fix: enforce carrier-specific channel group routing

docs/first-version-development-requirements.md

@@ -136,22 +136,25 @@
 1. 运营端配置短信通道，包括通道名称、运营商、单价、网关地址、端口、企业代码、账号、密码、接入号、协议参数、启停状态。
 2. 通道运营商支持移动、联通、电信和三网；三网通道可作为移动、联通、电信的通配通道。
 3. 通道必须配置发送地区，发送地区为全国或 34 个省级地区之一；单个通道只能选择一个发送地区。
-4. 运营端配置短信通道组，定义通道优先级、运营商适配、省网路由、全国路由、权重、失败补发开关和补发时间上限。
+4. 运营端配置短信通道组，通道组必须选择且只能选择一个运营商：移动、联通或电信；通道组不允许选择三网。通道组定义通道优先级、运营商分配、省网路由、全国路由、权重、失败补发开关和补发时间上限。
 5. 企业不配置默认通道组；企业应用必须单独配置至少一个运营商通道组，否则页面不可保存，发送时也必须直接失败。
 6. 一个企业应用可以分别绑定移动、联通、电信通道组；可以只绑定其中一类或两类，但不能一个都不绑定。
 7. 发送时先按运营商识别结果分流：移动短信走移动通道组，联通短信走联通通道组，电信短信走电信通道组；识别不出的号码走移动通道组。
-8. 运营商识别优先使用可配置的号码前缀正则表达式，通常匹配手机号前 3 到 4 位；如当前没有配置能力，手机号段库需增加“运营商区分规则”配置。
+8. 运营商识别以可配置的号码前缀正则表达式为准，通常匹配手机号前 3 到 4 位；手机号段库只提供省份/城市识别，其 carrier 字段仅作后台校验或提示，不参与发送运营商判定。
 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 未真正发出时释放冻结且不扣费；本期客户计费不使用通道成本价。
+12. 省网配置当前版本按通道组内省份唯一：同一个通道组内山东只能选择一个通道、河南只能选择一个通道，依此类推；该校验针对通道组明细里的省份配置，不是校验通道本体属性。省网明细的省份必须与引用通道的发送地区一致，例如山东省网不能引用发送地区为河南的通道。
+13. 全国通道可配置多个，并按优先级依次补发；同一通道组内全国通道优先级禁止重复，本期不支持权重分流。
+14. 通道组明细 `carrier` 必须保留并参与发送逻辑，且必须等于通道组运营商。三网只允许作为通道本体能力 `SmsChannel.carrier=all`，表示该通道可被运营分配到移动、联通或电信通道组；一旦放入某个通道组，只能服务该通道组所属运营商。
+15. 通道组明细引用通道时必须校验通道能力：移动组只能引用移动通道或三网通道，联通组只能引用联通通道或三网通道，电信组只能引用电信通道或三网通道。
+16. 未命中企业应用通道组或无可用通道时不得 fallback 到全局第一个 active 通道，应将该短信标记为 failed，并记录可读失败原因、trace 和系统日志；客户端本期不展示通道细节。
+17. 可发送通道必须同时满足：通道业务状态 active、CMPP 连接状态 online、当前连接数大于 0、心跳未失败；auth_failed、heartbeat_timeout、reconnecting、disconnected 或当前连接数为 0 的通道均不可被选中。
+18. 多连接通道只要至少 1 条连接 online 且可用即可参与路由；心跳失败应及时更新连接状态，连续 3 次心跳失败后进入重连，重连成功前不可发送。
+19. 通道异常时应支持熔断、降级、切换备用通道和失败重试；失败补发必须在同一企业应用授权的通道组范围内执行，并使用触发补发时的当前通道组配置，保证计费、退款、幂等和 trace 可追踪。
+20. 失败补发除以下情况外均应触发：短信状态为 unknown；距离客户提交时间超过 72 小时；距离客户提交时间超过通道组配置的补发时间上限；通道组关闭失败补发。
+21. 通道组补发时间上限由运营端配置，最大不得超过 72 小时；本期不配置最大补发次数、补发间隔、失败类型白名单或人工重发能力，进入最终 failed/timeout 后不再人工重发。
+22. 提交 accepted 后立即按企业应用配置的客户费率扣费；补发过程中最终成功只扣一次，submit failed 未真正发出时释放冻结且不扣费；failed receipt 导致最终全失败时退款；本期客户计费不使用通道成本价。
 
 ### 4.7 通道签名报备
 
