lislgosms/docs/first-version-development-requirements.md

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. 通道必须配置发送地区，发送地区为全国或 34 个省级地区之一；单个通道只能选择一个发送地区。
4. 运营端配置短信通道组，定义通道优先级、运营商适配、省网路由、全国路由、权重、失败补发开关和补发时间上限。
5. 企业不配置默认通道组；企业应用必须单独配置至少一个运营商通道组，否则页面不可保存，发送时也必须直接失败。
6. 一个企业应用可以分别绑定移动、联通、电信通道组；可以只绑定其中一类或两类，但不能一个都不绑定。
7. 发送时先按运营商识别结果分流：移动短信走移动通道组，联通短信走联通通道组，电信短信走电信通道组；识别不出的号码走移动通道组。
8. 运营商识别优先使用可配置的号码前缀正则表达式，通常匹配手机号前 3 到 4 位；如当前没有配置能力，手机号段库需增加“运营商区分规则”配置。
9. 路由规则只能表达应用到通道组的绑定关系，不能直接绑定单个通道，也不在规则层配置省份；省份和全国路由在通道组内部处理。
10. 发送服务必须使用手机号段库识别手机号省份和城市；无法识别省份时走对应运营商的全国通道组路由。
11. 通道组内必须先匹配省网路由；省网未匹配时走同一运营商通道组内的全国通道。省网发送失败后，当前版本立即跳到该通道组第一个全国通道补发，不再尝试同省第二省网通道。
12. 省网配置当前版本一省只能配置一个通道；全国通道可配置多个，并按优先级依次补发。
13. 未命中企业应用通道组或无可用通道时不得 fallback 到全局第一个 active 通道，应将该短信标记为 failed，并记录可读失败原因、trace 和系统日志；客户端本期不展示通道细节。
14. 可发送通道必须同时满足：通道业务状态 active、CMPP 连接状态 online、当前连接数大于 0、心跳未失败；auth_failed、heartbeat_timeout、reconnecting、disconnected 或当前连接数为 0 的通道均不可被选中。
15. 多连接通道只要至少 1 条连接 online 且可用即可参与路由；心跳失败应及时更新连接状态，连续 3 次心跳失败后进入重连，重连成功前不可发送。
16. 通道异常时应支持熔断、降级、切换备用通道和失败重试；失败补发必须在同一企业应用授权的通道组范围内执行，并保证计费、退款、幂等和 trace 可追踪。
17. 失败补发除以下情况外均应触发：短信状态为 unknown；距离客户提交时间超过 72 小时；距离客户提交时间超过通道组配置的补发时间上限；通道组关闭失败补发。
18. 通道组补发时间上限由运营端配置，最大不得超过 72 小时；本期不配置最大补发次数、补发间隔或失败类型白名单。
19. 提交 accepted 后立即按企业应用配置的客户费率扣费；补发过程中最终成功只扣一次，submit failed 未真正发出时释放冻结且不扣费；本期客户计费不使用通道成本价。

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 运营端客户与企业

• 支持企业列表、企业详情、新增、编辑、启用、停用。
• 支持企业认证资料审核。
• 支持查看企业下应用、签名、模板、发送记录、报备记录。
• 企业管理列表不提供无业务意义的“详情”按钮；需要查看明细时从企业应用、签名、模板、发送记录等业务入口进入。
• 企业应用管理编辑保存后返回企业应用管理列表。
• 企业应用列表展示 CMPP 连接数；点击连接数打开连接详情弹窗，内容包含连接 id、状态、连接建立时间、最近心跳时间、上次提交时间、窗口占用等。
• 企业应用连接详情支持删除连接；删除连接必须调用真实后端接口或 Gateway 回写接口，并写入系统日志。
• 企业应用列表提供 CMPP 连接参数查看与一键复制能力，参数来源于真实应用/通道配置，不允许只在前端拼接假数据。

5.12 运营端审核

• 企业认证审核：通过、驳回、查看材料。
• 企业认证详情必须展示客户提交的主体资料、统一社会信用代码、法定代表人、注册地址、营业执照附件、对公账户验证资料、联系人信息、提交时间、审核备注、驳回原因等；通过/驳回必须更新认证记录和租户认证状态，并写操作日志。
• 短信模板审核：通过、驳回、敏感词提示、变量检查。
• 短信模板审核必须支持按客户、应用、模板内容、审核编号和审核状态搜索；搜索应由真实后端 API 支持，前端只做展示和交互。
• 短信审核：查看短信内容、号码量、计费条数、进入审核原因、命中规则、风险原因；支持通过、驳回。
• 审核动作集中在审核中心；企业应用/签名/模板管理页面只做查询、维护、停用、备注和查看审核记录。

