junhong_cmp_fiber/docs/前端建设

前端建设总览

状态：前端尚未创建，本目录用于统一产品、UI、前端和后端对系统业务、页面范围与接口契约的理解。

接口字段的唯一权威来源是 docs/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 卡；资产由平台导入后，沿店铺层级进行分配，并可进一步授权给企业使用。

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. 展示总数、成功数、失败数和逐行失败原因。

三、前端建设产物

• 前端选型与代码组织
• 管理 Web 与管理 H5 页面接口矩阵
• C 端 H5 页面接口矩阵
• 权限矩阵与接口联调契约
• 完整 OpenAPI
• 现有系统流程图

四、契约优先级

出现冲突时按以下顺序判断：

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. 前端技术栈尚未落地，先完成选型决策再创建脚手架。