feat: add sms send chain phase

2026-07-01 13:39:26 +08:00
parent 56f835a00f
commit 27bb2d798a
11 changed files with 981 additions and 2 deletions
@@ -0,0 +1,66 @@
+# 阶段 7：发送链路进度记录
+
+## 当前状态
+
+- 状态：进行中
+- 开始时间：2026-07-01
+
+## 计划步骤
+
+1. 创建阶段 7 计划和验收标准。已完成。
+2. 增加批量任务、手机号短信记录、API 批次、CMPP 提交会话、提交记录、回执记录、上行短信模型。已完成，`npm --prefix api run prisma:generate` 通过。
+3. 实现客户端批量任务创建、号码拆分和入队。已完成，`npm --prefix api run build` 通过。
+4. 实现 Send Worker、通道路由、Redis 限速和 Gateway SubmitCommand 投递。已完成，`npm --prefix api run build` 通过。
+5. 实现 submit resp、回执、上行短信和 72 小时超时补偿。已完成，`npm --prefix api run build` 通过。
+6. 实现任务进度统计查询。已完成，`npm --prefix api run build` 通过。
+7. 运行 Prisma generate、API build、阶段验证脚本和 API health smoke。已完成。
+
+## 验收记录
+
+- 数据模型：
+  - `SmsBatchTask`：客户端批量任务，只记录客户端批次。
+  - `SmsMessageRecord`：手机号维度短信记录。
+  - `SmsApiRequest`：API 调用批次记录。
+  - `CmppSubmitSession`、`SmsSubmitRecord`：CMPP 会话和提交记录。
+  - `SmsReceiptRecord`：短信回执记录。
+  - `SmsUplinkMessage`：上行短信记录。
+- 客户端接口：
+  - `POST /api/client/send/batch-tasks`
+  - `GET /api/client/send/batch-tasks`
+  - `GET /api/client/send/batch-tasks/:id`
+  - `GET /api/client/send/batch-tasks/:id/messages`
+- 管理端接口：
+  - `GET /api/admin/send/batch-tasks`
+  - `GET /api/admin/send/messages`
+  - `GET /api/admin/send/submit-records`
+  - `GET /api/admin/send/receipt-records`
+  - `GET /api/admin/send/uplink-messages`
+  - `POST /api/admin/send/batch-tasks/:id/enqueue`
+  - `POST /api/admin/send/timeouts/mark-unknown`
+- Gateway 事件接口：
+  - `POST /api/gateway/events/submit-result`
+  - `POST /api/gateway/events/receipt`
+  - `POST /api/gateway/events/uplink`
+- `npm run verify:phase7` 通过。
+  - 队列契约校验通过。
+  - Go Gateway `go test ./...` 通过。
+  - BullMQ Spike：15000 条消息、并发 500、端到端约 910.39 TPS，满足 500 条/秒指标。
+  - Prisma Client 生成通过。
+  - API build 通过。
+  - 前端 build 通过，仍存在 Vite chunk size warning。
+- API health smoke 通过：`/api/health` 返回 `ok`。
+
+## 阶段 7 验收状态
+
+- 平台创建的批量任务只记录客户端任务：已完成，`SmsBatchTask.sourceType` 默认为 `client`，API 调用记录进入 `SmsApiRequest`。
+- 平台任务、API 调用、CMPP 对接发送全部按手机号维度进入短信记录：已完成，`SmsMessageRecord` 为每个手机号生成独立 `messageId`。
+- 支持 submit resp、deliver 回执、上行短信、超时补偿：已完成，Gateway 事件接口分别写入提交记录、回执记录、上行记录，并支持未知状态超时补偿。
+
+## 结论
+
+阶段 7 已完成。下一阶段可进入阶段 8：查询、统计、验收。
+
+## 风险与说明
+
+- 本地未启动 PostgreSQL 时，仅执行 Prisma Client 生成和 TypeScript 构建，不执行数据库迁移。
+- Gateway 协议层继续复用阶段 0 的 gocmpp 评估结果和队列契约；阶段 7 在 NestJS 侧完成业务编排与队列投递。