From db27ace0692d0e5eb5adbea09e112869c883e94a Mon Sep 17 00:00:00 2001
From: hectorzhao <hectorzhao@example.com>
Date: Wed, 1 Jul 2026 15:45:55 +0800
Subject: [PATCH] docs: add customer and cmpp status test steps

---
 docs/system-functional-test-cases.md | 386 ++++++++++++++++++++++++++-
 1 file changed, 385 insertions(+), 1 deletion(-)

diff --git a/docs/system-functional-test-cases.md b/docs/system-functional-test-cases.md
index eee79ae..8358fdc 100644
--- a/docs/system-functional-test-cases.md
+++ b/docs/system-functional-test-cases.md
@@ -23,6 +23,7 @@
 | 号码 | 合法号码、重复号码、非法号码、企业黑名单号码、全局黑名单号码。 |
 | 账户 | 余额充足、余额不足、套餐余量充足、套餐余量不足、授信额度可用。 |
 | 企业认证 | 未认证、待审核、已通过、已驳回四类企业认证资料。 |
+| 客户 | 正常客户、停用客户、欠费客户、未认证客户、跨租户客户、客户联系人和开票资料。 |
 | 导入文件 | UTF-8 CSV、GBK CSV、TXT、超 20 MB 文件、含空行/重复/非法号码/非法字符文件。 |
 | 非法内容 | 控制字符、emoji、换行、不可见字符、超长变量、签名外置内容、敏感词内容。 |
 
@@ -31,12 +32,14 @@
 | 业务闭环 | 必须验证 |
 | --- | --- |
 | 企业认证闭环 | 客户提交资料、运营审核、客户查看状态、驳回重提、通过后才允许使用受限发送能力、日志可追溯。 |
+| 客户管理闭环 | 客户创建、编辑、启停、认证、额度/余额、客户下应用/签名/模板/发送记录联动、租户隔离、日志可追溯。 |
 | 短信应用闭环 | 创建、启停、删除、密钥重置、IP 白名单、模板不匹配策略、变更后对发送实时生效、日志可追溯。 |
 | 签名闭环 | 创建、材料、审核、删除、报备状态变化、发送可用性校验、历史任务不受错误覆盖、日志可追溯。 |
 | 引流信息闭环 | 字段配置、客户填写、删除字段或删除客户引流信息、报备材料影响、发送阻断或审核原因可见。 |
 | 模板闭环 | 单变量、多变量、审核、删除、变量缺失/多传/格式异常、计费预估、发送可用性校验。 |
 | 号码导入闭环 | 文件上传、解析、去重、非法号码、黑名单、导入结果展示、生成任务、生成手机号记录。 |
 | 发送闭环 | 立即发送、定时发送、到点触发、入队、submit、回执、上行、任务进度、发送详情、trace、对账。 |
+| CMPP 连接闭环 | 通道连接状态、登录认证、active test、断线重连、连接异常对路由/发送影响、状态监控和日志告警。 |
 | 内容校验闭环 | 非法字符展示、敏感词、控制字符、内容清洗或拒绝、计费不被非法字符干扰、错误原因可见。 |
 | 计费闭环 | 预估、余额校验、冻结、扣费、释放、退款、短信计费记录、账单流水、对账。 |
 | 系统日志闭环 | 登录、创建、修改、删除、审核、导入导出、密钥重置、发送、报备、账务动作均可查询和定位操作者。 |
@@ -1393,7 +1396,388 @@
   - 历史发送可查询、可对账。
   - 配置删除、发送阻断、定时任务失败均有日志。
 
