# CMPP 短信平台第一版开发需求文档

## 0. 文档前提

本文基于当前前端设计原型整理，用于交给 Codex 或开发团队执行第一版落地开发。

当前确认：第一版保留短信业务，排除彩信功能；账户计费、充值套餐、账单流水进入第一版开发范围。彩信服务、彩信应用/签名/模板 Tab，以及运营端彩信相关菜单标记为“待开发”；业务性能指标为“平台可稳定入队并调度 500 条短信/秒，实际向通道 submit 受通道限速配置控制”。

## 1. 项目目标

建设一个短信平台第一版，支持企业客户在客户端完成短信应用、模板、签名、号码导入、短信发送、批量任务查询、发送明细查询、上行短信查询；支持运营端完成企业管理、企业应用/签名/模板管理、审核、通道配置、通道签名报备、报备任务导出/回执导入、发送监控、任务进度、短信记录、上行记录、安全控制和系统管理。

第一版必须满足：

- 支持最高 500 条短信/秒的提交吞吐。
- 支持批量任务异步发送，前端提交后可查询任务进度。
- 支持通道级限速、失败重试、回执同步和发送记录追踪。
- 支持企业、应用、签名、模板、通道、通道组、报备任务等核心配置数据的后台维护。
- 彩信功能仅保留菜单占位或隐藏，不进入第一版开发范围。
- 账户计费、充值套餐、账单流水进入第一版范围，并与发送记录形成可对账闭环。

## 2. 角色与权限

### 2.1 客户端企业管理员

可管理本企业短信应用、短信模板、短信签名、发送任务、上行短信、企业认证、企业用户和系统日志。

### 2.2 客户端普通用户

可按授权查看应用、模板、签名、发送任务和发送明细；是否允许创建和发送需由企业管理员配置。

### 2.3 运营端管理员

可管理全平台企业、应用、签名、模板、审核、通道、通道组、报备任务、发送监控、短信记录、上行记录、黑名单、敏感词、用户、手机号段库和引流字段库。

### 2.4 运营审核员

可处理企业认证审核、短信审核、短信模板审核、签名/模板/发送内容相关审核。

## 3. 第一版范围

### 3.1 客户端范围

保留并开发：

- 工作台
- 短信发送
- 查看批量任务
- 短信发送详情
- 查看上行短信
- 短信应用
- 模板管理
- 签名与引流信息
- 充值套餐
- 账单流水
- 企业认证
- 用户管理
- 账号设置
- 系统日志

暂不开发：

- 彩信服务分组下全部菜单

### 3.2 运营端范围

保留并开发：

- 运营看板、发送监控、数据统计、客户管理
- 企业管理、企业应用管理、企业签名管理、企业模板管理
- 企业认证审核、短信审核、短信模板审核
- 短信通道管理、短信通道组管理
- 报备任务、报备记录
- 短信任务进度、短信记录、短信上行记录
- 充值记录、账单流水、套餐配置、计费规则
- 企业黑名单、全局黑名单、敏感词管理
- 用户管理、手机号段库、引流信息字段库

暂不开发：

- 彩信模板审核
- 彩信通道管理
- 彩信任务进度
- 彩信记录
- 企业应用管理的彩信应用 Tab
- 企业签名管理的彩信签名 Tab
- 企业模板管理的彩信模板 Tab

## 4. 核心业务流程

### 4.1 企业入驻与认证

1. 客户端企业管理员提交企业认证资料。
2. 运营端在企业认证审核中查看资料并审核通过或驳回。
3. 审核通过后企业可创建短信应用、签名、模板并发起短信发送。
4. 驳回时必须记录驳回原因，客户端可查看并重新提交。

### 4.2 短信应用管理

1. 客户端创建短信应用，填写应用名称、场景、回调地址、限额等信息。
2. 运营端可查看企业应用，并支持按企业名称、应用名称、状态搜索。
3. 运营端可启用、停用、编辑应用。
4. 应用必须归属企业，并关联后续签名、模板和发送任务。

### 4.3 签名与引流信息

1. 客户端创建短信签名，提交签名名称、用途、证明材料、引流信息。
2. 运营端企业签名管理查看签名资料。
3. 签名需完成企业内部审核和通道报备，状态包括草稿、待审核、已通过、已驳回、报备中、报备通过、报备失败。
4. 已通过且报备通过的签名才允许发送。

### 4.4 模板管理与审核

1. 客户端创建短信模板，填写模板名称、短信内容、变量、应用、签名。
2. 系统校验敏感词、字数、变量格式和签名匹配。
3. 运营端短信模板审核可通过或驳回模板。
4. 审核通过的模板才允许在短信发送中选择。

### 4.5 短信发送

1. 客户端选择短信应用、签名、模板。
2. 输入或导入接收手机号，支持手动输入和文件导入。
3. 系统校验号码格式、黑名单、手机号段、企业余额/额度、模板变量。
4. 客户端选择立即发送或定时发送。
5. 提交后生成批量任务，任务进入待审核或待发送状态。
6. 系统执行风控规则，命中拒绝规则则直接拒绝并记录原因，命中人工审核规则则进入运营端短信审核。
7. 若命中审核策略，运营端短信审核通过后进入发送队列，审核页面必须展示进入审核的原因。
8. 发送服务按通道组路由、通道限速、企业限速执行提交。
9. 平台批量任务只记录客户端创建的发送任务；API 调用和 CMPP 对接发送不进入批量任务。
10. 所有来源的短信，包括平台批量任务、API 调用、CMPP 对接发送，全部按手机号维度进入短信记录。
11. 任务进度、发送详情和短信记录实时或准实时更新。