5.13 运营端通道管理

• 支持新增、编辑、删除、启用、停用短信通道。
• 删除通道采用软删除或停用归档，不能破坏历史发送、报备、日志外键；删除、启用、停用、复制等高影响操作必须二次确认并写系统日志。
• 支持复制通道：复制后新建一个通道，除 id/code 自动生成外，通道配置、CMPP 参数、通道报备字段、签名/引流报备材料和个性化字段配置均需从源通道复制；名称默认追加“副本”。
• 支持发送测试短信。
• 支持查看通道成功率、未知率、失败率、累计发送量。
• 支持进入通道报备详情。
• 通道报备详情页中，签名下的引流信息默认收起，用户点击后展开；展开/收起只影响页面展示，不改变报备数据。
• 通道列表状态区域展示“链接日志”入口；点击后弹窗展示真实连接日志，包括新建连接、断开、心跳、重连、异常等事件，日志来源于 Gateway 回写或 OperationLog。
• 通道操作按钮应保持一致的两列布局，报备详情、编辑、复制、发送测试、启停、删除等操作文案清晰。

5.14 运营端通道组管理

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

5.15 运营端报备任务

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

5.16 运营端报备记录

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

5.17 安全控制

• 企业黑名单：企业维度号码拦截。
• 全局黑名单：平台维度号码拦截。
• 敏感词管理：发送前和审核时命中提示或拦截。
• 手机号段库：用于运营商识别和路由。
• 引流信息字段库：用于签名/报备资料结构化采集。
• 企业黑名单、全局黑名单、敏感词管理必须提供搜索、添加、启停/删除功能；所有操作调用真实后端 API，写入系统日志。
• 企业黑名单支持按企业、应用、手机号、入库原因、状态搜索；全局黑名单支持按手机号、原因、状态搜索；敏感词支持按词、分类/级别、状态搜索。
• “引流信息字段库”菜单命名为“报备字段库”，编辑、删除按钮使用通用操作按钮样式。

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. 使用手机号段库识别号码省份和城市；识别不出省份时按全国路由处理。
7. 按企业应用绑定的对应运营商通道组执行路由：先匹配省网通道，再匹配全国通道；不得直接绑定或 fallback 到非授权单通道。
8. 过滤业务 disabled、连接离线、认证失败、心跳超时或无可用连接数的通道。
9. 通过通道限速器控制 TPS。
10. 调用 Gateway Adapter 提交短信。
11. 写入 submit 状态。
12. Submit rejected、submit timeout、Gateway 连接断开或未提交成功、receipt failed 等场景按通道组策略补发到下一可用全国通道；unknown、超过 72 小时、超过通道组补发时间上限或关闭补发时不再补发。
13. Receipt Worker 接收回执并更新最终状态。
14. 补发过程必须保持幂等、计费一致和 trace 可查，最终成功只扣一次客户费率。
15. 统计任务进度。

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
• POST /api/client/users
• PUT /api/client/users/{id}
• DELETE /api/client/users/{id}
• POST /api/client/users/{id}/status
• POST /api/client/users/{id}/password/reset
• POST /api/client/auth/password/change
• 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
• PUT /api/admin/enterprise-applications/{id}
• GET /api/admin/enterprise-applications/{id}/connections
• DELETE /api/admin/enterprise-applications/{id}/connections/{connectionId}
• GET /api/admin/enterprise-applications/{id}/cmpp-params
• GET /api/admin/enterprise-signatures
• GET /api/admin/enterprise-templates
• GET /api/admin/enterprise-certifications
• GET /api/admin/enterprise-certifications/{id}
• POST /api/admin/enterprise-certifications/{id}/approve
• POST /api/admin/enterprise-certifications/{id}/reject
• GET /api/admin/audit-summary
• 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}/status
• DELETE /api/admin/channels/{id}
• POST /api/admin/channels/{id}/copy
• POST /api/admin/channels/{id}/test
• GET /api/admin/channels/{id}/reports
• GET /api/admin/channels/{id}/connections
• GET /api/admin/channels/{id}/link-logs
• 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/dictionaries/blacklists/enterprise
• POST /api/admin/dictionaries/blacklists/enterprise
• POST /api/admin/dictionaries/blacklists/enterprise/{id}/status
• DELETE /api/admin/dictionaries/blacklists/enterprise/{id}
• GET /api/admin/dictionaries/blacklists/global
• POST /api/admin/dictionaries/blacklists/global
• POST /api/admin/dictionaries/blacklists/global/{id}/status
• DELETE /api/admin/dictionaries/blacklists/global/{id}
• GET /api/admin/dictionaries/sensitive-words
• POST /api/admin/dictionaries/sensitive-words
• POST /api/admin/dictionaries/sensitive-words/{id}/status
• DELETE /api/admin/dictionaries/sensitive-words/{id}
• 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
• POST /api/admin/drainage-fields
• PUT /api/admin/drainage-fields/{id}
• DELETE /api/admin/drainage-fields/{id}
• GET /api/admin/users
• POST /api/admin/users
• PUT /api/admin/users/{id}
• DELETE /api/admin/users/{id}
• POST /api/admin/users/{id}/status
• POST /api/admin/users/{id}/password/reset
• POST /api/admin/auth/password/change
• GET /api/admin/system-logs

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 的单任务提示模板

