161 lines
7.2 KiB
Markdown
161 lines
7.2 KiB
Markdown
# 阶段 0 技术 Spike 最小工程计划
|
||
|
||
## 目标
|
||
|
||
阶段 0 只验证第一版最大技术风险：NestJS 入队、Go Gateway 消费、模拟 CMPP 提交、submit resp、deliver 回执、上行事件回传、断线重连和 500 条/秒链路能力。
|
||
|
||
本阶段不实现完整业务审核、风控、计费、报备、路由后台，也不从零手写完整 CMPP 协议栈。
|
||
|
||
## 1. 目录结构建议
|
||
|
||
当前仓库先保留现有 React + TypeScript + Vite 原型作为根目录前端。阶段 0 建议以最小增量方式补齐后端和网关 Spike 目录：
|
||
|
||
```text
|
||
.
|
||
├── docs/
|
||
│ ├── contracts/
|
||
│ │ ├── gateway-queue-messages.schema.json
|
||
│ │ └── examples/
|
||
│ ├── phase-0-technical-spike-plan.md
|
||
│ └── phase-0-spike-progress.md
|
||
├── api/
|
||
│ ├── README.md
|
||
│ └── src/
|
||
│ └── spike/
|
||
│ └── queue-contracts/
|
||
├── gateway/
|
||
│ ├── README.md
|
||
│ ├── cmd/
|
||
│ │ ├── gateway/
|
||
│ │ └── smsc-simulator/
|
||
│ └── internal/
|
||
│ ├── cmpp/
|
||
│ ├── queue/
|
||
│ ├── connection/
|
||
│ ├── tracker/
|
||
│ └── metrics/
|
||
└── tools/
|
||
└── spike/
|
||
└── validate-gateway-queue-contract.mjs
|
||
```
|
||
|
||
阶段 1 再决定是否迁移为正式 monorepo：
|
||
|
||
- `web/`：当前 React 原型。
|
||
- `api/`：NestJS + Prisma + BullMQ。
|
||
- `gateway/`：Go CMPP Gateway。
|
||
- `infra/`：PostgreSQL、Redis、MinIO、Prometheus、Grafana 的 compose 与部署配置。
|
||
|
||
## 2. NestJS 与 Go Gateway 队列消息格式
|
||
|
||
阶段 0 采用 Redis + BullMQ 作为通信基线。NestJS 只负责投递已经完成业务校验和路由决策后的发送指令；Go Gateway 只负责协议提交和事件回传。
|
||
|
||
### 队列命名
|
||
|
||
- `cmpp.submit.commands`：NestJS -> Go Gateway，单号码发送指令。
|
||
- `cmpp.submit.results`：Go Gateway -> NestJS，submit resp 结果。
|
||
- `cmpp.receipt.events`：Go Gateway -> NestJS，deliver 回执事件。
|
||
- `cmpp.uplink.events`：Go Gateway -> NestJS，上行短信事件。
|
||
|
||
### 统一信封
|
||
|
||
每条消息必须包含：
|
||
|
||
- `schemaVersion`：当前固定为 `v1`。
|
||
- `messageType`：消息类型。
|
||
- `traceId`：贯穿 API、队列、网关、回执的链路 ID。
|
||
- `messageId`：平台单号码短信 ID，全局唯一。
|
||
- `channelId`：业务后台选定的通道 ID。
|
||
- `createdAt`：ISO 8601 时间。
|
||
|
||
### 发送指令
|
||
|
||
`SubmitCommand` 由 NestJS 或 Send Worker 产生。必须包含 `tenantId`、`applicationId`、`submitId`、`phoneNumber`、`content`、`signature`、`templateId`、`billingUnits`、`route`、`cmpp` 和 `retry`。
|
||
|
||
Go Gateway 不根据签名、模板、账户余额做业务判断，只读取 `route.cmppAccountCode`、`cmpp.serviceId`、`cmpp.srcId`、`cmpp.registeredDelivery`、`cmpp.msgFmt` 等协议提交所需字段。
|
||
|
||
### 结果和事件
|
||
|
||
- `SubmitResult` 必须回传 `sequenceId`、`gatewayMessageId`、`submitStatus`、`submittedAt`。
|
||
- `ReceiptEvent` 必须回传 `gatewayMessageId`、`sequenceId`、`receiptStatus`、`deliveredAt`、`rawStatus`。
|
||
- `UplinkEvent` 必须回传 `phoneNumber`、`destId`、`content`、`receivedAt`、`sequenceId`。
|
||
|
||
详细结构以 `docs/contracts/gateway-queue-messages.schema.json` 为准。
|
||
|
||
## 3. Go Gateway 最小能力清单
|
||
|
||
阶段 0 最小 Go Gateway 只做以下能力：
|
||
|
||
1. 读取一个通道配置：网关地址、端口、企业代码、账号、密码、接入号、CMPP 版本、窗口大小、心跳间隔、重连间隔。
|
||
2. 基于 gocmpp 或评估后的协议库完成 connect、active test、submit、deliver、terminate。
|
||
3. 消费 `cmpp.submit.commands`，提交到模拟 SMSC。
|
||
4. 将 submit resp 写入 `cmpp.submit.results`。
|
||
5. 将 deliver 回执写入 `cmpp.receipt.events`。
|
||
6. 将上行短信写入 `cmpp.uplink.events`。
|
||
7. 维护 `messageId -> sequenceId -> gatewayMessageId` 的追踪映射。
|
||
8. 支持断线重连，重连后继续消费后续消息。
|
||
9. 暴露最小健康检查和指标：连接状态、队列积压、提交 TPS、submit 成功率、回执延迟、重连次数。
|
||
10. 支持模拟 SMSC：正常响应、慢响应、断线、重复回执、窗口满。
|
||
|
||
## 4. gocmpp 与 cmpp-gateway 技术评估任务
|
||
|
||
评估对象：
|
||
|
||
- `bigwhite/gocmpp`：优先评估为协议层依赖。
|
||
- `JoeCao/cmpp-gateway`：只作为连接管理、重连、SEQID/MSGID 追踪和模拟器设计参考。
|
||
|
||
任务清单：
|
||
|
||
1. License：确认依赖许可是否允许第一版商业项目使用。
|
||
2. 维护活跃度：确认最近提交、Issue、PR、Go module 支持情况。
|
||
3. 协议覆盖：确认 CMPP 2.0/3.0、connect、submit、deliver、active test、terminate 支持情况。
|
||
4. 编解码可靠性：验证长短信、UCS2、GBK、状态报告、上行短信解析。
|
||
5. 连接模型：评估长连接、心跳、窗口、并发 submit、断线重连。
|
||
6. 追踪能力：验证 sequenceId、msgId、平台 messageId 的映射方案。
|
||
7. 模拟器：复用或参考模拟 SMSC 的响应、慢响应、断线和重复回执能力。
|
||
8. 改造边界：判断直接依赖、轻量 fork、或只参考实现的取舍。
|
||
9. 风险清单：列出协议层缺口、生产部署风险、测试补充项。
|
||
|
||
## 5. 500 条/秒 Spike 压测指标
|
||
|
||
压测只验证链路调度能力，不验证完整业务规则。
|
||
|
||
### 场景
|
||
|
||
1. NestJS 批量投递 30 秒，共 15000 条发送指令。
|
||
2. Go Gateway 消费队列并提交到模拟 SMSC。
|
||
3. 模拟 SMSC 立即返回 submit resp，并在 1 到 3 秒内返回 deliver。
|
||
4. 重复执行单连接和多连接两个场景。
|
||
5. 插入异常场景：模拟 SMSC 慢响应、短暂断线、重复回执。
|
||
|
||
### 指标
|
||
|
||
- 入队吞吐：P50、P95、P99，每秒入队数必须稳定达到 500。
|
||
- 消费吞吐：每秒消费并提交数，30 秒平均不低于 500。
|
||
- 端到端延迟：入队到 submit resp P95 小于 2 秒。
|
||
- 回执延迟：deliver 到 NestJS 消费 P95 小于 10 秒。
|
||
- 错误率：submit command 处理失败率小于 0.1%。
|
||
- 重试率：异常场景下可观测且不造成重复最终状态。
|
||
- 队列积压：压测停止后 30 秒内归零。
|
||
- 资源指标：CPU、内存、Redis ops、连接重连次数。
|
||
- 幂等指标：重复回执只产生一条最终状态更新，多余回执进入历史记录。
|
||
|
||
## 6. 阶段 0 验收标准
|
||
|
||
1. 跑通一条模拟短信链路：NestJS 入队 -> Go Gateway 提交 -> submit resp -> deliver 回执 -> NestJS 更新状态。
|
||
2. Go Gateway 断线后可重连，并能继续消费后续消息。
|
||
3. 所有消息具备 `traceId`、`messageId`、`channelId`、`sequenceId` 或可追踪映射。
|
||
4. 队列消息 Schema、示例消息和校验脚本通过。
|
||
5. 完成 gocmpp 与 JoeCao/cmpp-gateway 评估记录，明确最终依赖方式。
|
||
6. 完成 500 条/秒压测报告，包含瓶颈、资源使用和下一阶段优化建议。
|
||
7. 文档记录 Go Gateway 哪些能力复用协议库，哪些服务层能力由本项目自研。
|
||
|
||
## 阶段 0 执行顺序
|
||
|
||
1. 创建阶段 0 计划文档、队列消息 Schema、示例消息和校验脚本。
|
||
2. 创建 Go Gateway Spike 骨架和模拟 SMSC 骨架。
|
||
3. 创建 NestJS Spike 骨架，完成 BullMQ 入队和事件消费。
|
||
4. 接入 Redis 本地环境，跑通模拟链路。
|
||
5. 评估 gocmpp 与 JoeCao/cmpp-gateway。
|
||
6. 完成 500 条/秒压测脚本和报告。
|