### 4.6 通道配置与路由

1. 运营端配置短信通道，包括通道名称、运营商、单价、网关地址、端口、企业代码、账号、密码、接入号、协议参数、启停状态。
2. 运营端配置短信通道组，定义通道优先级、运营商适配、区域适配、权重和故障切换。
3. 发送时根据企业、应用、签名、模板、号码归属、通道状态和通道组策略选择通道。
4. 通道异常时应支持熔断、降级、切换备用通道和失败重试。

### 4.7 通道签名报备

1. 运营端在通道配置中维护签名报备字段。
2. 客户端上传签名资料。
3. 运营端审核企业签名资料。
4. 运营端在通道资料更新后生成通道签名报备任务。
5. 运营端在报备任务中导出通道报备资料。
6. 运营端在报备任务或通道报备详情页导入通道回执。
7. 系统根据回执同步签名在各通道的报备状态。
8. 报备记录保留每次导出、导入、状态变更和操作人。

### 4.8 回执与上行

1. 通道回执接入后更新发送记录状态。
2. 回执状态至少包括提交成功、提交失败、发送成功、发送失败、未知、超时。
3. 提交后 72 小时仍为未知的短信转超时，返回客户失败。
4. 超时前允许人工同步、重新拉取回执或接收供应商二次回执；所有二次回执必须记录历史。
5. 上行短信接入后优先按手机号、接入号、企业/应用、时间窗口匹配下发记录。
6. 接入号匹配不到企业/应用时，展示近期平台对此手机号下发的短信供人工判断。
7. 完全匹配不到的上行短信仍需入库，并展示为未匹配。
8. 客户端可查看本企业上行短信，运营端可查看全平台上行短信。

### 4.9 账户计费

1. 客户端可查看充值套餐、购买或申请充值套餐、查看账单流水。
2. 发送创建时按短信内容计费条数、企业单价或套餐规则生成预估费用，计费条数只按 70/67 字规则拆分。
3. 平台需在发送前检查企业账户余额、套餐余量或授信额度。
4. 发送链路需记录计费条数、计费单价、计费金额、账务状态。
5. 账单流水与短信记录可追溯关联，支持按企业、应用、任务、手机号、时间对账。
6. 最终失败、超时失败需要退费。
7. 计费口径可配置为按提交成功计费或按回执成功计费。

## 5. 功能需求

### 5.1 客户端工作台

- 展示短信余量或可发送额度、今日发送量、成功率、待审核事项、快捷入口。
- 展示最近发送批次、发送趋势、签名/模板状态。
- 数据范围限定为当前企业。

### 5.2 客户端短信发送

- 支持选择短信应用、签名、模板。
- 支持模板变量填充。
- 支持手机号手动输入、粘贴、文件导入。
- 导入号码文件格式支持 CSV、TXT，最大文件大小 20 MB。
- 单任务最大号码数默认 100 万条。
- 支持去重、非法号码提示、黑名单拦截提示。
- 支持立即发送和定时发送。
- 不允许修改已审核模板主体，只允许填写模板变量；如需修改主体，必须新建模板重新审核。
- 不符合模板的短信按应用配置处理：拒绝发送、进入人工审核或直接发送。
- 敏感词命中第一期直接拒绝发送，并记录拒绝原因。
- 提交后展示任务编号和任务状态。

### 5.3 客户端批量任务

- 支持按任务编号、应用、发送时间、状态搜索。
- 展示任务总量、成功数、失败数、未知数、发送进度、创建人。
- 支持查看任务详情和导出明细；默认企业管理员可导出，普通用户需授权。

### 5.4 客户端发送详情

- 支持按手机号、内容、回执、时间搜索。
- 展示手机号、短信内容、计费条数、通道、提交时间、回执时间、状态。
- 支持查看单条发送链路。

### 5.5 客户端上行短信

- 支持按手机号、内容、接收时间搜索。
- 展示上行内容、接入号、匹配下发记录、接收时间。

### 5.6 客户端短信应用

- 支持新增、编辑、启用、停用应用。
- 支持配置回调地址、IP 白名单、应用密钥、日发送限额。
- 支持配置“不符合模板的短信”处理策略：拒绝发送、人工审核、直接发送。
- 支持配置应用级风控阈值：单任务最大号码数、重复号码比例、非法号码比例、黑名单命中比例、非工作时间大批量发送策略、短时间任务创建频控。
- 默认阈值：重复号码比例 30%、非法号码比例 10%、黑名单命中比例 5%、同一企业/应用 10 分钟内最多创建 10 次任务。
- 应用密钥需支持重置，并记录操作日志。

### 5.7 客户端模板管理

- 支持新增、编辑、提交审核、撤回、删除草稿。
- 支持变量识别和字数/计费条数预估。
- 支持查看审核记录和驳回原因。

### 5.8 客户端签名管理

- 支持新增、编辑、提交审核、上传证明材料。
- 支持维护引流信息。
- 支持查看通道报备状态。

### 5.9 客户端账户计费

