233 lines
12 KiB
Markdown
233 lines
12 KiB
Markdown
# SendChain Service 职责拆分专项方案
|
||
|
||
- 方案日期：2026-08-28
|
||
- 对应整改项：`C8 SendChain Service 职责拆分`
|
||
- 当前范围：只制定方案，不在本轮实施发送链重构
|
||
- 适用环境：本地和测试环境 `100.93.204.60`
|
||
- 禁止范围：未经新授权不得部署预生产；不得用生产短信验证重构
|
||
|
||
## 1. 当前状态与问题
|
||
|
||
当前发送链已经存在一层门面 `send-submission.service.ts`，但两个实现类仍然过大：
|
||
|
||
| 文件 | 当前规模 | 集中职责 |
|
||
|---|---:|---|
|
||
| `send-inbound-entry.service.ts` | 约1852行、84.2 KiB | CMPP认证、入站持久化、长短信、Inbox claim、企业微批、配额、模板/引流匹配、风控、指标 |
|
||
| `send-gateway-submit.service.ts` | 约1159行、52.2 KiB | BullMQ Worker、批处理、路由、签名报备、限速、Submit命令、Outbox、任务进度、资源回收 |
|
||
| `send-submission.service.ts` | 约280行 | 对外门面、跨服务回调与编排 |
|
||
|
||
主要风险不是文件长度本身，而是以下行为边界在同一个类中耦合：
|
||
|
||
- PostgreSQL事务与 advisory lock 顺序。
|
||
- Inbox claim、租约、重试与恢复。
|
||
- 长短信分片幂等和完整消息恢复。
|
||
- 计费冻结、扣费、释放与失败补偿。
|
||
- 路由、签名报备、通道限速和主备策略。
|
||
- Submit Outbox 的租约、发布、确认和重复消费。
|
||
- 消息状态与批量任务进度的单飞/尾随刷新。
|
||
|
||
因此专项必须以“行为锁定后机械提取”为主，不允许借拆分类的机会同时重写SQL、事务或状态机。
|
||
|
||
## 2. 拆分目标
|
||
|
||
1. `SendSubmissionService` 只保留稳定门面和跨子域编排。
|
||
2. 每个子服务只有一个主要变化原因，建议控制在500行以内；复杂持久化服务可放宽至700行，但不得继续混合Worker生命周期、业务校验和发布协议。
|
||
3. 保持现有公开方法签名、队列名、Stream字段、幂等键、数据库状态和错误码不变。
|
||
4. 拆分过程中不改变吞吐参数、路由权重、计费口径和定时器周期。
|
||
5. 每一步均可独立回退，不要求一次性完成全部拆分。
|
||
|
||
## 3. 目标结构
|
||
|
||
建议新增以下内部服务，目录仍保留在 `api/src/send-chain/`，暂不建立更深目录，避免一次性路径迁移过大。
|
||
|
||
### 3.1 入站侧
|
||
|
||
| 目标服务 | 从现有文件提取的职责 | 明确不负责 |
|
||
|---|---|---|
|
||
| `inbound-authentication.service.ts` | `authenticateInboundApplication`、连接认证结果记录、IP白名单和接口状态检查 | 消息持久化、计费 |
|
||
| `inbound-long-message.service.ts` | 分片收集、完成判定、超时清理、已完成结果恢复 | 普通单条业务创建 |
|
||
| `inbound-inbox-repository.service.ts` | Inbox持久化、请求哈希、claim、租约续期/完成/失败 | 风控和模板匹配 |
|
||
| `inbound-workflow-worker.service.ts` | pump、企业公平分组、微批调度、停止与指标刷新 | SQL细节、消息业务规则 |
|
||
| `inbound-message-preparation.service.ts` | 应用快照、模板/签名/引流匹配、号码频控与风控输入组装 | 事务写入和队列发布 |
|
||
| `inbound-message-persistence.service.ts` | 单条/微批消息、任务、记录、配额预留和幂等持久化 | Worker生命周期、Gateway Submit |
|
||
|
||
### 3.2 出站侧
|
||
|
||
| 目标服务 | 从现有文件提取的职责 | 明确不负责 |
|
||
|---|---|---|
|
||
| `send-worker-lifecycle.service.ts` | BullMQ Worker启动/停止、并发槽位、微批flush、队列指标 | 路由、计费和命令构造 |
|
||
| `message-send-processor.service.ts` | 单条/批量消息处理、状态迁移、失败补偿编排 | Worker定时器和Outbox发布器生命周期 |
|
||
| `channel-routing.service.ts` | 运营商/省份识别、应用路由、候选通道、签名报备检查、主备选择 | 发布命令和数据库Outbox |
|
||
| `channel-rate-limit.service.ts` | 通道TPS等待和相关低基数指标 | 路由选择 |
|
||
| `gateway-submit-command.service.ts` | 命令构造、开放会话ID复用、直接Stream发布契约 | Outbox claim和业务状态变更 |
|
||
| `submit-outbox-publisher.service.ts` | Outbox claim、租约、批量发布、确认、重试和恢复 | 消息计费和路由 |
|
||
| `task-progress-refresher.service.ts` | 真实总量/状态聚合、单飞和尾随刷新 | Submit或回执业务处理 |
|
||
|
||
### 3.3 共享边界
|
||
|
||
- `send-chain.contracts.ts`：只保留稳定输入输出契约，不放实现函数。
|
||
- `send-chain.helpers.ts`：只保留无副作用纯函数；需要数据库、Redis、时间器或日志的逻辑必须进入Service。
|
||
- 计费继续通过现有 `BillingService`，不得复制金额算法。
|
||
- 所有数据库访问保持现有 Prisma 条件和事务客户端传递方式。
|
||
- 所有跨服务调用通过构造注入，不通过全局单例或循环引用。
|
||
|
||
## 4. 拆分前行为锁定
|
||
|
||
在移动代码前补齐特征测试，测试的是当前语义，不是期望中的新设计。
|
||
|
||
### 4.1 入站测试
|
||
|
||
- 认证成功、未知账号、禁用应用、未认证企业、IP不在白名单。
|
||
- 同一请求键并发两次只产生一份任务/消息/计费预留。
|
||
- 请求键相同但payload不同返回冲突。
|
||
- 长短信乱序、重复分片、缺片、超时、重启恢复。
|
||
- Inbox claim不重复、租约超时可恢复、失败次数和最终状态一致。
|
||
- 企业微批公平性、单企业失败不阻塞其他企业。
|
||
- 模板、签名、引流匹配和人工审核关联不改变。
|
||
- 配额预留不足时不产生半成品消息或费用。
|
||
|
||
### 4.2 出站测试
|
||
|
||
- 普通批量与CMPP内部任务入队语义保持不同且正确。
|
||
- Worker微批开启/关闭结果一致。
|
||
- 路由优先级、weighted分流、主备切换和运营商过滤不变。
|
||
- 签名未报备时的拒绝状态和费用释放一致。
|
||
- 通道TPS限制不会跨通道串扰。
|
||
- Submit命令字段、Sequence_Id、Msg_Id、Src_Id和幂等键保持一致。
|
||
- Outbox重复claim、租约恢复、发布成功/失败、Stream重复消费结果一致。
|
||
- 计费冻结、扣费、退款和释放只发生一次。
|
||
- 任务进度刷新保持单飞，并在运行中出现新状态时执行一次尾随刷新。
|
||
|
||
### 4.3 契约快照
|
||
|
||
拆分前固定以下非敏感契约样本：
|
||
|
||
- `gateway.submit.commands`
|
||
- `gateway.submit.results`
|
||
- `gateway.protocol.logs`
|
||
- BullMQ `send-message` job data
|
||
- Submit Outbox payload
|
||
|
||
契约测试只固定字段、类型、必填关系和幂等语义，不固定时间戳、随机ID或日志文本。
|
||
|
||
## 5. 分阶段实施顺序
|
||
|
||
### 阶段 S0：基线冻结
|
||
|
||
- 记录Git commit、两个文件行数/哈希、95项migration状态。
|
||
- 运行现有SendChain专项、API全量、Gateway全量、队列契约和性能基线。
|
||
- 在隔离数据库和Redis记录测试前快照。
|
||
|
||
出口：所有既有测试通过，所有临时数据带独立前缀且可清理。
|
||
|
||
### 阶段 S1：提取纯路由与命令构造
|
||
|
||
先提取 `channel-routing.service.ts` 和 `gateway-submit-command.service.ts`。这两部分事务耦合相对较低，最适合验证构造注入和门面调用方式。
|
||
|
||
规则：只移动代码；输入输出、查询条件、排序和错误文本保持不变。
|
||
|
||
### 阶段 S2：提取任务进度刷新与限速
|
||
|
||
提取 `task-progress-refresher.service.ts` 和 `channel-rate-limit.service.ts`，保留单飞Map、dirty尾随集合及Redis限速键格式。
|
||
|
||
出口：并发刷新和跨通道限速特征测试通过。
|
||
|
||
### 阶段 S3：提取Submit Outbox
|
||
|
||
提取 `submit-outbox-publisher.service.ts`，将定时器生命周期和claim/publish/ack逻辑封装在同一服务；不得改变租约所有者、批量大小、轮询周期或重试条件。
|
||
|
||
出口：故障注入后无丢失、无双发，Stream最终 `pending=0/lag=0`。
|
||
|
||
### 阶段 S4：提取Worker生命周期和消息处理
|
||
|
||
将BullMQ启动/停止/微批flush移入 `send-worker-lifecycle.service.ts`，业务处理移入 `message-send-processor.service.ts`。
|
||
|
||
出口：Worker关闭会等待当前flush；并发槽位与处理指标不变；吞吐基线不下降超过5%。
|
||
|
||
### 阶段 S5：提取入站认证和长短信
|
||
|
||
先移动认证，再移动长短信。两者均有明确入口和状态表，避免直接触碰Inbox微批主流程。
|
||
|
||
出口：认证审计字段、长短信幂等和超时恢复全部一致。
|
||
|
||
### 阶段 S6：提取Inbox Repository和Worker
|
||
|
||
先封装原SQL与事务为Repository，再将pump/企业分组/claim循环移入Worker。Repository方法必须接受现有事务客户端，不允许内部偷偷开启嵌套事务。
|
||
|
||
出口：claim锁顺序、租约、重试、企业公平性和停机等待不变。
|
||
|
||
### 阶段 S7：提取消息准备与持久化
|
||
|
||
这是入站侧风险最高的阶段，最后执行。先把纯准备结果定义为显式结构，再机械移动持久化；计费操作继续调用现有BillingService。
|
||
|
||
出口：消息、任务、计费、审核任务和Inbox状态在成功与每个失败点均与基线一致。
|
||
|
||
### 阶段 S8：清理门面
|
||
|
||
删除仅为旧类内部跳转存在的回调，`SendSubmissionService`仅保留公开API编排。清理必须单独提交，不能与任何业务优化合并。
|
||
|
||
## 6. 每阶段验证矩阵
|
||
|
||
| 层级 | 必须执行 |
|
||
|---|---|
|
||
| 静态 | API TypeScript、ESLint、Prettier、结构门禁、`git diff --check` |
|
||
| 单元 | 新子服务定向测试、SendChain既有全套特征测试 |
|
||
| API | 全量Jest及全源/增量覆盖率 |
|
||
| PostgreSQL | Prisma validate、95项migration、真实事务/锁/幂等契约 |
|
||
| Redis | BullMQ、限速键、Stream、Outbox幂等和最终pending/lag |
|
||
| Gateway | `go test ./... -count=1`、`go vet ./...`、五份队列契约 |
|
||
| 故障注入 | Redis短暂不可用、Gateway响应超时、DB事务失败、Worker中断恢复 |
|
||
| 性能 | 与S0同数据和同参数，入口延迟、完整Submit吞吐、DB池等待、队列积压 |
|
||
|
||
任何阶段出现以下情况立即停止并回退该阶段：
|
||
|
||
- 重复计费、重复Submit或消息丢失。
|
||
- 状态机出现无法收敛的新状态。
|
||
- advisory lock顺序或事务边界变化。
|
||
- 相同负载完整Submit吞吐下降超过5%，且无法由环境波动解释。
|
||
- Stream pending/lag、Inbox processing或Outbox leased无法清零。
|
||
|
||
## 7. 提交策略
|
||
|
||
每个阶段至少拆成两个提交：
|
||
|
||
1. `test(send-chain): lock <responsibility> behavior`
|
||
2. `refactor(send-chain): extract <responsibility> service`
|
||
|
||
禁止在重构提交中混入：
|
||
|
||
- SQL优化或索引变更。
|
||
- 状态、错误码、队列字段变更。
|
||
- TPS、批量大小、超时或重试参数调整。
|
||
- 依赖大版本升级和全仓格式化。
|
||
|
||
## 8. 测试环境发布与回退
|
||
|
||
每个可部署阶段发布前都必须重新建立并校验：PostgreSQL custom dump、运行目录、环境/systemd/Nginx、Redis RDB与Stream状态、MinIO清单、部署commit和migration状态。
|
||
|
||
建议S1～S3合并为第一个测试版本，S4为第二个，S5～S6为第三个，S7～S8为最终版本。每个版本均使用独立恢复点，禁止复用旧备份冒充当前基线。
|
||
|
||
回退只允许回退本阶段部署包与对应恢复资产；如已发生业务写入，应优先代码前滚修复，不得盲目恢复数据库覆盖测试期间其他数据。
|
||
|
||
## 9. 工作量与决策点
|
||
|
||
| 阶段 | 预计工作量 | 风险 |
|
||
|---|---:|---:|
|
||
| S0 行为锁定 | 2～3人日 | 中 |
|
||
| S1～S3 出站低/中耦合拆分 | 2～4人日 | 中 |
|
||
| S4 Worker拆分 | 1～2人日 | 中高 |
|
||
| S5～S6 入站认证/Inbox拆分 | 2～4人日 | 高 |
|
||
| S7～S8 持久化与门面收口 | 2～4人日 | 高 |
|
||
|
||
总计建议按9～17人日安排，并分至少4个测试版本。开始实施前需要用户再次明确授权C8专项和测试环境发布窗口。
|
||
|
||
## 10. 最终关闭标准
|
||
|
||
- 两个超大实现类被删除或只保留不超过300行的兼容转发层。
|
||
- 每个目标服务职责单一，构造依赖和公开方法有明确边界。
|
||
- 所有行为锁定、故障注入、真实PostgreSQL/Redis和Gateway契约通过。
|
||
- 任务、消息、Submit、Outbox、计费和回执语义与S0一致。
|
||
- 同口径性能基线下降不超过5%，无新增DB池等待或队列积压。
|
||
- 测试环境发布后服务健康、错误日志为0、Stream最终 `pending=0/lag=0`。
|
||
- 浏览器只需验证受影响的任务/消息状态展示；不得用页面显示替代后端全链证据。
|