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

C 端 H5 页面接口矩阵

C 端是独立 H5，使用个人客户体系和 /api/c/v1，不复用管理 Web/H5 的账号密码登录、菜单或角色。

一、C 端产品定位

当前 C 端是“围绕资产提供查询、充值、购包和设备控制”的服务 H5，不是完整电商商城。

客户通常从资产二维码、设备标签或外部链接进入，通过资产标识完成验证和微信身份登录。登录后可查看本人绑定的卡或设备，并围绕该资产操作。

首期不应设计购物车、商品分类、收货地址簿等页面，因为当前没有对应后端能力。

二、进入与登录流程

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
退出登录	无	无	使当前 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 展示中文状态。

五、当前缺口

以下页面没有现成接口支撑，不纳入首期：

• 独立商品详情和商品分类。
• 购物车。
• 收货地址簿。
• 客户主动取消订单。
• 客户主动申请退款。
• 客户资产列表和主动切换当前资产。
• 独立支付状态查询。

若产品要求其中任一能力，应先作为独立后端用例设计，不能只在前端模拟。