- 充值套餐：展示可购买套餐、套餐价格、短信条数、有效期、适用范围。
- 账单流水：展示充值、冻结、扣费、退费、调整等流水。
- 账单流水需关联短信任务、短信记录或人工调整单据。
- 客户端账号设置属于系统管理，不允许客户自行配置通道或通道组。

### 5.10 运营端看板与监控

- 展示总发送量、成功率、通道健康度、待处理审核数。
- 发送监控展示通道状态、发送趋势、失败率、积压队列。
- 数据统计支持按企业、应用、通道、日期统计。

### 5.11 运营端客户与企业

- 支持企业列表、企业详情、新增、编辑、启用、停用。
- 支持企业认证资料审核。
- 支持查看企业下应用、签名、模板、发送记录、报备记录。

### 5.12 运营端审核

- 企业认证审核：通过、驳回、查看材料。
- 短信模板审核：通过、驳回、敏感词提示、变量检查。
- 短信审核：查看短信内容、号码量、计费条数、进入审核原因、命中规则、风险原因；支持通过、驳回。
- 审核动作集中在审核中心；企业应用/签名/模板管理页面只做查询、维护、停用、备注和查看审核记录。

### 5.13 运营端通道管理

- 支持新增、编辑、删除、启用、停用短信通道。
- 支持发送测试短信。
- 支持查看通道成功率、未知率、失败率、累计发送量。
- 支持进入通道报备详情。

### 5.14 运营端通道组管理

- 支持新增、编辑通道组。
- 支持配置运营商、区域、优先级、权重、备用通道、限速。
- 支持设置企业或应用绑定关系。

### 5.15 运营端报备任务

- 支持按企业、签名、通道、任务状态、时间搜索。
- 支持生成报备任务。
- 支持在报备任务中导出通道报备资料。
- 支持在报备任务中导入回执。
- 支持查看报备任务详情和处理历史。

### 5.16 运营端报备记录

- 记录报备任务生成、导出、导入、状态同步、失败原因。
- 支持按企业、签名、通道、状态、操作时间搜索。

### 5.17 安全控制

- 企业黑名单：企业维度号码拦截。
- 全局黑名单：平台维度号码拦截。
- 敏感词管理：发送前和审核时命中提示或拦截。
- 手机号段库：用于运营商识别和路由。
- 引流信息字段库：用于签名/报备资料结构化采集。

### 5.18 风控规则闭环

- 运营端提供风控规则配置页面，可按平台、企业、应用维度配置规则。
- 第一版支持规则：单任务最大号码数、重复号码比例、非法号码比例、黑名单命中比例、非工作时间大批量营销发送、短时间任务创建频控、模板变量异常。
- 默认阈值：重复号码比例 30%、非法号码比例 10%、黑名单命中比例 5%、同一企业/应用 10 分钟内最多创建 10 次任务。
- 每条规则需配置启停、阈值、处理动作、适用范围、优先级。
- 处理动作包括：拒绝发送、进入人工审核、仅记录预警。
- 命中规则后必须生成风控命中记录，包含规则编号、规则名称、阈值、实际值、处理动作、命中时间。
- 进入短信审核的任务必须展示进入审核原因和命中的风控规则。
- 直接拒绝的任务必须向客户端返回可读原因，并写入系统日志。

### 5.19 运营端账户计费

- 套餐配置：支持配置套餐名称、价格、短信条数、有效期、适用企业范围、启停状态。
- 充值记录：支持人工充值、套餐购买记录、授信额度调整。
- 账单流水：支持冻结、扣费、退费、解冻、人工调整、失败返还。
- 计费规则：支持按短信计费条数、企业单价、套餐余量、授信额度计算费用。
- 账务流水必须与短信记录形成可追溯关系，支持对账导出。
- 最终失败、超时失败需要退费。
- 计费口径可配置为按提交成功计费或按回执成功计费。

### 5.20 数据保存与清理

- 发送记录保存 12 个月。
- 支持运营端手动按月清除发送记录。
- 冷热分层由技术方案自行设计，但不得影响最近 12 个月在线查询与对账。

### 5.21 系统管理与审计

- 用户管理支持角色、权限、启停、重置密码。
- 系统日志记录登录、配置变更、审核、发送、导入导出、密钥重置等操作。

## 6. 非功能需求

### 6.1 性能

- 平台峰值提交能力：500 条短信/秒。
- 批量任务提交接口响应：创建任务后 2 秒内返回任务编号，不同步完成发送。
- 查询接口 P95 响应时间：列表查询小于 500 ms，详情查询小于 800 ms。
- 发送进度延迟：任务进度统计延迟不超过 5 秒。
- 回执处理：单通道回执接入后 10 秒内完成状态更新，异常积压需告警。

### 6.2 可用性

- 发送链路服务可横向扩容。
- 通道异常不影响其他通道发送。
- 队列消息必须可重试、可追踪、可补偿。
- 关键配置变更必须记录审计日志。

### 6.3 数据安全

- 企业数据必须按租户隔离。
- 手机号、通道密码、应用密钥等敏感字段加密或脱敏展示。
- 导入文件需做格式校验、大小限制、病毒/恶意内容防护。
- 导出文件需鉴权并记录日志。

### 6.4 合规与风控

- 支持敏感词拦截。
- 支持黑名单拦截。
- 支持按企业、应用、通道设置日限额、秒级限速。
- 营销类短信不单独硬编码强制审核，由应用配置和风控规则共同决定处理动作。

## 7. 推荐技术栈

