1112 lines
41 KiB
Markdown
1112 lines
41 KiB
Markdown
# 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 的验收标准。
|
||
|
||
然后按计划逐步实现。每完成一步都要运行构建或测试，并更新文档。
|
||
```
|