@@ -163,6 +166,7 @@
 6. 运营端在报备任务或通道报备详情页导入通道回执。
 7. 系统根据回执同步签名在各通道的报备状态。
 8. 报备记录保留每次导出、导入、状态变更和操作人。
+9. 发送前必须校验最终选中通道上的签名报备任务为 approved；补发切换到新通道时必须重新按新通道校验报备状态，未通过则该次发送失败。
 
 ### 4.8 回执与上行
 
@@ -170,20 +174,23 @@
 2. 回执状态至少包括提交成功、提交失败、发送成功、发送失败、未知、超时。
 3. 提交后 72 小时仍为未知的短信转超时，返回客户失败。
 4. 超时前允许人工同步、重新拉取回执或接收供应商二次回执；所有二次回执必须记录历史。
-5. 上行短信接入后优先按手机号、接入号、企业/应用、时间窗口匹配下发记录。
-6. 接入号匹配不到企业/应用时，展示近期平台对此手机号下发的短信供人工判断。
-7. 完全匹配不到的上行短信仍需入库，并展示为未匹配。
-8. 客户端可查看本企业上行短信，运营端可查看全平台上行短信。
+5. 旧通道迟到的 failed receipt 如果对应短信已经由新通道 delivered，不得覆盖短信记录最终 delivered 状态；短信详情弹窗必须能看到该历史 failed receipt。
+6. 重复提交结果或重复回执必须幂等处理，不得重复扣费、重复释放冻结或重复退款。
+7. 上行短信接入后优先按手机号、接入号、企业/应用、时间窗口匹配下发记录。
+8. 接入号匹配不到企业/应用时，展示近期平台对此手机号下发的短信供人工判断。
+9. 完全匹配不到的上行短信仍需入库，并展示为未匹配。
+10. 客户端可查看本企业上行短信，运营端可查看全平台上行短信。
 
 ### 4.9 账户计费
 
 1. 客户端可查看充值套餐、购买或申请充值套餐、查看账单流水。
-2. 发送创建时按短信内容计费条数、企业单价或套餐规则生成预估费用，计费条数只按 70/67 字规则拆分。
+2. 发送创建时按短信内容计费条数、企业应用客户单价或套餐规则生成预估费用，计费条数只按 70/67 字规则拆分；不按移动、联通、电信配置不同客户价。
 3. 平台需在发送前检查企业账户余额、套餐余量或授信额度。
 4. 发送链路需记录计费条数、计费单价、计费金额、账务状态。
 5. 账单流水与短信记录可追溯关联，支持按企业、应用、任务、手机号、时间对账。
 6. 最终失败、超时失败需要退费。
-7. 计费口径可配置为按提交成功计费或按回执成功计费。
+7. 三网通道成本只用于平台内部成本核算，不影响客户扣费金额。
+8. 当前版本计费口径固定为提交 accepted 扣费、最终 failed receipt/timeout 退款。
 
 ## 5. 功能需求
 
@@ -479,7 +486,7 @@
 4. Send Worker 消费消息，校验黑名单、敏感词、限额。
 5. 使用可配置号码前缀正则识别运营商；识别不出时按移动处理。
 6. 使用手机号段库识别号码省份和城市；识别不出省份时按全国路由处理。