### 7.1 前端

- React 19
- TypeScript
- Vite
- React Router
- Zustand 或 TanStack Query
- ECharts
- Lucide React
- CSS Modules 或现有全局 CSS 体系

说明：现有原型已使用 React、TypeScript、Vite、React Router、Zustand、ECharts、Lucide，可延续。

### 7.2 后端

采用 TypeScript 业务后台 + Go CMPP 网关：

- 后端 API：NestJS + TypeScript
- DB：PostgreSQL
- ORM：Prisma
- 队列：Redis + BullMQ
- 缓存/限速：Redis
- 文件：MinIO
- API 文档：OpenAPI/Swagger
- 监控：Prometheus + Grafana
- 日志：Loki 或 ELK
- 网关：Go 实现真实 CMPP Gateway，第一版必须接入真实 CMPP 长连接能力

### 7.3 短信网关

- Go CMPP Gateway 作为独立服务部署，不和 NestJS 业务后台耦合。
- 第一版支持真实 CMPP 2.0/3.0 长连接能力，后续可扩展 SGIP、SMGP、HTTP 通道。
- 网关负责通道连接、登录认证、长连接保活、submit、deliver、active test、重连、滑动窗口、sequence 管理、回执与上行接收。
- NestJS 业务后台负责企业、应用、模板、签名、报备、审核、计费、风控、路由决策和发送任务编排。
- NestJS 与 Go Gateway 之间通过 Redis/BullMQ 队列或内部 gRPC/HTTP 通信；第一版建议使用队列提交发送指令、队列回传提交结果和回执事件。
- Go Gateway 不直接承担业务审核、账务扣费、签名报备判断，只执行已被业务后台路由后的通道提交。

### 7.4 Go CMPP 开源项目评估结论

可参考开源项目，但不建议直接把完整开源网关作为核心生产服务不加改造使用。建议策略：

- 协议层优先评估并复用成熟 Go CMPP 协议库，降低从零实现 CMPP PDU、编解码、sequence、滑动窗口、deliver 解析的风险。
- 网关服务层由本项目自研，围绕本系统的通道配置、限速、发送队列、回执幂等、监控、日志、故障切换、账务关联来设计。
- 对开源网关项目可作为参考实现或测试工具，不直接绑定业务模型。

初步候选：

- `bigwhite/gocmpp`：Go CMPP 协议库，适合作为协议层参考或依赖候选。
- `JoeCao/cmpp-gateway`：基于 gocmpp 的网关项目，包含 gateway、backend、simulator 等模块，适合作为架构参考和联调模拟参考。

落地前需要完成一次技术 Spike：

1. 拉取候选项目，确认 License、维护活跃度、CMPP 2.0/3.0 支持情况。
2. 用模拟 SMSC 完成 connect、submit、deliver、active test、disconnect 流程。
3. 压测单连接和多连接 submit 能力，验证 500 条/秒调度下的网关稳定性。
4. 检查异常场景：断线重连、sequence 回绕、窗口满、回执重复、SMSC 慢响应。
5. 决定最终依赖方式：直接依赖协议库、fork 改造、或完全自研协议层。

## 8. 建议系统架构

### 8.1 服务拆分

第一版可采用模块化单体加独立发送 Worker，避免过早微服务化：

- Web/API 服务：认证、企业、应用、签名、模板、审核、通道、报备、查询。
- Send Worker：消费发送队列，执行路由、限速、提交通道。
- Receipt Worker：处理通道回执、更新发送状态。
- Report Worker：处理报备资料导出、回执导入、状态同步。
- Gateway Adapter：CMPP 通道连接与协议适配。

后续可拆为独立服务：

- tenant-service
- config-service
- audit-service
- send-service
- gateway-service
- report-service
- statistics-service

### 8.2 发送链路

1. API 创建批量任务。
2. 拆分号码和变量，生成 message_record。
3. 写入数据库并投递 send.queue。
4. Send Worker 消费消息，校验黑名单、敏感词、限额。
5. 路由选择通道。
6. 通过通道限速器控制 TPS。
7. 调用 Gateway Adapter 提交短信。
8. 写入 submit 状态。
9. Receipt Worker 接收回执并更新最终状态。
10. 统计任务进度。

### 8.3 500 条/秒实现建议

- 创建任务与发送解耦，提交接口只负责入库和投递队列。
- Send Worker 多实例部署，每实例处理固定通道分片或队列分片。
- 使用 Redis Token Bucket 或本地令牌桶加 Redis 协调实现通道限速。
- 单条发送记录以 message_id 全局唯一，所有提交和回执处理幂等。
- 批量插入 message_record，避免逐条事务。
- 按任务、日期或企业对发送明细表做分区。
- 热查询统计写入 Redis 或统计表，避免实时 count 大表。

## 9. 核心数据模型

### 9.1 租户与用户

- tenant：企业主体。
- tenant_certification：企业认证资料。
- user：用户。
- role、permission、user_role：权限。
- operation_log：操作日志。

### 9.2 短信配置

- sms_application：短信应用。
- sms_signature：短信签名。
- signature_material：签名证明材料。
- sms_template：短信模板。
- template_variable：模板变量。
- audit_record：审核记录。

### 9.3 通道与路由

- sms_channel：短信通道。
- sms_channel_group：通道组。
- sms_channel_group_item：通道组通道明细。
- channel_route_rule：路由规则。
- channel_health_metric：通道健康指标。