请基于 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. 原型阶段的 mock、localStorage 或静态数据只能用于早期界面占位；进入系统功能验收后不得继续作为兜底通过路径。审核、通道、连接、日志、黑名单、敏感词、报备字段、用户、账务等闭环必须接入真实 API、数据库或 Gateway 回写；API 不可用时应展示错误态或空态，并将用例标记为阻塞或未通过。
6. 补充错误处理、权限校验、操作日志。
7. 运行构建和相关测试，并更新测试进度文档。

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 会话后直接发送以下提示词：

当前项目是 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、回执、上行事件回传。
- 当前项目已进入真实开发阶段；前端 mock、localStorage 或静态数据不得作为功能完成标准，也不得作为验收兜底通过路径。涉及审核、通道、连接、日志、安全控制、用户、账务等闭环时，必须接入真实 API、数据库或 Gateway 回写，并补真实后端 smoke 或 E2E 测试。

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

## 追加需求：登录与用户管理闭环

### 1. 登录入口

- 客户端和运营端必须使用独立登录页面：客户端 `/client/login`，运营端 `/admin/login`。
- 两端登录均输入邮箱或手机号、密码和图形验证码。
- 登录接口必须调用真实 NestJS API，不允许前端静态用户、localStorage mock 或纯前端验证码作为验收依据。
- 运营端登录仅允许平台管理员；客户端登录仅允许已关联企业的企业管理员。

### 2. 用户类型和企业关联

- 运营端用户管理支持创建两类用户：平台管理员、企业管理员。
- 平台管理员不得关联企业，只能登录运营端。
- 企业管理员必须关联一个企业，只能登录客户端。
- 企业管理员登录客户端后，所有客户端 API 必须继承当前企业租户范围，用户、Dashboard、账务、日志等数据不得越权访问其他企业。

### 3. 用户管理功能

- 运营端和客户端用户管理均需接入真实 API，支持添加、编辑、启用/禁用、删除、修改密码。
- 启用/禁用、删除必须弹窗确认。
- 删除采用软删除，历史系统日志、审核记录和业务记录仍可追溯；删除后用户不可登录且列表默认不展示。
- 客户端用户字段必须包含邮箱和手机号，并支持邮箱或手机号登录。
- 所有创建、编辑、启用、禁用、删除、修改密码动作必须写系统日志。

### 4. fail2ban

- 用户连续登录失败 5 次后，账号锁定 24 小时。
- 锁定状态必须写入后端持久化字段，后续登录直接拒绝。
- 登录成功后清空失败次数和锁定状态。

### 2026-07-02 纯 mock 菜单真实化补充

除文档或菜单明确标注为待开发的彩信能力外，第一版所有可进入菜单不得以 mock/static/localStorage 作为系统功能完成标准：

1. 客户端充值套餐、账单流水、批量任务、短信发送、短信签名、短信模板必须调用真实 API；签名/模板新增后进入真实审核状态，发送任务调用真实发送链路。
2. 运营端数据统计、账务账户、发送监控、短信审核、短信记录、安全控制、手机号段库、报备字段库、通道组、通道报备字段、报备任务和报备记录必须调用真实 API。
3. 运营端企业管理使用真实租户、账户、应用、签名、模板接口；企业新增、编辑、启用/禁用、删除必须写真实租户表，删除采用软删除或归档，不允许纯前端删除。
4. 企业签名和企业模板运营端列表只展示真实短信配置数据；彩信签名、彩信模板、彩信通道、彩信记录、彩信任务进度等仍归入待开发，不得用静态样例作为第一版短信验收结果。
5. 后端接口暂缺编辑/删除能力时，前端不得用本地状态模拟成功；应只开放真实能力，缺失能力记录为待补接口。
6. API 不可用、数据库不可用或依赖服务不可用时，页面展示错误态或空态；测试记录标记阻塞或失败，不能用静态兜底数据假装通过。

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

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