-7. 按企业应用绑定的对应运营商通道组执行路由：先匹配省网通道，再匹配全国通道；不得直接绑定或 fallback 到非授权单通道。
+7. 按企业应用绑定的对应运营商通道组执行路由：通道组只能是移动、联通、电信之一，发送时必须同时满足路由规则运营商、通道组运营商、通道组明细 carrier 与号码识别运营商一致；再校验通道本体 carrier 为对应运营商或三网；最后先匹配省网通道，再匹配全国通道，不得直接绑定或 fallback 到非授权单通道。
 8. 过滤业务 disabled、连接离线、认证失败、心跳超时或无可用连接数的通道。
 9. 通过通道限速器控制 TPS。
 10. 调用 Gateway Adapter 提交短信。
@@ -521,8 +528,8 @@
 ### 9.3 通道与路由
 
 - sms_channel：短信通道。
-- sms_channel_group：通道组。
-- sms_channel_group_item：通道组通道明细。
+- sms_channel_group：通道组，必须配置单一运营商 `mobile/unicom/telecom`，不支持三网通道组。
+- sms_channel_group_item：通道组通道明细，`carrier` 必须等于所属通道组运营商；省网明细按 `groupId + province` 唯一，全国明细可多条。
 - channel_route_rule：路由规则。
 - channel_health_metric：通道健康指标。
 

docs/system-functional-test-cases.md

@@ -248,16 +248,27 @@
 ### TC-ADMIN-004 通道组与路由规则
 
 - 优先级：P0
-- 前置条件：存在主通道和备用通道。
+- 前置条件：存在移动、联通、电信专属通道和三网通道，存在主通道和备用通道。
 - 步骤：
-  1. 创建通道组。
-  2. 添加主通道优先级 10、备用通道优先级 20。
-  3. 创建租户/应用维度路由规则。
-  4. 创建发送任务触发送链路。
+  1. 创建移动通道组、联通通道组、电信通道组。
+  2. 尝试创建三网通道组。
+  3. 在移动通道组中添加 mobile item，引用移动通道或三网通道。
+  4. 尝试在移动通道组中添加 unicom item 或引用电信专属通道。
+  5. 尝试在移动通道组中添加山东省网 item，但引用发送地区为河南的通道。
+  6. 在同一通道组中为山东省重复添加第二个省网通道。
+  7. 添加主通道优先级 10、备用全国通道优先级 20，并尝试添加另一个优先级 20 的全国通道。
+  8. 创建租户/应用维度路由规则。
+  9. 创建发送任务触发送链路。
 - 预期结果：
+  - 只能创建 mobile/unicom/telecom 通道组，三网通道组被拒绝。
+  - 通道组明细 carrier 必须等于通道组运营商。
+  - 通道组明细引用通道时必须满足通道本体能力兼容：移动组只允许 mobile/all，联通组只允许 unicom/all，电信组只允许 telecom/all。
+  - 省网 item 的省份必须与通道发送地区一致。
+  - 同一通道组内同一省份只能配置一个通道，全国通道可配置多个但优先级不能重复。
   - 路由优先命中租户/应用规则。
   - 主通道 active 时选择主通道。
   - 主通道 disabled 时选择备用 active 通道。
+  - 通道组不支持权重分流，同优先级全国通道配置被拒绝。
 
 ### TC-ADMIN-005 签名报备任务生成与导出
 
@@ -286,6 +297,7 @@
   - 报备任务状态变为 approved。
   - 签名 `reportStatus` 同步为 approved。
   - 报备记录包含 receipt_import。
+  - 发送前仅允许使用最终选中通道上报备状态为 approved 的签名。
 
 ### TC-ADMIN-007 报备回执导入失败
 
@@ -613,11 +625,12 @@
 ### TC-BILLING-003 submit 成功扣费
 
 - 优先级：P0
-- 前置条件：计费口径为 submit_success。
+- 前置条件：企业应用已配置客户单价，发送任务已冻结预算。
 - 步骤：模拟 Gateway 返回 submit accepted。
 - 预期结果：
   - 生成 charged 流水。
   - 短信计费记录状态更新为 charged。