### 9.4 报备

- channel_report_field：通道报备字段配置。
- signature_report_material：签名报备资料。
- channel_signature_report_task：通道签名报备任务。
- channel_signature_report_record：报备记录。
- report_export_file：导出文件。
- report_receipt_import：回执导入批次。

### 9.5 发送

- sms_batch_task：批量任务。
- sms_message_record：单号码发送记录，所有平台任务、API 调用、CMPP 对接发送均进入此表。
- sms_api_request：API 调用批次记录。
- cmpp_submit_session：CMPP 对接提交会话或批次记录。
- sms_submit_record：通道提交记录。
- sms_receipt_record：短信回执。
- sms_uplink_message：上行短信。
- sms_send_audit：短信发送审核。

### 9.6 风控与基础数据

- enterprise_blacklist：企业黑名单。
- global_blacklist：全局黑名单。
- sensitive_word：敏感词。
- risk_rule：风控规则配置。
- risk_rule_hit：风控规则命中记录。
- phone_segment：手机号段库。
- drainage_field：引流字段库。

### 9.7 账户计费

- billing_plan：充值套餐。
- tenant_account：企业账户。
- account_balance：余额或套餐余量。
- account_transaction：账户流水。
- billing_rule：计费规则。
- sms_billing_record：短信计费记录。
- recharge_order：充值订单或人工充值记录。

## 10. 接口范围

### 10.1 客户端 API

- `POST /api/client/auth/login`
- `GET /api/client/dashboard`
- `GET /api/client/applications`
- `POST /api/client/applications`
- `PUT /api/client/applications/{id}`
- `POST /api/client/applications/{id}/secret/reset`
- `GET /api/client/signatures`
- `POST /api/client/signatures`
- `POST /api/client/signatures/{id}/submit`
- `GET /api/client/templates`
- `POST /api/client/templates`
- `POST /api/client/templates/{id}/submit`
- `POST /api/client/sms/tasks`
- `GET /api/client/sms/tasks`
- `GET /api/client/sms/tasks/{id}`
- `GET /api/client/sms/messages`
- `GET /api/client/sms/uplinks`
- `GET /api/client/billing/plans`
- `POST /api/client/billing/orders`
- `GET /api/client/billing/transactions`
- `POST /api/client/enterprise-certification`
- `GET /api/client/users`
- `GET /api/client/system-logs`

### 10.2 运营端 API

- `GET /api/admin/dashboard`
- `GET /api/admin/monitor`
- `GET /api/admin/statistics`
- `GET /api/admin/enterprises`
- `POST /api/admin/enterprises`
- `PUT /api/admin/enterprises/{id}`
- `GET /api/admin/enterprise-applications`
- `GET /api/admin/enterprise-signatures`
- `GET /api/admin/enterprise-templates`
- `POST /api/admin/audits/{id}/approve`
- `POST /api/admin/audits/{id}/reject`
- `GET /api/admin/channels`
- `POST /api/admin/channels`
- `PUT /api/admin/channels/{id}`
- `POST /api/admin/channels/{id}/test`
- `GET /api/admin/channels/{id}/reports`
- `POST /api/admin/channel-groups`
- `GET /api/admin/report-tasks`
- `POST /api/admin/report-tasks/generate`
- `POST /api/admin/report-tasks/{id}/export`
- `POST /api/admin/report-tasks/{id}/receipt-import`
- `GET /api/admin/report-records`
- `GET /api/admin/sms/tasks`
- `GET /api/admin/sms/records`
- `GET /api/admin/sms/uplinks`
- `GET /api/admin/blacklists/enterprise`
- `GET /api/admin/blacklists/global`
- `GET /api/admin/sensitive-words`
- `GET /api/admin/risk-rules`
- `POST /api/admin/risk-rules`
- `PUT /api/admin/risk-rules/{id}`
- `GET /api/admin/risk-rule-hits`
- `GET /api/admin/billing/plans`
- `POST /api/admin/billing/plans`
- `PUT /api/admin/billing/plans/{id}`
- `GET /api/admin/billing/transactions`
- `POST /api/admin/billing/recharges`
- `GET /api/admin/phone-segments`
- `GET /api/admin/drainage-fields`
- `GET /api/admin/users`

### 10.3 通道回调 API

- `POST /api/gateway/receipts/{channelCode}`
- `POST /api/gateway/uplinks/{channelCode}`

如使用 CMPP 长连接，回执和上行由 Gateway Adapter 直接消费协议消息，不一定暴露 HTTP 回调。

## 11. 状态定义

### 11.1 审核状态

- draft：草稿
- pending：待审核
- approved：已通过
- rejected：已驳回

### 11.2 报备状态

- not_required：无需报备
- waiting_material：待资料
- pending：待报备
- exporting：导出中
- submitted：已提交通道
- approved：报备通过
- rejected：报备失败
- partial_approved：部分通过

### 11.3 发送任务状态

- draft：草稿
- pending_audit：待审核
- rejected：审核驳回
- scheduled：待定时发送
- queued：排队中
- sending：发送中
- completed：已完成
- canceled：已取消
- failed：失败

### 11.4 单条短信状态

- created：已创建
- rejected：风控拒绝或规则拒绝
- filtered：已拦截
- queued：待发送
- submitted：已提交
- submit_failed：提交失败
- delivered：发送成功
- undelivered：发送失败
- unknown：未知
- timeout：超时

