diff --git a/docs/superpowers/specs/2026-08-31-backend-new-api-frontend-align-design.md b/docs/superpowers/specs/2026-08-31-backend-new-api-frontend-align-design.md new file mode 100644 index 0000000..f881585 --- /dev/null +++ b/docs/superpowers/specs/2026-08-31-backend-new-api-frontend-align-design.md @@ -0,0 +1,107 @@ +# 前端对接后台新增 API 设计 + +日期:2026-08-31 +范围:只改 `laic-frontend`,不改 `laic-backend`,不改 Vite 代理目标(继续远程网关)。 + +## 背景 + +后台已新增/调整账户计费能力(流量套餐、微信支付、SIM 充值订单)。前端账户中心仍按旧流程: + +- 流量:`POST /v1/account/traffic/orders` 直接传 `amountGb`,文案仍是“管理员人工确认” +- SIM:页面写死“运营商通道未接入”,且 `urls.js` 仍有错误路径 `/sim-cards/:id/recharge` +- 缺少:`traffic-packages`、`sim-packages`、`payments`、`sim-recharge-orders`、取消订单、`auth/refresh` + +协议层(Bearer、`code===200`、分页 `pageNum/pageSize/records/total`)已对齐,本设计只补齐路径与账户主流程。 + +## 目标 + +1. `urls.js` 与后台 `route/route.go` 账户相关新接口对齐 +2. 账户中心流量购买、SIM 充值改为:选套餐 → 创建业务订单 → 创建微信支付 +3. 支持取消未支付订单 +4. 不改后台,不切本地代理 + +## 非目标 + +- 不启动/改造 `laic-backend` +- 不改 Vite `/api` 代理目标 +- 不把“设备操作记录”页改成 `/v1/logs/operation`(该页语义仍是指令记录,继续 `/v1/commands`) +- 不接 WebSocket `/v1/ws/monitor` +- 不做 admin `/v1/admin/traffic/*` 管理台 + +## API 对齐 + +### 新增/修正 URL + +| 常量 | 方法 | 路径 | +|---|---|---| +| `AUTH_REFRESH` | POST | `/v1/auth/refresh` | +| `TRAFFIC_PACKAGES` | GET | `/v1/account/traffic-packages` | +| `TRAFFIC_ORDER` | DELETE | `/v1/account/traffic/orders/:id` | +| `PAYMENTS` | POST | `/v1/account/payments` | +| `PAYMENT` | GET | `/v1/account/payments/:id` | +| `SIM_PACKAGES` | GET | `/v1/account/sim-packages` | +| `SIM_CARD_RECHARGE_ORDERS` | POST | `/v1/account/sim-cards/:id/recharge-orders` | +| `SIM_RECHARGE_ORDER` | GET/DELETE | `/v1/account/sim-recharge-orders/:id` | + +删除错误常量:`SIM_CARD_RECHARGE = /sim-cards/:id/recharge`。 + +### 请求体约定(以后台 VO 为准) + +- 创建流量订单:`{ packageId }`(可保留 `amountGb` 兼容,但 UI 以套餐为准) +- 创建 SIM 充值订单:`{ packageId }` +- 创建支付:`{ businessType: 'traffic_order' | 'sim_recharge_order', businessOrderId }` + +### 字段映射注意 + +- 流量订单:继续用 `payStatus` / `totalPrice` / `amountGb` +- SIM 充值订单:后台是 `paymentStatus` / `fulfillmentStatus` / `totalFeeFen`;列表若仍读 `sim-recharge-logs`,保持旧字段;若展示订单详情,需映射新字段 +- 支付金额:`totalFeeFen`(分)→ 前端展示元 + +## 账户中心交互 + +### 云媒体流量 + +1. 进入流量 Tab:拉取 `TRAFFIC_PACKAGES` + 余额 + 订单 + 消费 +2. 购买区由“输入 GB”改为套餐选择(名称、流量、价格、有效期) +3. 点击购买: + - `POST TRAFFIC_ORDERS { packageId }` + - `POST PAYMENTS { businessType:'traffic_order', businessOrderId }` + - toast 展示支付创建结果;若返回 `providerPayload`,按现有可展示方式提示(二维码/链接能力以返回为准,不做额外支付 SDK) +4. 未支付订单提供“取消”:`DELETE TRAFFIC_ORDER(id)` +5. 文案从“等待管理员确认”改为“创建订单并发起支付” + +### 通信卡 + +1. 拉取 `SIM_PACKAGES` +2. 每张卡操作从“未接入”改为“充值” +3. 充值弹窗选套餐后: + - `POST SIM_CARD_RECHARGE_ORDERS(simId) { packageId }` + - `POST PAYMENTS { businessType:'sim_recharge_order', businessOrderId }` +4. 保留充值记录表(`SIM_RECHARGE_LOGS`) +5. 未支付充值订单可取消:`DELETE SIM_RECHARGE_ORDER(id)`(若 UI 有入口) + +### 其他 + +- `AUTH_REFRESH` 先进入 `urls.js`;本轮不强制做 401 自动续期 +- 操作日志页保持 `/v1/commands` + +## 错误处理 + +- 继续走现有 `http.js` 拦截器 toast +- 支付未开通(后台 `ErrPaymentDisabled`)时,页面明确提示“支付暂不可用” +- 套餐列表为空时,禁用下单按钮并提示 + +## 验证 + +远程网关环境下: + +1. 账户中心可加载流量套餐、SIM 套餐 +2. 流量:选套餐 → 创建订单 → 创建支付(成功或明确业务错误) +3. SIM:选卡选套餐 → 创建充值订单 → 创建支付 +4. 未支付订单可取消 +5. 原有资料/会话/发票/余额查询不回归 + +## 风险 + +- 远程环境若尚未发布对应新路由,前端会拿到 404;需以实际网关响应确认 +- 支付 `providerPayload` 形态未在前端固化,本轮只做最小展示/提示,不引入微信支付 JS SDK