111

docs/前端建设/C端H5页面接口矩阵.md

@@ -0,0 +1,176 @@
+# C 端 H5 页面接口矩阵
+
+> C 端是独立 H5，使用个人客户体系和 `/api/c/v1`，不复用管理 Web/H5 的账号密码登录、菜单或角色。
+
+## 一、C 端产品定位
+
+当前 C 端是“围绕资产提供查询、充值、购包和设备控制”的服务 H5，不是完整电商商城。
+
+客户通常从资产二维码、设备标签或外部链接进入，通过资产标识完成验证和微信身份登录。登录后可查看本人绑定的卡或设备，并围绕该资产操作。
+
+首期不应设计购物车、商品分类、收货地址簿等页面，因为当前没有对应后端能力。
+
+## 二、进入与登录流程
+
+```mermaid
+sequenceDiagram
+    participant U as 客户
+    participant H as C端H5
+    participant A as 后端
+    participant W as 微信
+
+    U->>H: 扫码或输入资产标识
+    H->>A: POST /auth/verify-asset
+    A-->>H: asset_token、资产类型、微信配置
+    H->>W: 公众号OAuth或小程序登录
+    W-->>H: code
+    H->>A: POST /auth/wechat-login 或 miniapp-login
+    A-->>H: JWT、客户信息、need_bind_phone
+    alt 需要绑定手机号
+        H->>A: POST /auth/send-code
+        H->>A: POST /auth/bind-phone
+    end
+    H->>A: GET /asset/info
+    A-->>H: 资产首页数据
+```
+
+关键约束：
+
+- `verify-asset` 支持 ICCID、虚拟号、MSISDN、IMEI、SN。
+- 设备内绑定卡不能以独立卡身份登录，应提示客户使用设备标识。
+- `asset_token` 是短期登录凭证，不等同于登录后的 JWT。
+- C 端 JWT 由签名和 Redis 当前 Token 双重校验；同一客户后登录可能使旧会话失效。
+- C 端没有 Refresh Token 接口，认证失效后重新走资产验证和微信登录。
+
+## 三、页面矩阵
+
+### 3.1 启动、登录和账户
+
+| 页面 | 输入 | 展示字段 | 操作 | 接口 |
+| --- | --- | --- | --- | --- |
+| 启动初始化 | 当前完整 URL | `app_id`、JSSDK 配置、环境错误 | 初始化微信能力 | `GET /wechat/appid`、`GET /wechat/jssdk-config` |
+| 资产验证 | 资产标识 | 资产类型、脱敏资产摘要、登录提示 | 验证并获取 `asset_token` | `POST /auth/verify-asset` |
+| 微信登录 | `asset_token`、OAuth `code` | 客户、是否新用户、是否需绑手机、Token | 公众号/小程序登录 | `POST /auth/wechat-login`、`POST /auth/miniapp-login` |
+| 手机号绑定 | 手机号、验证码 | 绑定结果 | 发送验证码、绑定、更换手机号 | `/auth/send-code`、`/auth/bind-phone`、`/auth/change-phone` |
+| 个人资料 | 无或昵称、头像 | 客户 ID、昵称、头像、手机号、状态 | 查看、更新 | `GET|PUT /profile` |
+| 退出登录 | 无 | 无 | 使当前 Token 失效 | `POST /auth/logout` |
+
+公开接口必须在没有 Bearer Token 时也能访问：微信配置、资产验证、微信/小程序登录、发送验证码。
+
+### 3.2 资产首页
+
+| 区块 | 关键展示字段 | 交互 | 接口 |
+| --- | --- | --- | --- |
+| 资产身份 | `asset_type`、主标识、ICCID/虚拟号/IMEI/SN、设备名 | 复制标识 | `GET /asset/info` |
+| 状态 | 业务状态、网络/在线状态、实名状态及名称、最后同步时间 | 刷新 | `GET /asset/info`、`POST /asset/refresh` |
+| 流量 | 总量、已用、剩余、使用比例、周期 | 查看套餐历史 | `GET /asset/info`、`GET /asset/package-history` |
+| 当前套餐 | 套餐名、类型、生效/到期、预计最终到期、排队信息 | 查看可购套餐 | `GET /asset/info` |
+| 钱包 | 余额、冻结金额、资产类型 | 充值、查看流水 | `GET /wallet/detail` |
+| 实名 | `effective_realname_policy`、`realname_required`、`realname_status` | 去实名 | `GET /asset/info`、`GET /realname/link` |
+| 支付能力 | `allowed_payment_methods` | 控制购买和充值按钮 | `GET /asset/info` |
+
+前端不得根据“卡还是设备”自行推断实名策略和支付方式。
+
+### 3.3 套餐购买
+
+| 页面 | 主要输入/筛选 | 展示字段 | 操作 | 接口 |
+| --- | --- | --- | --- | --- |
+| 可购套餐 | 资产标识、分页/类型（以 OpenAPI 为准） | 套餐 ID、名称、系列、类型、流量、周期、售价、上下架/可购状态、有效期说明 | 选择套餐 | `GET /asset/packages` |
+| 下单确认 | 资产标识、套餐 ID、支付方式、应用类型 | 资产、套餐、价格、实名要求、强充提示、允许支付方式 | 创建订单 | `POST /orders/create` |
+| 支付 | 订单 ID | 应付金额、支付方式、订单状态 | 钱包支付、微信支付、支付宝支付 | `POST /orders/:id/pay` |
+| 订单列表 | 状态、分页 | 订单号、资产、套餐、金额、支付方式、状态名称、创建时间 | 查看详情 | `GET /orders` |
+| 订单详情 | 订单 ID | 订单、套餐、资产、金额、支付、状态时间、权益结果 | 重新支付 | `GET /orders/:id` |
+
+调用顺序：
+
+1. 先查询 `/asset/info`，取得实名策略和允许支付方式。
+2. 查询 `/asset/packages`。
+3. 提交 `/orders/create`。
+4. 如果响应已包含强充支付参数，按响应拉起支付。
+5. 普通待支付订单调用 `/orders/:id/pay`。
+6. 钱包支付成功后直接刷新详情；第三方支付返回页面后重新查询订单详情。
+
+当前没有独立 C 端支付状态接口，也没有客户端主动取消订单接口。页面通过订单详情确认后端最终状态。
+
+### 3.4 钱包与充值
+
+| 页面 | 输入/筛选 | 展示字段 | 操作 | 接口 |
+| --- | --- | --- | --- | --- |
+| 钱包详情 | 资产标识 | 资产类型/ID、余额、冻结金额、可用余额 | 进入充值 | `GET /wallet/detail` |
+| 钱包流水 | 类型、时间、分页 | 流水号、变动金额、前后余额、业务类型、关联订单、状态、时间 | 查看关联业务 | `GET /wallet/transactions` |
+| 充值校验 | 资产标识、金额/场景 | 最低/最高金额、允许支付方式、实名/强充规则 | 进入充值 | `GET /wallet/recharge-check` |
+| 创建充值 | 资产、金额、支付方式、应用类型、幂等请求标识 | 充值单号、支付参数或支付宝链接、状态 | 拉起支付 | `POST /wallet/recharge` |
+| 充值记录 | 状态、分页 | 充值单号、金额、方式、支付状态、到账状态、时间 | 查看详情 | `GET /wallet/recharges`、`GET /recharge-orders` |
+| 充值详情 | 充值订单 ID | 金额、资产、渠道、第三方单号、支付/到账时间、状态名称 | 刷新状态 | `GET /recharge-orders/:id` |
+
+充值只使用接口返回的支付方式。钱包不能给自己钱包充值，因此强充和普通充值通常只提供微信、支付宝等第三方方式。
+
+### 3.5 实名
+
+| 页面 | 输入 | 展示字段 | 操作 | 接口 |
+| --- | --- | --- | --- | --- |
+| 实名引导 | 资产标识 | 是否需要实名、实名状态、模式、运营商、提示 | 获取实名链接 | `GET /realname/link` |
+
+可能的策略：
+
+- `none`：无需实名。
+- `before_order`：未实名时禁止充值或购买。
+- `after_order`：可先购买，支付后继续引导实名。
+
+页面必须使用 `effective_realname_policy`，不能只读资产原始策略。
+
+### 3.6 设备控制
+
+仅设备资产显示该模块。
+
+| 页面/动作 | 输入 | 展示字段 | 接口 |
+| --- | --- | --- | --- |
+| 卡槽列表 | 设备标识 | 卡槽号、ICCID、运营商、网络/实名/激活状态、当前卡 | `GET /device/cards` |
+| 切卡 | 设备标识、目标卡/卡槽 | 操作结果、当前卡 | `POST /device/switch-card` |
+| 配置 WiFi | SSID、密码等 DTO 字段 | 操作结果 | `POST /device/wifi` |
+| 重启 | 设备标识 | 操作结果 | `POST /device/reboot` |
+| 恢复出厂 | 设备标识、确认 | 操作结果 | `POST /device/factory-reset` |
+
+重启、切卡、WiFi、恢复出厂都应防止重复点击；恢复出厂必须二次确认。
+
+### 3.7 换货
+
+| 页面 | 输入 | 展示字段 | 操作 | 接口 |
+| --- | --- | --- | --- | --- |
+| 待处理换货提醒 | 当前登录资产 | 换货单号、旧资产、状态、提交期限 | 进入收货信息 | `GET /exchange/pending` |
+| 收货信息 | 收件人、手机号、地区、详细地址 | 换货摘要 | 提交 | `POST /exchange/:id/shipping-info` |
+
+C 端不能创建、发货、完成或取消换货，只负责查询待补资料换货单并提交收货信息。
+
+### 3.8 通知
+
+| 页面 | 筛选/输入 | 展示字段 | 操作 | 接口 |
+| --- | --- | --- | --- | --- |
+| 未读提示 | 无 | 未读数 | 打开通知中心 | `GET /notifications/unread-count` |
+| 通知列表 | 类型、状态、分页 | 类型、标题、内容、风险、关联资源、时间、已读状态 | 标记已读 | `GET /notifications`、`PUT /notifications/:id/read` |
+| 全部已读 | 无 | 无 | 全部标记已读 | `PUT /notifications/read-all` |
+
+## 四、全局交互状态
+
+C 端至少统一处理：
+
+- 首次加载、局部刷新、空数据和网络异常。
+- Token 失效后回到资产验证入口，并保留当前进入链接。
+- 403 表示当前客户未绑定该资产或无权操作，不显示“资产不存在”的差异提示。
+- 支付取消、支付失败、支付结果未知和支付成功。
+- Gateway 操作已提交但结果未知，禁止无限自动重试。
+- 订单、充值、换货使用后端 `status_name` 展示中文状态。
+
+## 五、当前缺口
+
+以下页面没有现成接口支撑，不纳入首期：
+
+- 独立商品详情和商品分类。
+- 购物车。
+- 收货地址簿。
+- 客户主动取消订单。
+- 客户主动申请退款。
+- 客户资产列表和主动切换当前资产。
+- 独立支付状态查询。
+
+若产品要求其中任一能力，应先作为独立后端用例设计，不能只在前端模拟。