+  - 扣费金额按企业应用客户单价计算，不按通道成本价或运营商差异价计算。
   - 可按 messageId 对账。
 
 ### TC-BILLING-004 最终失败退款
@@ -629,6 +642,7 @@
   - 短信状态 failed/undelivered。
   - 生成 refunded 流水。
   - 退款金额与原扣费一致。
+  - 重复 failed receipt 不重复退款。
 
 ### TC-BILLING-005 72 小时超时退款
 
@@ -709,6 +723,7 @@
   3. 查询 submit record、trace 和路由日志。
 - 预期结果：
   - 系统按可配置前缀正则识别运营商，并按手机号段库查询省份和城市。
+  - 手机号段 carrier 仅作为后台校验或提示，不改变正则识别出的发送运营商。
   - trace 记录识别出的运营商、省份和城市。
   - 路由优先选择山东省网通道 A。
   - Gateway SubmitCommand 的 channelId 为 A。
@@ -741,6 +756,7 @@
   - 补发不跨出企业应用授权通道组。
   - 原失败原因、补发次数、前后 channelId 和状态流转在 trace 中可查。
   - 最终成功只按企业应用客户费率扣一次，不按通道成本价重复扣费。
+  - 补发选择通道时使用当前通道组配置，并重新校验新通道上的签名报备状态。
 
 ### TC-SEND-015 企业应用通道组保存校验
 
@@ -768,17 +784,21 @@
   - 联通号码进入联通通道组。
   - 电信号码进入电信通道组。
   - 运营商识别失败时进入移动通道组。
+  - 若手机号段库 carrier 与正则识别结果冲突，以正则识别结果为准，号段 carrier 仅记录为提示信息。
 
 ### TC-SEND-017 三网通道作为运营商通配
 
 - 优先级：P0
-- 前置条件：企业应用绑定移动通道组；移动通道组内无可用移动全国通道，但有可用三网全国通道。
+- 前置条件：企业应用绑定移动通道组；移动通道组 carrier 为 mobile；组内明细 carrier 为 mobile；组内无可用移动全国通道，但有可用三网全国通道。
 - 步骤：
   1. 提交移动号码。
   2. 触发送 worker。
   3. 查询 submit record 和 trace。
+  4. 将同一三网通道放入联通通道组，再提交移动号码。
 - 预期结果：
-  - 三网通道可作为移动、联通、电信的通配通道参与路由。
+  - 三网通道本体 `channel.carrier=all` 只表示通道能力，可被运营分配到移动、联通或电信通道组。
+  - 移动号码只会选择移动通道组内 `item.carrier=mobile` 且通道本体为 mobile/all 的通道。
+  - 放入联通通道组的三网通道不能被移动号码选中。
   - route/trace 标明实际命中的三网通道。
 
 ### TC-SEND-018 失败补发停止条件
@@ -798,6 +818,33 @@
   - 超过通道组补发时间上限不触发补发。
   - 通道组关闭失败补发时不触发补发。
 
+### TC-SEND-019 迟到旧通道回执不覆盖最终成功
+
+- 优先级：P0
+- 前置条件：短信首次通过通道 A 发送失败并补发到通道 B，通道 B 已返回 delivered。
+- 步骤：
+  1. 查询短信记录列表，确认该短信当前状态为 delivered，channelId/gatewayMessageId 为通道 B。
+  2. 模拟通道 A 迟到的 failed receipt。
+  3. 查询短信记录列表、短信详情弹窗、回执历史和账单流水。
+- 预期结果：
+  - 短信记录列表仍展示最终 delivered 状态，不被通道 A 的 failed receipt 覆盖。
+  - 短信详情弹窗可见通道 A 的历史 failed receipt。
+  - 不产生重复退款，也不改变已成功短信的最终计费状态。
+
+### TC-SEND-020 重复回调幂等
+
+- 优先级：P0
+- 前置条件：存在一条已 submit accepted 并完成账务扣费的短信。
+- 步骤：
+  1. 连续发送两次相同 submit accepted 回调。
+  2. 连续发送两次相同 failed receipt 回调。
+  3. 查询短信记录、提交记录、回执记录、短信计费记录和账户流水。
+- 预期结果：
+  - 提交/回执历史可追踪，但短信最终状态按最新有效尝试处理。
+  - accepted 不重复扣费。
+  - failed receipt 不重复退款。
+  - 账户流水、短信计费记录和 reconciliation 无重复金额。
+
 ### TC-SEND-004 SubmitResult accepted
 
 - 优先级：P0

