break
5ba227eff5
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 1m8s
147 lines
7.0 KiB
Markdown
147 lines
7.0 KiB
Markdown
# 前端建设总览
|
||
|
||
> 状态：前端尚未创建，本目录用于统一产品、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. 前端技术栈尚未落地，先完成选型决策再创建脚手架。
|