# 前端对接后台新增 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