docs/testing-plan.md

@@ -15,9 +15,9 @@
 - 目标：覆盖纯业务规则、状态流转、查询条件、Gateway tracker/reconnector/health 等无需真实外部服务的逻辑。
 - 当前重点：
   - 风控规则评估：最大号码数、重复率、非法号码率、黑名单率、模板变量异常、直接拒绝、进入人工审核。
-  - 计费：费用预估、余额检查、冻结、扣费、释放、退款、短信计费记录。
-  - 发送链路：批量任务创建、手机号拆分、发送入队、运营商前缀正则分流、手机号段归属地识别、应用运营商通道组路由、省网/全国路由、submit result 更新、receipt 更新、失败补发、补发停止条件、uplink 记录、72 小时未知转超时。
-  - 通道与报备：通道创建、通道发送地区、三网通道通配、通道组路由规则、企业应用通道组保存校验、禁止单通道发送规则、签名报备任务、导出、回执导入、签名状态同步。
+  - 计费：费用预估、余额检查、冻结、提交 accepted 扣费、失败回执退款、短信计费记录、应用级客户费率、重复回调幂等。
+  - 发送链路：批量任务创建、手机号拆分、发送入队、运营商前缀正则分流、手机号段归属地识别、应用运营商通道组路由、省网/全国路由、submit result 更新、receipt 更新、迟到旧回执不覆盖最终成功、失败补发、补发停止条件、uplink 记录、72 小时未知转超时。
+  - 通道与报备：通道创建、通道发送地区、三网通道通配、单运营商通道组、通道组明细 carrier 参与发送、省份与通道发送地区一致性、全国通道优先级唯一、企业应用通道组保存校验、禁止单通道发送规则、最终选中通道签名报备校验、签名报备任务、导出、回执导入、签名状态同步。
   - 查询统计：发送链路 trace、对账 reconciliation、dashboard/statistics。
   - Gateway：SEQID/MSGID 追踪、重连、health、gocmpp submit/resp 模拟器。
 

docs/testing-progress.md

@@ -437,3 +437,75 @@ npm run verify:phase8
 ### 待复测
 
 - 浏览器 smoke 和真实文件上传 smoke 需要在生产验证环境补跑，重点复测客户端发送、签名材料上传、短信审核、短信记录、客户管理和报备任务。