### 11.5 短信来源

- platform_task：客户端平台批量任务
- api：企业 API 调用
- cmpp: 企业 CMPP 对接发送

### 11.6 风控处理动作

- reject：拒绝发送
- manual_audit：进入人工审核
- warn_only：仅记录预警

### 11.7 账务状态

- estimated：已预估
- frozen：已冻结
- charged：已扣费
- refunded：已退费
- released：已解冻
- adjusted：人工调整

## 12. 实施步骤

### 阶段 1：工程初始化

1. 确认第一版范围，关闭或隐藏彩信菜单，保留账户计费菜单。
2. 建立前端、NestJS API、Go CMPP Gateway 的仓库结构或 monorepo 工作区。
3. 配置代码规范、环境变量、构建、Docker Compose。
4. 建立 Prisma schema 和数据库迁移流程。
5. 建立 OpenAPI 文档和前端 API Client 生成流程。
6. 建立 Go Gateway 的配置、日志、监控、健康检查和本地模拟 SMSC 联调环境。

### 阶段 2：基础能力

1. 实现登录、用户、角色、权限。
2. 实现租户隔离。
3. 实现文件上传和对象存储。
4. 实现操作日志。
5. 实现基础字典：手机号段、敏感词、黑名单、引流字段。
6. 实现账户、套餐、账务流水基础模型。

### 阶段 3：企业与配置

1. 实现企业认证。
2. 实现短信应用。
3. 实现短信签名和材料。
4. 实现短信模板和变量解析。
5. 实现应用级不符合模板短信处理策略。
6. 实现审核记录与审核工作台。

### 阶段 4：通道与报备

1. 实现短信通道 CRUD。
2. 实现通道组与路由规则。
3. 实现通道签名报备字段配置。
4. 实现报备任务生成。
5. 实现报备资料导出。
6. 实现回执导入和报备状态同步。

### 阶段 5：发送链路

1. 实现批量任务创建。
2. 实现号码导入、校验、去重、拆分。
3. 实现风控规则配置、规则命中、审核原因展示。
4. 实现发送审核策略。
5. 实现发送前账户校验、预估、冻结或扣费。
6. 实现发送队列。
7. 实现 Send Worker。
8. 实现 Go CMPP Gateway，支持真实 CMPP 长连接、submit、deliver、active test、重连。
9. 实现回执处理、72 小时超时和上行处理。
10. 实现任务进度统计。

### 阶段 6：查询与统计

1. 实现客户端批量任务、发送详情、上行短信。
2. 实现运营端任务进度、短信记录、上行记录。
3. 实现客户端充值套餐、账单流水。
4. 实现运营端充值记录、账务流水、套餐配置。
5. 实现运营看板、发送监控、数据统计。
6. 实现导出权限和导出日志。

### 阶段 7：性能与稳定性

1. 压测任务创建接口。
2. 压测队列消费和发送 Worker。
3. 压测回执处理。
4. 验证 500 条/秒提交能力。
5. 验证风控规则命中、审核原因、账务流水一致性。
6. 验证通道限速、故障切换、重试、幂等。
7. 加入监控告警和慢查询优化。

### 阶段 8：验收

1. 按原型完成页面功能联调。
2. 完成核心流程端到端测试。
3. 完成权限测试。
4. 完成数据隔离测试。
5. 完成账务对账测试。
6. 完成性能测试报告。
7. 完成 Linux 部署方案。
8. 完成上线回滚方案。

## 13. Codex 开发执行建议

### 13.1 推荐任务拆分

1. 根据本文创建数据库迁移脚本和实体模型。
2. 实现认证、租户、权限基础模块。
3. 实现企业、应用、签名、模板 CRUD 与审核。
4. 实现账户计费、套餐、账务流水。
5. 实现通道、通道组、报备任务。
6. 实现风控规则、审核原因、规则命中记录。
7. 实现 NestJS Send Worker、BullMQ 队列和 Redis 限速。
8. 实现 Go CMPP Gateway，并完成与 NestJS 队列事件的联调。
9. 实现发送任务、发送明细、回执、上行。
10. 前端将 mock service 替换为真实 API。
11. 增加集成测试、性能测试和部署脚本。

### 13.2 给 Codex 的单任务提示模板

```text
请基于 docs/first-version-development-requirements.md，实现【模块名】。
要求：
1. 遵循现有原型页面和字段命名。
2. NestJS 后端实现 Prisma schema、migration、Service、Controller、DTO、单元测试。
3. Go Gateway 实现配置、连接管理、CMPP submit/deliver/active test、回执事件发布、单元测试。
4. 前端将对应 mock 数据替换为 API 调用，保留现有视觉样式。
5. 补充错误处理、权限校验、操作日志。
6. 运行构建和相关测试。
```

## 14. 已确认关键决策

### 14.1 通道协议与报备

- 运营商通道协议参数和回执格式先按公开 CMPP 文档实现。
- 签名报备字段模板由运营端自行配置和手工维护。
- 第一期不考虑通过 API 向运营商传送签名报备资料。

### 14.2 发送能力

- 需要支持定时发送。
- 导入号码文件格式支持 CSV、TXT。
- 导入文件最大 20 MB。
- 单任务最大号码数默认 100 万条。

### 14.3 风控默认阈值

