# 前端建设总览

> 状态：前端尚未创建，本目录用于统一产品、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. 前端技术栈尚未落地，先完成选型决策再创建脚手架。