+
+## 2026-07-03 单运营商通道组、应用级费率和回执幂等
+
+### 本轮修复范围
+
+- 通道组规则：
+  - `SmsChannelGroup.carrier` 固化为移动、联通、电信三选一，禁止三网通道组。
+  - `SmsChannelGroupItem.carrier` 保留并参与发送，必须等于通道组运营商。
+  - 三网只作为通道本体能力 `SmsChannel.carrier=all`，放入某个通道组后只服务该组运营商。
+  - 同一通道组内同一省份只能配置一个通道；省份 item 必须引用发送地区一致的通道。
+  - 全国通道允许多个，但同一通道组内全国通道优先级禁止重复；本期不做权重分流。
+  - 路由规则必须绑定应用、运营商、通道组，且 route carrier 必须等于 group carrier。
+- 发送和计费规则：
+  - 运营商以号码前缀正则为准；手机号段库只提供省份/城市，carrier 仅作后台提示或校验。
+  - 发送前校验最终选中通道的签名报备任务为 approved，补发切换通道时重新校验。
+  - 企业应用新增 `customerUnitPrice`，客户扣费按应用级客户费率；通道成本只作内部成本。
+  - 迟到旧通道 failed receipt 不覆盖新通道 delivered 最终状态；历史回执仍入库可查。
+  - 重复 submit/receipt 回调不得重复扣费、释放冻结或退款。
+  - 补发使用触发时当前通道组配置；本期不考虑人工重发。
+- 前端和真实 smoke：
+  - 企业应用表单增加客户单价输入，保存时写入真实应用 API。
+  - 企业应用按移动、联通、电信分别选择通道组，选项按通道组 carrier 过滤。
+  - 真实 smoke seed 补充应用客户单价、三网通道放入移动组、签名-通道 approved 报备。
+
+### 新增/更新测试
+
+| 测试文件 | 新增覆盖 |
+| --- | --- |
+| `api/src/channels/channels.service.spec.ts` | 单运营商通道组、通道组 item carrier 校验、通道 carrier 兼容、省份与发送地区一致、同省唯一、全国优先级唯一、route carrier 与 group carrier 一致。 |
+| `api/src/send-chain/send-chain.service.spec.ts` | 通道组 item carrier 参与发送、最终通道签名报备校验、应用级客户费率、迟到旧 failed receipt 不覆盖 delivered、重复账务动作幂等。 |
+| `api/src/sms-config/sms-config.service.spec.ts` | 应用配置与列表在新增客户费率字段后继续通过。 |
+
+### 已执行命令
+
+```bash
+npm --prefix api run prisma:generate
+npm --prefix api test -- channels.service.spec.ts send-chain.service.spec.ts sms-config.service.spec.ts --runInBand
+npm --prefix api test
+npm --prefix api run build
+npm run build
+npm --prefix api run prisma:migrate:deploy
+$env:API_PORT='3101'; $env:API_ENABLE_SEND_WORKER='true'; npm --prefix api run start:dev
+node tools/smoke/real-env-smoke.mjs
+node <inline channel-group rule HTTP smoke>
+npm run spike:contracts
+npm run test:gateway
+npm run verify:phase8
+```
+
+### 当前结果
+
+- Prisma Client 生成通过。
+- 新增迁移已应用到真实 PostgreSQL：
+  - `20260703143000_add_channel_group_carrier`
+  - `20260703152000_add_application_customer_rate`
+- API Jest：10 个 test suite 通过，56 个测试通过。
+- API build 通过。
+- 前端 build 通过，仍存在既有 Vite chunk size warning。
+- 真实 API smoke 通过：
+  - `tools/smoke/real-env-smoke.mjs` 通过，验证真实 API、Prisma/PostgreSQL、Redis/BullMQ、登录、充值、发送任务、worker 入队、文件上传元数据和操作日志。
+  - inline 通道组规则 HTTP smoke 通过，覆盖三网组拒绝、item carrier 不匹配拒绝、通道 carrier 不兼容拒绝、省份/发送地区不匹配拒绝、同省重复拒绝、全国优先级重复拒绝、route carrier/group carrier 不匹配拒绝。
+- Gateway 队列契约通过，4 个示例均验证通过。
+- `npm run test:gateway` 通过，Go Gateway health、connection、tracker、cmpp、spike 测试全部通过。
+- `npm run verify:phase8` 未通过，仍阻塞在已知 BullMQ spike 性能阈值：
+  - 15000 条消息、并发 500。
+  - enqueue TPS 3139.43。
+  - end-to-end TPS 479.02，低于 500 TPS。
+
+### 剩余说明
+
+- `verify:phase8` 当前失败点是独立 BullMQ 性能阈值，不是本轮通道组、计费、报备、回执业务逻辑测试失败。
+- 浏览器端完整手工回归仍建议补跑企业应用创建、通道组配置、短信记录详情弹窗中的历史回执展示。