docs: add frontend alignment design for backend billing APIs

Capture the approved frontend-only plan to wire traffic packages,
SIM recharge orders, and payments without changing the backend.

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