break
5ba227eff5
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 1m8s
7.0 KiB
7.0 KiB
前端建设总览
状态：前端尚未创建，本目录用于统一产品、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 请求内完成：
- 前端获取对象存储预签名地址。
- 文件直传对象存储。
- 将
file_key和业务参数提交给任务接口。 - 获得任务 ID。
- 轮询列表或详情。
- 展示总数、成功数、失败数和逐行失败原因。
三、前端建设产物
四、契约优先级
出现冲突时按以下顺序判断：
- 当前代码中的路由、DTO 和权限实现。
docs/admin-openapi.yaml生成契约。- 本目录的业务和页面说明。
- 历史功能总结和历史流程图。
历史文档仍可能出现 /api/admin/login、/api/h5/login 等旧路径。当前统一认证入口是 /api/auth/*，新前端不得继续使用旧路径。
五、当前启动前阻塞项
- 管理端逐接口权限门禁尚未形成统一闭环，前端隐藏菜单不能替代后端鉴权。
- 企业账号的数据范围需要使用真实 Token 对企业、资产和授权接口做越权验证。
- 管理 H5 的首期页面范围尚未最终确认；本文给出任务型 MVP 建议，不默认复制全部 Web 页面。
- C 端目前是“围绕当前资产直接购买”的服务 H5，没有购物车、地址簿、独立商品详情和主动退款等完整商城能力。
- 前端技术栈尚未落地，先完成选型决策再创建脚手架。