- 重复号码比例默认阈值：30%。
- 非法号码比例默认阈值：10%。
- 黑名单命中比例默认阈值：5%。
- 短时间任务创建频控默认阈值：同一企业/应用 10 分钟内 10 次。

### 14.4 计费与退费

- 最终失败、超时失败需要退费。
- 计费口径可配置为按提交成功计费或按回执成功计费。
- 短信计费规则只按 70/67 字拆分。

### 14.5 数据保存与更正

- 发送记录保存 12 个月。
- 支持手动按月清除发送记录。
- 冷热分层由技术方案自行设计。
- 超时后供应商又返回成功回执时，不允许自动覆盖业务失败状态。
- 系统需保留二次回执记录，并提供人工更正功能。

### 14.6 认证、部署与账号体系

- 第一版不考虑多租户独立域名和企业 SSO，只支持一个平台域名。
- 部署环境为 Linux。
- 最终需要给出 Linux 部署方案。
- 企业认证资料采用人工上传、人工审核，不接第三方实名认证或营业执照 OCR。

### 14.7 待确认问题

暂无阻塞性待确认问题。后续进入详细设计或开发时，如遇具体运营商协议参数、生产部署资源规格、默认套餐价格等执行细节，再按模块补充确认。

## 15. 第一版落地执行路线

### 阶段 0：技术 Spike

目标：优先验证最大技术风险，避免业务代码写完后发现网关链路不可用。

任务：

1. Go CMPP Gateway Spike
   - 基于 `gocmpp` 验证 CMPP connect、submit、deliver、active test、terminate。
   - 参考 `JoeCao/cmpp-gateway` 的连接、重连、SEQID/MSGID 追踪、模拟器设计。
   - 搭建最小 Go Gateway，支持配置一个模拟或真实 CMPP 通道。

2. BullMQ 通信 Spike
   - NestJS 通过 Redis/BullMQ 下发发送指令。
   - Go Gateway 消费发送指令或监听队列事件。
   - Go Gateway 回传提交结果、回执、上行事件。

3. 500 条/秒链路 Spike
   - 不接完整业务，只压测 NestJS 入队、Go Gateway 消费、模拟通道响应。
   - 验证平台可稳定入队并调度 500 条短信/秒。
   - 输出压测结果、瓶颈和下一步优化建议。

验收标准：

- 能跑通一条模拟短信：NestJS 入队 -> Go Gateway 提交 -> submit resp -> deliver 回执 -> NestJS 更新状态。
- Go Gateway 断线后可重连，并能继续消费后续消息。
- 所有消息都有 messageId、channelId、sequenceId 或可追踪映射。
- Spike 文档记录是否采用 `gocmpp`、是否需要 fork、哪些能力需要自研。

### 阶段 1：工程骨架

目标：让前端、NestJS API、Go Gateway 和基础设施能稳定启动。

任务：

1. 建立 monorepo 或多目录结构：
   - `web`：React + TypeScript + Vite
   - `api`：NestJS + TypeScript
   - `gateway`：Go CMPP Gateway
   - `docs`：需求、设计、接口、部署文档
2. 配置 PostgreSQL、Redis、MinIO、Docker Compose。
3. 配置 Prisma、migration、seed。
4. 配置 OpenAPI/Swagger。
5. 配置日志、环境变量、健康检查。
6. 配置基础 CI 命令：lint、test、build。

验收标准：

- `web`、`api`、`gateway` 均可本地启动。
- Docker Compose 可启动 PostgreSQL、Redis、MinIO。
- NestJS 可连接 PostgreSQL 和 Redis。
- Go Gateway 可读取配置并启动健康检查接口。

### 阶段 2：基础后台

目标：完成业务底座。

任务：

1. 登录认证。
2. 企业/租户。
3. 用户、角色、权限。
4. 操作日志。
5. 文件上传。
6. 系统字典。
7. 手机号段库。
8. 敏感词。
9. 黑名单。
10. 引流字段库。

验收标准：

- 所有业务数据具备租户隔离。
- 关键操作写入操作日志。
- 文件上传可用于签名资料和认证资料。

### 阶段 3：短信配置

目标：客户和运营能配置发送短信所需资源。

任务：

1. 短信应用。
2. 应用密钥和 IP 白名单。
3. 应用发送限额。
4. 应用级“不符合模板短信”处理策略。
5. 短信签名。
6. 签名资料。
7. 短信模板。
8. 模板变量。
9. 平台审核记录。

验收标准：

- 客户端可创建应用、签名、模板。
- 运营端可审核签名和模板。
- 发送时只能使用审核通过的签名和模板。
- 客户端不能修改已审核模板主体，只能填写变量。

### 阶段 4：通道与报备

目标：运营端能配置通道、通道组和签名报备流程。

任务：

1. 短信通道管理。
2. 通道组管理。
3. 路由规则。
4. 通道签名报备字段配置。
5. 签名报备资料。
6. 报备任务生成。
7. 报备资料导出。
8. 回执导入。
9. 报备记录。
10. 签名报备状态同步。

验收标准：

- 签名审核状态和通道报备状态分层。
- 发送前必须校验签名在目标通道报备通过。
- 报备任务导出、导入具备幂等和历史记录。

### 阶段 5：账户计费

目标：发送前能判断是否可发，发送后能对账。

任务：

1. 套餐配置。
2. 充值套餐。
3. 企业账户。
4. 余额或套餐余量。
5. 充值记录。
6. 账单流水。
7. 发送预估费用。
8. 冻结、扣费、退费、解冻。
9. 短信记录与账务流水关联。

