lislgosms/docs/phase-4-channel-reporting-plan.md

阶段 4 通道与报备实施计划

目标

让运营端能配置短信通道、通道组、路由规则和签名报备流程；让系统能记录签名在各通道的报备资料、报备任务、导出文件、回执导入和状态同步。

阶段 4 不实现真实发送链路，真实 CMPP 提交在阶段 7 发送链路接入；本阶段只建立通道和报备配置闭环。

实施步骤

1. Prisma 模型

   • SmsChannel
   • SmsChannelGroup
   • SmsChannelGroupItem
   • ChannelRouteRule
   • ChannelHealthMetric
   • ChannelReportField
   • SignatureReportMaterial
   • ChannelSignatureReportTask
   • ChannelSignatureReportRecord
   • ReportExportFile
   • ReportReceiptImport

2. NestJS 模块

   • ChannelsModule
   • 通道 CRUD、测试短信占位、通道健康指标查询。
   • 通道组 CRUD、通道组成员配置。
   • 路由规则 CRUD。
   • 报备字段配置 CRUD。
   • 签名报备资料登记。
   • 报备任务生成、导出记录、回执导入记录、报备记录查询。

3. 状态同步

   • 生成报备任务时记录 pending。
   • 导出报备资料时记录导出文件和报备记录。
   • 导入回执时记录导入批次、回执结果，并更新任务状态。

4. 验证

   • cd api && npm run prisma:generate
   • cd api && npm run build
   • API health 冒烟
   • npm run verify:phase3

验收标准

• Prisma Client 生成成功。
• API 构建成功。
• ChannelsModule 被 AppModule 引入。
• 通道、通道组、路由规则、报备字段、报备任务基础接口存在。
• 报备导出/导入记录和报备状态同步接口存在。
• 阶段 4 进度文档记录验证结果。

2026-09-17 有效签名名称唯一性

本节补充签名新增、修改和状态恢复规则；批量导入仍遵循 补资料方案 的字段合并规则。

• 同一企业、同一应用下，完整签名名称精确相同时只能存在一条有效记录。有效指审核状态不是 deleted 或 disabled，包含草稿、待审、通过和驳回。未绑定应用作为独立范围，同企业未绑定应用的同名有效签名也唯一；不同企业、不同应用允许同名。
• 新增、改名、换应用、提交审核、审核及状态恢复均执行接口查重，修改排除自身；冲突返回 HTTP 409 和“同一企业、同一应用下已存在同名有效签名，请修改已有签名资料”。保留既有认证、租户校验、审核及报备资料行为，无新增权限、页面和短信链路变更。
• PostgreSQL 使用两个部分唯一索引：绑定应用的 (tenantId, applicationId, name)，未绑定应用的 (tenantId, name)，都排除停用及删除状态。并发以数据库最终约束为准，唯一冲突转为相同业务错误；Prisma schema 用注释指明 SQL 所有权，不用普通复合唯一键冒充部分索引。
• 迁移在事务和写锁内检查历史有效重名；发现冲突则明确报错、整体回滚，禁止自动删除、合并或改状态。发布前需只读盘点并另行确认历史治理，不把迁移阻断当作成功；本轮只本地提交，不部署。
• 批量导入仍是补资料：优先匹配同范围有效签名，其次沿用未删除的停用记录；原签名 ID、未映射字段、用途及关联记录保留。导入暂存后新增了同名签名时，审核阶段重新匹配并更新；并发创建冲突时重新读取有效记录转为资料更新，仅重试一次，不吞其他错误。已有指定目标不会暗中改写为另一条记录，恢复冲突明确失败。
• 验收覆盖新增/编辑/换应用/空应用/状态恢复、不同企业应用、并发创建、直接 SQL 防重、历史迁移失败回滚，以及导入暂存与审核后补资料保留。使用本机隔离 PostgreSQL 和真实服务/API，不发送短信，不改线上资料；线上历史数据与部署留作未验证项。