# 阶段 5 账户计费进度记录

## 2026-07-01

### 阶段计划

- 已创建 `docs/phase-5-billing-plan.md`。
- 阶段 5 聚焦账户计费闭环，不实现完整发送链路。

### 验证记录

- 创建阶段 5 计划文档、扩展 Prisma 充值订单和短信计费记录模型后执行：
  - `cd api && npm run prisma:generate`：通过。
  - `cd api && npm run build`：通过。
- 实现 Billing 账务动作 API 后执行：
  - `cd api && npm run prisma:generate`：通过。
  - `cd api && npm run build`：通过。
  - API health 冒烟：`GET http://127.0.0.1:3101/api/health` 返回 `{"status":"ok","service":"cmpp-platform-api",...}`。
- 阶段 5 完整验证：
  - `npm run verify:phase5`：通过。
  - BullMQ 本轮端到端 TPS：543.91，满足 500 条/秒验证线。
  - Prisma Client 生成成功。
  - API 构建成功。
  - 前端构建成功，仍有 Vite chunk 大小告警，不阻塞。

### 已完成

- Prisma 账户计费模型补强：
  - `RechargeOrder`
  - `SmsBillingRecord`
- Billing 账务动作：
  - 套餐购买/人工充值：创建 `RechargeOrder` 并写入 `AccountTransaction`。
  - 发送费用预估：按 70/67 字规则计算计费条数、总条数和金额。
  - 账户校验：检查余额+授信额度和套餐余量。
  - 冻结：写入 `frozen` 流水。
  - 扣费：写入 `charged` 流水。
  - 解冻：写入 `released` 流水。
  - 退费：写入 `refunded` 流水。
  - 调整：写入 `adjusted` 流水。
  - 短信计费记录：创建和查询 `SmsBillingRecord`。
- 运营端接口：
  - `GET/POST /api/admin/billing/recharges`
  - `POST /api/admin/billing/estimate`
  - `POST /api/admin/billing/check`
  - `POST /api/admin/billing/freeze`
  - `POST /api/admin/billing/charge`
  - `POST /api/admin/billing/release`
  - `POST /api/admin/billing/refund`
  - `POST /api/admin/billing/adjust`
  - `GET/POST /api/admin/billing/sms-billing-records`
- 客户端接口：
  - `GET/POST /api/client/billing/orders`
  - `POST /api/client/billing/estimate`

### 下一步

1. 输出阶段 6 实施计划和验收标准。
2. 实现风控规则、默认阈值、规则命中记录、短信审核、审核原因展示和拒绝原因返回。

### 阶段 5 验收状态

| 验收项 | 状态 | 说明 |
| --- | --- | --- |
| Prisma Client 生成成功 | 已完成 | `npm run prisma:generate` 通过。 |
| API 构建成功 | 已完成 | `npm run build` 在 `api` 下通过。 |
| 套餐、充值记录、账务流水、计费规则 API 存在 | 已完成 | 已有套餐、充值订单、账户、流水、规则接口。 |
| 费用预估 API 存在 | 已完成 | `POST /api/admin/billing/estimate` 与 `POST /api/client/billing/estimate` 已实现。 |
| 账户校验 API 存在 | 已完成 | `POST /api/admin/billing/check` 已实现。 |
| 冻结、扣费、解冻、退费 API 存在 | 已完成 | `freeze/charge/release/refund` 已实现。 |
| 短信计费记录 API 存在 | 已完成 | `sms-billing-records` 查询和创建已实现。 |
| 阶段完整验证 | 已完成 | `npm run verify:phase5` 通过。 |

### 阶段 5 结论

阶段 5 已完成。第一版可以进入阶段 6 风控与审核。