验收标准：

- 客户端充值套餐和账单流水进入第一版。
- 发送前校验账户余额、套餐余量或授信额度。
- 每条短信记录可追溯到账务流水。

### 阶段 6：风控与审核

目标：发送前有规则、有原因、有闭环。

任务：

1. 风控规则配置。
2. 默认阈值。
3. 单任务最大号码数。
4. 重复号码比例。
5. 非法号码比例。
6. 黑名单命中比例。
7. 非工作时间大批量营销发送。
8. 短时间任务创建频控。
9. 模板变量异常。
10. 风控命中记录。
11. 短信审核。
12. 审核原因展示。
13. 拒绝原因返回客户端。

验收标准：

- 命中风控规则时记录规则编号、规则名称、阈值、实际值、处理动作。
- 进入审核的任务必须展示审核原因。
- 直接拒绝的任务必须向客户端返回可读原因。

### 阶段 7：发送链路

目标：真实跑通短信发送。

任务：

1. 客户端批量任务创建。
2. 号码导入和拆分。
3. 发送任务入队。
4. Send Worker。
5. 通道路由。
6. Redis 限速。
7. Go Gateway 提交 CMPP。
8. Submit Resp 处理。
9. 回执处理。
10. 上行短信处理。
11. 72 小时未知转超时。
12. 任务进度统计。

验收标准：

- 平台创建的批量任务只记录客户端任务。
- 平台任务、API 调用、CMPP 对接发送全部按手机号维度进入短信记录。
- 支持 submit resp、deliver 回执、上行短信、超时补偿。

### 阶段 8：查询、统计、验收

目标：系统可运营、可排查、可上线。

任务：

1. 客户端批量任务。
2. 客户端发送详情。
3. 客户端上行短信。
4. 运营端发送监控。
5. 运营端任务进度。
6. 运营端短信记录。
7. 运营端上行记录。
8. 运营看板。
9. 数据统计。
10. 操作日志审计。
11. 性能压测。
12. 500 条/秒报告。
13. Linux 上线部署文档。
14. 回滚方案。

验收标准：

- 可按企业、应用、通道、任务、手机号追踪发送链路。
- 可按账务流水和短信记录对账。
- 输出 500 条/秒压测报告。
- 输出 Linux 部署方案，至少覆盖 Docker Compose 或 systemd 部署、环境变量、数据库迁移、日志目录、备份恢复、服务健康检查和回滚步骤。

## 16. 新 Codex 会话提示词

## 17. 第一版需求增补记录

### 2026-07-01 账户与日志展示调整

1. 运营端增加企业人工充值入口。
   - 运营端可针对指定企业录入人工充值金额、操作人和备注。
   - 人工充值必须写入充值订单和账务流水。
   - 运营端充值记录需区分人工充值和套餐充值。
2. 客户端概览指标调整。
   - 原“剩余条数”改为“剩余余额”。
   - 原“近24小时成功率”改为“今日发送条数和今日成功率”。
   - 新增“今日消费金额”和“今日返还金额”展示。
3. 运营端增加系统日志。
   - 运营端可查询全平台系统日志。
   - 日志需支持按企业、模块、级别、操作人、资源 ID 或详情定位。
   - 人工充值、审核、风控、发送链路、系统管理等关键动作需要可追溯。

建议新开 Codex 会话后直接发送以下提示词：

```text
当前项目是 CMPP 短信平台第一版开发，工作区内已有前端设计原型和需求文档。

请先完整阅读：
1. docs/first-version-development-requirements.md
2. docs/ui-design-guidelines.md
3. package.json
4. src/routes/AppRoutes.tsx
5. src/layouts/ClientLayout.tsx
6. src/layouts/AdminLayout.tsx

重要前提：
- 第一版保留短信业务，排除彩信功能。
- 账户计费、充值套餐、账单流水进入第一版。
- 前端使用 React + TypeScript + Vite。
- 后端 API 使用 NestJS + TypeScript。
- DB 使用 PostgreSQL。
- ORM 使用 Prisma。
- 队列使用 Redis + BullMQ。
- 缓存/限速使用 Redis。
- 文件使用 MinIO。
- 第一版必须实现真实 Go CMPP Gateway。
- Go Gateway 协议层优先评估 gocmpp，参考 JoeCao/cmpp-gateway 的连接、重连、SEQID/MSGID 追踪、模拟器设计。
- 不从零手写整个 CMPP 协议栈，也不直接照搬完整开源网关；协议层可复用，服务层按本项目自研。
- NestJS 负责业务审核、风控、计费、报备、路由和发送编排。
- Go Gateway 只负责 CMPP 连接、协议提交、submit resp、回执、上行事件回传。

请从 docs/first-version-development-requirements.md 的“阶段 0：技术 Spike”开始执行。

第一步请先不要大规模写业务代码，先输出并创建阶段 0 Spike 的最小工程计划，包括：
1. 目录结构建议。
2. NestJS 与 Go Gateway 的队列消息格式。
3. Go Gateway 最小能力清单。
4. gocmpp 与 cmpp-gateway 的技术评估任务。
5. 500 条/秒 Spike 压测指标。
6. 阶段 0 的验收标准。

然后按计划逐步实现。每完成一步都要运行构建或测试，并更新文档。
```