111

docs/前端建设/README.md

@@ -0,0 +1,146 @@
+# 前端建设总览
+
+> 状态：前端尚未创建，本目录用于统一产品、UI、前端和后端对系统业务、页面范围与接口契约的理解。
+>
+> 接口字段的唯一权威来源是 [`docs/admin-openapi.yaml`](../admin-openapi.yaml)。本目录只说明业务语义、页面需要什么、接口按什么顺序调用，不复制完整 DTO。
+
+## 一、已经确认的产品形态
+
+系统包含三个前端使用场景，不存在独立的“代理端”或“企业端”后端：
+
+| 使用场景 | 形态 | 登录用户 | 后端接口 |
+| --- | --- | --- | --- |
+| 管理 Web | 桌面浏览器管理系统 | 超级管理员、平台账号、代理账号、企业账号 | `/api/auth`、`/api/admin` |
+| 管理 H5 | 移动浏览器管理系统 | 超级管理员、平台账号、代理账号、企业账号 | `/api/auth`、`/api/admin` |
+| C 端 H5 | 面向个人客户的资产服务 H5 | 个人客户 | `/api/c/v1` |
+
+管理 Web 和管理 H5 的菜单不是按“平台端、代理端、企业端”写死，而由登录账号的角色权限决定。账号身份只决定组织关系和数据范围：
+
+- 超级管理员：不分配角色，获取当前终端全部启用权限。
+- 平台账号：可分配多个平台角色，数据范围为全平台。
+- 代理账号：归属一个店铺，可分配一个客户角色，数据范围为本店及下级店铺。
+- 企业账号：归属一个企业，可分配一个客户角色，数据范围应限制为本企业。
+- 个人客户：独立用户体系，不参与管理端 RBAC，通过客户与资产绑定控制数据范围。
+
+登录请求中的 `device` 决定返回哪一套菜单：
+
+- 管理 Web 传 `web`。
+- 管理 H5 传 `h5`。
+- 权限记录的 `platform=all` 同时适用于两端。
+
+## 二、系统业务全景
+
+系统管理两类核心资产：IoT 卡和设备。设备可以绑定多张 IoT 卡；资产由平台导入后，沿店铺层级进行分配，并可进一步授权给企业使用。
+
+```mermaid
+flowchart LR
+    A[平台配置运营商、套餐和规则] --> B[导入 IoT 卡和设备]
+    B --> C[分配给代理店铺]
+    C --> D[代理向直属下级继续分配]
+    C --> E[授权给企业客户使用]
+    C --> F[个人客户绑定资产]
+    D --> F
+    E --> G[企业查看被授权资产]
+    F --> H[C 端查询流量、实名和套餐]
+    H --> I[充值或购买套餐]
+    I --> J[支付回调和套餐生效]
+    J --> K[轮询流量、状态和实名]
+    J --> L[生成钱包流水、差价和佣金]
+    J --> M[退款、换货和通知]
+    L --> N[代理提现或继续采购]
+```
+
+### 2.1 身份与组织
+
+`Account` 是管理端账号；`Shop` 是代理组织；`Enterprise` 是企业组织；`PersonalCustomer` 是独立 C 端客户。
+
+- 店铺最多形成 7 级上下级关系。
+- 代理账号必须关联一个店铺。
+- 企业账号必须关联一个企业。
+- 企业可以归属于平台，也可以归属于某个店铺。
+- 个人客户通过微信身份、手机号和资产绑定建立使用关系。
+
+### 2.2 资产
+
+- IoT 卡可独立使用，也可绑定在设备卡槽中。
+- 卡和设备均有平台/店铺归属、业务状态、实名策略、套餐系列等信息。
+- 设备分配时，其绑定卡需要同步处理归属。
+- 企业授权是使用权，不改变资产的店铺归属。
+- C 端客户绑定资产后，只能操作本人已绑定的资产。
+
+### 2.3 套餐与分销
+
+平台先创建套餐系列和套餐，再将系列、套餐和价格逐级下发给店铺。
+
+- 上级只能将自己有权销售的套餐分配给下级。
+- 代理通常只能向直属下级分配。
+- 下级成本价不能低于上级成本价。
+- 主套餐在已有生效主套餐时进入排队。
+- 加油包要求已有主套餐，并立即生效，其有效期跟随主套餐。
+- 下架套餐默认不再进入新客户可购列表；符合历史续费条件的资产可继续按已有套餐 ID 下单。
+
+### 2.4 订单与支付
+
+订单来源包括管理端代购、C 端自助购买和批量购买。
+
+- 管理端先调用购买校验，再创建订单。
+- C 端先查询资产信息和可购套餐，再创建订单。
+- 支付方式由后端按资产类型、业务场景和配置计算，前端使用 `allowed_payment_methods`。
+- 钱包支付同步完成扣款；微信、支付宝等第三方支付依赖服务端回调更新状态。
+- 支付成功后，后端负责套餐激活、排队、佣金和通知，前端不能自行修改业务状态。
+
+### 2.5 钱包、佣金与提现
+
+系统存在资产钱包和代理主钱包两套资金语义：
+
+- 资产钱包：归属于卡或设备，供 C 端充值和购买套餐。
+- 代理主钱包：归属于店铺，用于代理采购、代购和经营结算。
+- 佣金钱包/记录：记录差价收益和一次性佣金。
+- 提现：代理提交申请，系统冻结金额，审批完成后结算或解冻。
+- 所有金额接口以“分”的整数为准，前端只在展示层转换为元。
+
+### 2.6 售后
+
+- 退款：围绕原订单、实付金额、套餐权益和审批状态处理。
+- 换货：后台建单，C 端填写收货信息，后台发货并选择是否迁移旧资产权益。
+- 套餐失效：退款或人工任务只失效目标订单产生的权益。
+- 通知：管理账号和个人客户使用两套通知读取接口。
+
+### 2.7 异步任务
+
+导入、导出、批量购买、批量分配和部分扫描任务不在单次 HTTP 请求内完成：
+
+1. 前端获取对象存储预签名地址。
+2. 文件直传对象存储。
+3. 将 `file_key` 和业务参数提交给任务接口。
+4. 获得任务 ID。
+5. 轮询列表或详情。
+6. 展示总数、成功数、失败数和逐行失败原因。
+
+## 三、前端建设产物
+
+- [前端选型与代码组织](前端选型与代码组织.md)
+- [管理 Web 与管理 H5 页面接口矩阵](管理端页面接口矩阵.md)
+- [C 端 H5 页面接口矩阵](C端H5页面接口矩阵.md)
+- [权限矩阵与接口联调契约](权限矩阵与接口联调契约.md)
+- [完整 OpenAPI](../admin-openapi.yaml)
+- [现有系统流程图](../系统流程图/)
+
+## 四、契约优先级
+
+出现冲突时按以下顺序判断：
+
+1. 当前代码中的路由、DTO 和权限实现。
+2. `docs/admin-openapi.yaml` 生成契约。
+3. 本目录的业务和页面说明。
+4. 历史功能总结和历史流程图。
+
+历史文档仍可能出现 `/api/admin/login`、`/api/h5/login` 等旧路径。当前统一认证入口是 `/api/auth/*`，新前端不得继续使用旧路径。
+
+## 五、当前启动前阻塞项
+
+1. 管理端逐接口权限门禁尚未形成统一闭环，前端隐藏菜单不能替代后端鉴权。
+2. 企业账号的数据范围需要使用真实 Token 对企业、资产和授权接口做越权验证。
+3. 管理 H5 的首期页面范围尚未最终确认；本文给出任务型 MVP 建议，不默认复制全部 Web 页面。
+4. C 端目前是“围绕当前资产直接购买”的服务 H5，没有购物车、地址簿、独立商品详情和主动退款等完整商城能力。
+5. 前端技术栈尚未落地，先完成选型决策再创建脚手架。