-## 15. 回归执行建议
+### TC-CUSTOMER-001 运营端创建客户并初始化租户
+
+- 优先级：P0
+- 前置条件：运营管理员已登录。
+- 步骤：
+  1. 运营端新建客户，填写客户名称、客户编码、联系人、手机号、邮箱、状态、备注。
+  2. 保存后打开客户详情。
+  3. 查看客户下应用、签名、模板、账户、认证资料、发送记录入口。
+  4. 使用该客户管理员账号登录客户端。
+- 预期结果：
+  - 创建客户成功，同时生成或关联租户。
+  - 客户详情展示基础信息和业务入口。
+  - 客户管理员只能进入本客户租户上下文。
+  - 系统日志记录客户创建动作和操作者。
+
+### TC-CUSTOMER-002 客户资料编辑影响展示但不破坏历史数据
+
+- 优先级：P1
+- 前置条件：客户已有应用、签名、模板和历史发送记录。
+- 步骤：
+  1. 运营端修改客户名称、联系人、联系电话、备注。
+  2. 客户端刷新工作台和账号信息。
+  3. 运营端查看历史发送记录、账单流水、trace。
+- 预期结果：
+  - 新客户资料在客户端和运营端同步展示。
+  - 历史发送记录、账单流水、trace 仍可查询。
+  - 历史记录中的 tenantId 不变化，必要时展示当前客户名称或历史快照。
+  - 系统日志记录修改前后关键字段。
+
+### TC-CUSTOMER-003 客户停用阻断新发送
+
+- 优先级：P0
+- 前置条件：客户已认证且有可用应用、签名、模板、余额和 active 通道。
+- 步骤：
+  1. 运营端将客户状态改为 disabled。
+  2. 客户端尝试创建立即发送任务。
+  3. 客户端尝试创建定时发送任务。
+  4. API 调用或 CMPP 接入尝试发送。
+  5. 查询系统日志和发送任务列表。
+- 预期结果：
+  - 客户端、API、CMPP 接入的新发送均被阻断。
+  - 错误原因包含客户已停用。
+  - 不生成可发送状态任务，不入队，不扣费。
+  - 历史任务仍可查询。
+  - 系统日志记录客户停用和发送阻断。
+
+### TC-CUSTOMER-004 客户停用对定时任务到点执行的影响
+
+- 优先级：P0
+- 前置条件：客户 active 时已创建未来定时发送任务。
+- 步骤：
+  1. 创建 scheduled 任务。
+  2. 到点前运营端停用客户。
+  3. 等待或触发调度器执行。
+  4. 查询任务详情、账单流水和系统日志。
+- 预期结果：
+  - 定时任务到点前重新校验客户状态。
+  - 客户停用时任务不入队，状态变为 rejected/canceled/failed。
+  - 如已冻结费用，生成 release 流水。
+  - 任务失败原因和系统日志均指向客户停用。
+
+### TC-CUSTOMER-005 客户重新启用恢复发送能力
+
+- 优先级：P0
+- 前置条件：客户曾被停用，应用/签名/模板/报备/账户均可用。
+- 步骤：
+  1. 运营端重新启用客户。
+  2. 客户端创建立即发送任务。
+  3. 模拟 submit accepted 和 delivered。
+  4. 查询任务、发送详情、账单流水。
+- 预期结果：
+  - 客户状态变为 active。
+  - 新发送可进入风控、计费和发送链路。
+  - 发送记录和账务流水完整。
+  - 系统日志记录重新启用动作。
+
+### TC-CUSTOMER-006 客户欠费或额度不足状态联动发送
+
+- 优先级：P0
+- 前置条件：客户余额、套餐余量、授信额度不足，或运营端标记欠费。
+- 步骤：
+  1. 客户端创建发送任务。
+  2. API 调用发送。
+  3. 运营端查看客户账户、账单流水、发送失败记录。
+- 预期结果：
+  - 发送前账户校验失败。
+  - 错误原因包含余额/额度/欠费。
+  - 不生成扣费流水，不投递 Gateway。
+  - 运营端客户详情可看到欠费或余额不足状态。
+
+### TC-CUSTOMER-007 客户租户隔离和越权访问
+
+- 优先级：P0
+- 前置条件：存在客户 A 和客户 B，各有应用、签名、模板、任务、账单流水。
+- 步骤：
+  1. 使用客户 A 用户登录客户端。
+  2. 尝试通过 URL、筛选条件或 API 参数访问客户 B 的资源 id。
+  3. 运营端使用客户维度查询两边数据。
+- 预期结果：
+  - 客户 A 无法访问客户 B 的任何资源。
+  - 返回无权限或无数据，不泄露客户 B 业务信息。
+  - 运营端按客户过滤时数据准确。
+  - 越权访问失败记录进入安全或系统日志。
+
+### TC-CUSTOMER-008 客户删除或归档的业务影响
+
+- 优先级：P0
+- 前置条件：客户有历史任务、账单流水、应用、签名、模板和 scheduled 任务。
+- 步骤：
+  1. 运营端删除、归档或停用客户。
+  2. 客户端尝试登录和发送。
+  3. 到达 scheduled 任务执行时间。
+  4. 运营端查询历史任务、账单流水、trace。
+- 预期结果：
+  - 如系统不允许硬删除，应提示存在业务数据并要求停用/归档。
+  - 被归档/停用客户不能新建发送。
+  - 未执行定时任务不应继续发送。
+  - 历史任务、账单、trace 必须保留可查。
+  - 系统日志记录删除失败、归档或停用动作。
+
+### TC-CMPP-STATUS-001 通道初始连接状态展示
+
+- 优先级：P0
+- 前置条件：运营端已创建 CMPP 通道，Gateway 未启动或未连接。
+- 步骤：
+  1. 打开运营端通道管理和发送监控。
+  2. 查看通道连接状态、最近心跳时间、重连次数、错误信息。
+  3. 调用健康检查或监控接口。
+- 预期结果：
+  - 通道业务状态 active 与 CMPP 连接状态分开展示。
+  - Gateway 未连接时连接状态显示 disconnected/unknown。
+  - 最近心跳为空或过期。
+  - 不误显示为可提交状态。
+
+### TC-CMPP-STATUS-002 CMPP 登录成功后连接状态变为在线
+
+- 优先级：P0
+- 前置条件：模拟 SMSC 可用，通道账号密码正确。
+- 步骤：
+  1. 启动 Gateway。
+  2. Gateway 连接模拟 SMSC 并完成 CMPP connect/login。
+  3. 运营端刷新通道详情和监控。
+  4. 创建发送任务并提交一条短信。
+- 预期结果：
+  - 连接状态变为 connected/online。
+  - 展示连接建立时间、最近 active test 时间、窗口大小或可用窗口。
+  - 发送任务可被路由到该通道。
+  - submit accepted 后通道健康指标更新。
+
+### TC-CMPP-STATUS-003 CMPP 登录失败展示认证错误
+
+- 优先级：P0
+- 前置条件：通道账号、密码或企业代码配置错误。
+- 步骤：
+  1. 启动 Gateway 连接模拟 SMSC。
+  2. 模拟 SMSC 返回登录失败。
+  3. 运营端查看通道状态和错误信息。
+  4. 创建发送任务。
+- 预期结果：
+  - 连接状态显示 auth_failed/login_failed。
+  - 错误信息包含认证失败原因或错误码。
+  - 发送路由不应选择该通道，除非无备用通道时任务失败并展示原因。
+  - 系统日志或告警记录登录失败。
+
+### TC-CMPP-STATUS-004 Active Test 心跳超时变更连接状态
+
+- 优先级：P0
+- 前置条件：Gateway 已连接模拟 SMSC。
+- 步骤：
+  1. 模拟 SMSC 停止响应 active test。
+  2. 等待心跳超时。
+  3. 查看通道连接状态。
+  4. 提交发送任务。
+- 预期结果：
+  - 通道连接状态从 online 变为 heartbeat_timeout/disconnected。
+  - 最近心跳时间不再刷新。
+  - Gateway 进入重连流程。
+  - 新发送不应继续提交到该失联连接，应走备用通道或失败排队。
+
+### TC-CMPP-STATUS-005 断线重连成功后恢复发送
+
+- 优先级：P0
+- 前置条件：通道在线，存在备用通道或队列可暂存。
+- 步骤：
+  1. 模拟 SMSC 断开 TCP 连接。
+  2. 观察 Gateway 重连次数和连接状态。
+  3. 恢复模拟 SMSC。
+  4. 提交新发送任务。
+- 预期结果：
+  - 断线后状态变为 disconnected/reconnecting。
+  - 重连次数增加，日志记录断线原因。
+  - 重连成功后状态回到 online。
+  - 新发送可正常 submit。
+  - 断线期间未确认的消息有明确重试、失败或待补偿状态。
+
+### TC-CMPP-STATUS-006 通道连接离线时路由到备用通道
+
+- 优先级：P0
+- 前置条件：通道组包含主通道 A 和备用通道 B，A active 但连接离线，B active 且 online，签名在 B 报备通过。
+- 步骤：
+  1. 确认 A 业务状态 active、连接状态 disconnected。
+  2. 确认 B 业务状态 active、连接状态 online。
+  3. 创建发送任务。
+  4. 查询 submit record 和 trace。
+- 预期结果：
+  - 路由跳过连接离线的 A。
+  - 选择 B 提交。
+  - trace 显示实际 channelId 为 B。
+  - 通道健康指标记录 A 不可用和 B 提交成功。
+
+### TC-CMPP-STATUS-007 无在线通道时发送任务失败或等待
+
+- 优先级：P0
+- 前置条件：路由范围内所有通道连接状态均 disconnected/auth_failed/heartbeat_timeout。
+- 步骤：
+  1. 创建发送任务。
+  2. 触发送 worker。
+  3. 查看任务状态、发送明细、系统日志。
+- 预期结果：
+  - 系统不向离线连接 submit。
+  - 按设计进入 delayed/retry、failed 或 pending_channel 状态。
+  - 客户端和运营端展示“无可用在线通道”原因。
+  - 不产生 submit accepted 记录，不错误扣费。
+
+### TC-CMPP-STATUS-008 连接状态与通道启停状态组合
+
+- 优先级：P1
+- 前置条件：通道连接 online。
+- 步骤：
+  1. 运营端将通道业务状态改为 disabled。
+  2. 查看连接状态是否仍可展示。
+  3. 创建发送任务。
+  4. 再将通道启用。
+- 预期结果：
+  - disabled 通道即使连接 online，也不可被路由选中。
+  - 连接状态可继续用于运维观察，但发送可用性显示为不可用。
+  - 启用后如连接仍 online，可恢复路由；如连接已断开，需要等待重连。
+  - 系统日志记录启停操作。
+
+### TC-CMPP-STATUS-009 慢响应导致窗口占满和状态告警
+
+- 优先级：P1
+- 前置条件：模拟 SMSC 可配置慢 submit resp，Gateway 有滑动窗口限制。
+- 步骤：
+  1. 配置模拟 SMSC 延迟 submit resp。
+  2. 连续提交多条短信直到窗口占满。
+  3. 查看通道监控和队列积压。
+  4. 恢复 SMSC 正常响应。
+- 预期结果：
+  - 通道状态展示窗口占用、慢响应或拥塞指标。
+  - 新消息排队等待，不丢失。
+  - 恢复后积压逐步下降。
+  - 超时消息按 submit timeout 处理并可追踪。
+
+### TC-CMPP-STATUS-010 连接状态变化写入日志和监控
+
+- 优先级：P0
+- 前置条件：通道经历 online、disconnected、reconnecting、online 状态变化。
+- 步骤：
+  1. 触发连接成功、断线、重连成功。
+  2. 查询通道健康指标。
+  3. 查询系统日志或运维日志。
+- 预期结果：
+  - 每次连接状态变化都有时间戳。
+  - 健康指标记录重连次数、连接可用性、submit 成功/失败。
+  - 日志包含 channelId、channelCode、错误原因、恢复时间。
+  - 运营端监控可按通道查看状态历史。
+
+## 15. 测试实施步骤
+
+系统功能测试建议分 8 步执行。第一步先做测试基线和数据准备，不直接开始点页面；原因是后续所有闭环都依赖客户、认证、应用、签名、模板、通道、账户和模拟 Gateway 的一致初始状态。
+
+### 第一步：准备测试环境和基线数据
+
+- 目标：让后续所有测试在同一套可复现数据上执行。
+- 执行内容：
+  1. 启动或确认 PostgreSQL、Redis、MinIO、API、前端、Gateway、模拟 SMSC。
+  2. 初始化客户 A、客户 B、运营管理员、运营审核员、客户管理员、客户普通用户。
+  3. 初始化 active/disabled 客户、未认证/待审核/已认证/驳回企业认证资料。
+  4. 初始化可用应用、停用应用、待删除应用。
+  5. 初始化签名、引流信息、模板、多变量模板、通道、通道组、路由规则。
+  6. 初始化账户余额、套餐余量、欠费/不足余额场景。
+  7. 准备 CSV/TXT/GBK/大文件/非法字符/黑名单号码测试文件。
+  8. 确认 Gateway 模拟器可切换 online、auth_failed、heartbeat_timeout、disconnected、slow_response。
+- 产出物：
+  - 测试账号清单。
+  - 测试客户和租户 id。
+  - 测试应用/签名/模板/通道 id。
+  - 测试文件目录。
+  - 环境健康检查截图或日志。
+
+### 第二步：执行静态配置和权限基础测试
+
+- 覆盖范围：
+  - 客户创建、编辑、启停、租户隔离。
+  - 登录、用户权限、客户越权访问。
+  - 应用、签名、模板、引流字段、通道、路由规则的基础 CRUD。
+- 通过标准：
+  - 数据隔离正确。
+  - 启停/删除状态能影响后续发送。
+  - 系统日志记录所有关键配置变更。
+
+### 第三步：执行认证、审核、报备闭环测试
+
+- 覆盖范围：
+  - 企业认证提交、审核通过、驳回重提、企业停用。
+  - 签名审核、模板审核、短信审核。
+  - 签名引流信息和通道报备状态变更。
+- 通过标准：
+  - 审核状态在客户端和运营端一致。
+  - 报备未通过或失效时发送被阻断。
+  - 审核记录、报备记录、系统日志三类证据完整。
+
+### 第四步：执行发送前校验测试
+
+- 覆盖范围：
+  - 多变量模板、变量缺失/多传/超长。
+  - 导入文件解析、重复、非法、黑名单。
+  - 非法字符、敏感词、内容展示和计费预估。
+  - 风控规则和账户余额校验。
+- 通过标准：
+  - 所有阻断场景都不入队、不扣费，原因可读。
+  - 所有允许场景的计费预估与最终内容一致。
+  - 风控命中记录包含阈值、实际值、动作和原因。
+
+### 第五步：执行发送链路闭环测试
+
+- 覆盖范围：
+  - 立即发送。
+  - 定时发送创建、查看、取消、到点执行。
+  - 导入数据发送。
+  - submit result、receipt、uplink、72 小时超时。
+- 通过标准：
+  - 批量任务、手机号记录、提交记录、回执记录、上行记录完整。
+  - 任务进度统计准确。
+  - trace 能串起 messageId、submitId、sequenceId、gatewayMessageId。
+
+### 第六步：执行计费和对账测试
+
+- 覆盖范围：
+  - 70/67 计费。
+  - 预估、冻结、扣费、释放、退款。
+  - 失败退款、超时退款。
+  - 账单流水和 reconciliation。
+- 通过标准：
+  - 每条短信记录可追溯到账务流水。
+  - 成功、失败、超时的金额方向正确。
+  - 对账 diff 符合预期。
+
+### 第七步：执行 CMPP 连接状态和通道路由测试
+
+- 覆盖范围：
+  - online、auth_failed、heartbeat_timeout、disconnected、reconnecting、slow_response。
+  - 主备通道路由。
+  - 无在线通道。
+  - 连接状态和业务启停状态组合。
+- 通过标准：
+  - 离线或认证失败通道不被错误提交。
+  - 可用备用通道能接管。
+  - 连接状态变化有监控、健康指标和日志。
+
+### 第八步：执行回归验证和报告归档
+
+- 覆盖范围：
+  - 自动化测试命令。
+  - 前端 smoke。
+  - 性能 smoke。
+  - 缺陷复测。
+- 建议执行命令：
+  ```bash
+  npm run spike:contracts
+  npm run test:api
+  npm run test:gateway
+  npm run verify:phase8
+  ```
+- 产出物：
+  - 测试执行记录。
+  - 缺陷列表和复测结果。
+  - 性能 smoke 结果。
+  - 未覆盖项和延期说明。
+
+## 16. 回归执行建议
 
 每次阶段回归至少执行：