docs: add system functional test cases

docs/system-functional-test-cases.md

@@ -0,0 +1,733 @@
+# CMPP 短信平台第一版系统功能测试用例
+
+## 1. 用例说明
+
+本文档补充第一版系统功能测试用例，面向验收测试、人工回归测试和后续 E2E 自动化改造。用例不依赖真实运营商 CMPP 网关；Gateway 场景使用项目模拟器、队列契约或测试替身。
+
+优先级定义：
+
+- P0：第一版上线阻断项，必须通过。
+- P1：核心功能回归项，建议每轮发布通过。
+- P2：增强/边界项，可按时间和环境选择执行。
+
+## 2. 测试数据基线
+
+| 数据类型 | 建议数据 |
+| --- | --- |
+| 租户 | `tenant-a` 正常企业，`tenant-b` 用于租户隔离验证。 |
+| 用户 | 客户端企业管理员、客户端普通用户、运营管理员、运营审核员。 |
+| 短信应用 | `app-a`，状态 active，日限额开启，模板不匹配策略分别准备 reject/manual_review/allow 三组。 |
+| 签名 | `【测试签名】`，审核通过且报备通过；另准备待审核、驳回、报备失败签名。 |
+| 模板 | 验证码模板 `验证码为 ${code}`，营销模板 `尊敬的${name}，优惠活动开始`，分别准备草稿、待审核、通过、驳回。 |
+| 通道 | active CMPP 通道、disabled 通道、备用通道；通道组包含主备优先级。 |
+| 号码 | 合法号码、重复号码、非法号码、企业黑名单号码、全局黑名单号码。 |
+| 账户 | 余额充足、余额不足、套餐余量充足、套餐余量不足、授信额度可用。 |
+
+## 3. 客户端功能用例
+
+### TC-CLIENT-001 登录与租户隔离
+
+- 优先级：P0
+- 前置条件：存在 `tenant-a` 和 `tenant-b`，两个租户各有发送任务和账单流水。
+- 步骤：
+  1. 使用 `tenant-a` 企业管理员登录客户端。
+  2. 打开工作台、批量任务、发送详情、上行短信、账单流水。
+  3. 使用查询条件搜索 `tenant-b` 的任务编号或手机号。
+- 预期结果：
+  - 登录成功，返回当前租户上下文。
+  - 所有列表只展示 `tenant-a` 数据。
+  - 查询 `tenant-b` 数据无结果或返回无权限。
+
+### TC-CLIENT-002 创建短信应用并重置密钥
+
+- 优先级：P1
+- 前置条件：企业管理员已登录。
+- 步骤：
+  1. 创建短信应用，填写名称、场景、回调地址、IP 白名单、日限额。
+  2. 查询应用列表和详情。
+  3. 执行应用密钥重置。
+- 预期结果：
+  - 应用创建成功，状态为 active。
+  - IP 白名单、日限额、模板不匹配策略保存正确。
+  - 密钥重置后旧密钥不可见，新密钥或密钥摘要更新。
+  - 生成操作日志。
+
+### TC-CLIENT-003 签名创建、材料上传与提交审核
+
+- 优先级：P0
+- 前置条件：MinIO 不可用时使用文件服务 mock 或跳过真实上传。
+- 步骤：
+  1. 创建短信签名，填写名称、用途、引流信息。
+  2. 上传或登记签名证明材料。
+  3. 提交审核。
+  4. 打开签名列表和详情。
+- 预期结果：
+  - 签名初始为 draft。
+  - 材料与签名关联成功。
+  - 提交后签名状态变为 pending。
+  - 生成审核记录。
+
+### TC-CLIENT-004 模板变量识别与提交审核
+
+- 优先级：P0
+- 前置条件：存在 active 应用和可用签名。
+- 步骤：
+  1. 创建模板 `验证码为 ${code}`。
+  2. 保存后查看变量列表。
+  3. 提交模板审核。
+- 预期结果：
+  - 系统识别变量 `code`。
+  - 计费条数按 70/67 字规则预估。
+  - 提交后模板状态为 pending。
+  - 生成审核记录。
+
+### TC-CLIENT-005 客户端发送任务创建成功
+
+- 优先级：P0
+- 前置条件：应用、签名、模板审核通过；签名报备通过；账户余额充足；通道可用。
+- 步骤：
+  1. 选择应用、签名、模板。
+  2. 填写模板变量。
+  3. 输入 3 个合法手机号。
+  4. 提交立即发送。
+  5. 查看批量任务详情和发送明细。
+- 预期结果：
+  - 返回批量任务编号。
+  - 批量任务 `sourceType=client`。
+  - 手机号维度生成 3 条短信记录。
+  - 任务进入 queued/sending/completed 之一的正常流转状态。
+  - 发送明细可按手机号查询。
+
+### TC-CLIENT-006 手机号去重与非法号码提示
+
+- 优先级：P0
+- 前置条件：存在通过审核的发送资源。
+- 步骤：
+  1. 输入合法号码 A、合法号码 A、非法号码 X、合法号码 B。
+  2. 提交发送。
+  3. 查看预审结果和任务明细。
+- 预期结果：
+  - 重复号码被识别，重复率写入风控指标。
+  - 非法号码被识别，非法率写入风控指标。
+  - 如命中拒绝阈值，任务被 rejected，返回可读拒绝原因。
+  - 如未命中拒绝阈值，仅合法且去重后的号码进入后续发送。
+
+### TC-CLIENT-007 账户余额不足禁止发送
+
+- 优先级：P0
+- 前置条件：账户余额、套餐余量和授信额度不足。
+- 步骤：
+  1. 使用长内容和多个手机号生成较高预估费用。
+  2. 提交发送。
+  3. 查看账单流水。
+- 预期结果：
+  - 发送前账户校验失败。
+  - 不创建可发送状态的批量任务，或任务进入 rejected。
+  - 不生成冻结/扣费流水。
+  - 客户端展示余额不足原因。
+
+### TC-CLIENT-008 客户端账单流水查询
+
+- 优先级：P1
+- 前置条件：存在充值、冻结、扣费、退款、释放流水。
+- 步骤：
+  1. 打开账单流水。
+  2. 按时间、交易类型、任务编号查询。
+  3. 查看单条流水关联对象。
+- 预期结果：
+  - 流水类型和金额方向正确。
+  - 任务、短信记录或充值订单可追溯。
+  - 客户端只展示本租户流水。
+
+### TC-CLIENT-009 客户端上行短信查询
+
+- 优先级：P1
+- 前置条件：已通过 Gateway 模拟器写入上行事件。
+- 步骤：
+  1. 打开上行短信页面。
+  2. 按手机号和时间查询。
+  3. 查看上行关联下发记录。
+- 预期结果：
+  - 展示上行内容、接入号、接收时间。
+  - 可展示匹配到的下发 messageId。
+  - 未匹配上行仍可查询，状态或关联为空。
+
+## 4. 运营端功能用例
+
+### TC-ADMIN-001 签名审核通过
+
+- 优先级：P0
+- 前置条件：客户端已提交待审核签名。
+- 步骤：
+  1. 运营审核员打开签名审核列表。
+  2. 查看签名材料和引流信息。
+  3. 点击通过。
+- 预期结果：
+  - 签名状态变为 approved。
+  - 写入审核记录，包含审核人、动作、时间。
+  - 客户端签名列表同步展示通过状态。
+
+### TC-ADMIN-002 模板审核驳回
+
+- 优先级：P0
+- 前置条件：客户端已提交待审核模板。
+- 步骤：
+  1. 运营审核员打开模板审核详情。
+  2. 填写驳回原因。
+  3. 点击驳回。
+- 预期结果：
+  - 模板状态变为 rejected。
+  - 驳回原因保存并返回客户端。
+  - 被驳回模板不能用于发送。
+
+### TC-ADMIN-003 通道创建与启停
+
+- 优先级：P0
+- 前置条件：运营管理员已登录。
+- 步骤：
+  1. 创建 CMPP 通道，填写网关地址、端口、账号、密码密文、接入号、限速。
+  2. 查询通道列表。
+  3. 停用通道后创建发送任务。
+- 预期结果：
+  - 通道协议默认为 CMPP，版本默认为 3.0。
+  - 通道限速保存正确。
+  - 停用通道不会被路由选中。
+
+### TC-ADMIN-004 通道组与路由规则
+
+- 优先级：P0
+- 前置条件：存在主通道和备用通道。
+- 步骤：
+  1. 创建通道组。
+  2. 添加主通道优先级 10、备用通道优先级 20。
+  3. 创建租户/应用维度路由规则。
+  4. 创建发送任务触发送链路。
+- 预期结果：
+  - 路由优先命中租户/应用规则。
+  - 主通道 active 时选择主通道。
+  - 主通道 disabled 时选择备用 active 通道。
+
+### TC-ADMIN-005 签名报备任务生成与导出
+
+- 优先级：P0
+- 前置条件：签名审核通过，通道配置了报备字段。
+- 步骤：
+  1. 为签名登记通道报备材料。
+  2. 生成报备任务。
+  3. 执行报备资料导出。
+  4. 查看报备记录。
+- 预期结果：
+  - 生成 pending 报备任务。
+  - 导出后任务状态变为 exporting。
+  - 生成导出文件记录。
+  - 报备记录包含 create/export 两个动作。
+
+### TC-ADMIN-006 报备回执导入通过
+
+- 优先级：P0
+- 前置条件：存在 exporting 报备任务。
+- 步骤：
+  1. 导入全部成功的通道回执。
+  2. 查看报备任务和签名状态。
+- 预期结果：
+  - 导入批次记录 rowCount、successCount、failedCount。
+  - 报备任务状态变为 approved。
+  - 签名 `reportStatus` 同步为 approved。
+  - 报备记录包含 receipt_import。
+
+### TC-ADMIN-007 报备回执导入失败
+
+- 优先级：P1
+- 前置条件：存在 exporting 报备任务。
+- 步骤：
+  1. 导入存在失败行的通道回执。
+  2. 填写失败原因。
+  3. 查看签名报备状态。
+- 预期结果：
+  - 报备任务状态变为 rejected 或 partial_approved。
+  - 失败原因可查询。
+  - 签名报备状态同步为对应失败状态。
+
+### TC-ADMIN-008 风控规则配置覆盖默认规则
+
+- 优先级：P0
+- 前置条件：存在平台默认风控规则。
+- 步骤：
+  1. 为 `tenant-a` 创建同 code 的租户级规则，阈值低于平台默认值。
+  2. 提交达到租户阈值但未达到平台阈值的任务。
+  3. 查看风控命中记录。
+- 预期结果：
+  - 生效规则使用租户级配置。
+  - 风控命中记录写入租户规则 id、规则编号、阈值、实际值、处理动作。
+  - 运营端审核页面展示命中原因。
+
+### TC-ADMIN-009 短信审核通过后入队
+
+- 优先级：P0
+- 前置条件：发送任务因风控进入 pending_review。
+- 步骤：
+  1. 运营审核员打开短信审核详情。
+  2. 查看号码量、内容、计费条数、命中规则。
+  3. 点击通过。
+  4. 查看发送队列和任务状态。
+- 预期结果：
+  - 审核状态变为 approved。
+  - 任务进入 queued/sending。
+  - 生成发送队列消息。
+  - 审核动作写入日志。
+
+### TC-ADMIN-010 短信审核驳回
+
+- 优先级：P0
+- 前置条件：发送任务因风控进入 pending_review。
+- 步骤：
+  1. 运营审核员填写驳回原因。
+  2. 点击驳回。
+  3. 客户端查看任务状态。
+- 预期结果：
+  - 任务状态变为 rejected。
+  - 不再进入发送队列。
+  - 客户端可见驳回原因。
+
+### TC-ADMIN-011 运营看板与监控
+
+- 优先级：P1
+- 前置条件：存在 delivered、failed、unknown、timeout 多种短信记录。
+- 步骤：
+  1. 打开运营看板。
+  2. 打开发送监控。
+  3. 按租户和通道过滤。
+- 预期结果：
+  - 看板展示任务数、发送状态分布、上行数、账务聚合。
+  - 监控展示最近发送、最近回执、最近上行。
+  - 过滤条件生效。
+
+### TC-ADMIN-012 发送链路 Trace
+
+- 优先级：P0
+- 前置条件：存在一条完成 submit result、receipt、billing、uplink 的短信。
+- 步骤：
+  1. 在运营端按 messageId 查询 trace。
+  2. 查看批量任务、API 请求、提交记录、回执记录、计费记录、上行记录。
+- 预期结果：
+  - trace 返回完整链路。
+  - submitId、sequenceId、gatewayMessageId 可追踪。
+  - 计费记录和短信记录金额一致。
+
+### TC-ADMIN-013 对账 reconciliation
+
+- 优先级：P0
+- 前置条件：存在同一 taskId 下的短信记录、短信计费记录和账户流水。
+- 步骤：
+  1. 按租户和 taskId 查询对账。
+  2. 对比短信记录金额、计费记录金额、账户流水金额。
+- 预期结果：
+  - 无异常时 diff 为 0。
+  - 若人为构造缺失流水，diff 展示差额。
+  - 查询结果支持定位 taskId/messageId。
+
+## 5. 风控规则专项用例
+
+### TC-RISK-001 单任务最大号码数直接拒绝
+
+- 优先级：P0
+- 前置条件：应用最大号码数阈值为 100。
+- 步骤：提交 101 个合法号码。
+- 预期结果：
+  - 命中 `MAX_PHONES_PER_TASK`。
+  - 任务 rejected。
+  - 风控命中记录包含阈值 100、实际值 101、动作 reject/block。
+
+### TC-RISK-002 重复号码比例进入人工审核
+
+- 优先级：P0
+- 前置条件：重复率阈值为 30%，动作为人工审核。
+- 步骤：提交 10 个号码，其中 4 个为重复号码。
+- 预期结果：
+  - duplicateRatio 为 0.4。
+  - 命中重复号码规则。
+  - 任务 pending_review。
+
+### TC-RISK-003 非法号码比例直接拒绝
+
+- 优先级：P0
+- 前置条件：非法率阈值为 10%，动作为拒绝。
+- 步骤：提交 10 个号码，其中 2 个非法。
+- 预期结果：
+  - illegalRatio 为 0.2。
+  - 任务 rejected。
+  - 客户端展示非法号码比例过高。
+
+### TC-RISK-004 黑名单命中比例人工审核
+
+- 优先级：P0
+- 前置条件：黑名单率阈值为 5%，动作为人工审核。
+- 步骤：提交 20 个号码，其中 2 个在企业或全局黑名单。
+- 预期结果：
+  - blacklistHitRatio 为 0.1。
+  - 任务 pending_review。
+  - 命中记录写入黑名单规则。
+
+### TC-RISK-005 模板变量缺失直接拒绝
+
+- 优先级：P0
+- 前置条件：模板要求变量 `code`。
+- 步骤：提交发送时不传 `code`，或额外传入未定义变量。
+- 预期结果：
+  - 命中 `TEMPLATE_VARIABLE_ANOMALY`。
+  - 任务 rejected。
+  - variableIssues 记录缺失或多传变量。
+
+### TC-RISK-006 非工作时间营销大批量人工审核
+
+- 优先级：P1
+- 前置条件：非工作时间大批量阈值为 5000。
+- 步骤：在 21:00 后提交营销类短信 5001 个号码。
+- 预期结果：
+  - 命中非工作时间营销大批量规则。
+  - 任务 pending_review。
+  - 审核原因可见。
+
+### TC-RISK-007 短时间任务创建频控
+
+- 优先级：P1
+- 前置条件：10 分钟最多创建 10 次任务。
+- 步骤：同租户同应用 10 分钟内创建第 11 个任务。
+- 预期结果：
+  - 命中频控规则。
+  - 按规则动作进入人工审核或拒绝。
+  - 命中记录包含 recentTaskCount。
+
+## 6. 计费专项用例
+
+### TC-BILLING-001 70/67 计费条数
+
+- 优先级：P0
+- 步骤：
+  1. 使用 70 字内容提交 1 个号码。
+  2. 使用 71 字内容提交 1 个号码。
+  3. 使用 134 字内容提交 1 个号码。
+- 预期结果：
+  - 70 字为 1 条。
+  - 71 字为 2 条。
+  - 134 字为 2 条。
+  - 金额等于计费条数乘单价。
+
+### TC-BILLING-002 发送前冻结
+
+- 优先级：P0
+- 前置条件：账户余额充足，计费口径需要发送前冻结。
+- 步骤：创建发送任务并进入待发送。
+- 预期结果：
+  - 生成 frozen 流水。
+  - 账户余额或套餐余量减少。
+  - 流水关联 taskId。
+
+### TC-BILLING-003 submit 成功扣费
+
+- 优先级：P0
+- 前置条件：计费口径为 submit_success。
+- 步骤：模拟 Gateway 返回 submit accepted。
+- 预期结果：
+  - 生成 charged 流水。
+  - 短信计费记录状态更新为 charged。
+  - 可按 messageId 对账。
+
+### TC-BILLING-004 最终失败退款
+
+- 优先级：P0
+- 前置条件：短信已扣费。
+- 步骤：模拟 receipt undelivered。
+- 预期结果：
+  - 短信状态 failed/undelivered。
+  - 生成 refunded 流水。
+  - 退款金额与原扣费一致。
+
+### TC-BILLING-005 72 小时超时退款
+
+- 优先级：P0
+- 前置条件：短信状态 unknown 且超过 72 小时。
+- 步骤：执行未知转超时补偿任务。
+- 预期结果：
+  - 短信状态 timeout。
+  - 生成退款或释放流水。
+  - 后续二次成功回执不自动覆盖 timeout 状态。
+
+## 7. 发送链路专项用例
+
+### TC-SEND-001 批量任务创建和手机号拆分
+
+- 优先级：P0
+- 步骤：提交包含多个手机号的客户端批量任务。
+- 预期结果：
+  - 生成 1 条 `SmsBatchTask`。
+  - 每个有效手机号生成 1 条 `SmsMessageRecord`。
+  - `SmsBatchTask.progressTotal` 等于有效手机号数量。
+
+### TC-SEND-002 发送任务入队
+
+- 优先级：P0
+- 前置条件：任务审核通过。
+- 步骤：触发送 worker 入队。
+- 预期结果：
+  - 每条 queued 短信生成一个发送 job。
+  - jobId 使用 messageRecordId，避免重复入队。
+  - 批量任务状态变为 queued。
+
+### TC-SEND-003 通道路由和 Gateway SubmitCommand
+
+- 优先级：P0
+- 前置条件：存在 active 通道和路由规则。
+- 步骤：处理一条发送 job。
+- 预期结果：
+  - 选择正确通道。
+  - 创建 SmsSubmitRecord。
+  - 投递 Gateway SubmitCommand，包含 traceId、messageId、channelId、submitId、phoneNumber、content、cmpp 参数。
+
+### TC-SEND-004 SubmitResult accepted
+
+- 优先级：P0
+- 步骤：模拟 Gateway 返回 accepted。
+- 预期结果：
+  - SmsSubmitRecord 写入 sequenceId、gatewayMessageId、accepted 状态。
+  - SmsMessageRecord 状态变为 submitted。
+  - 批量任务进度刷新。
+
+### TC-SEND-005 SubmitResult rejected
+
+- 优先级：P0
+- 步骤：模拟 Gateway 返回 rejected 和错误码。
+- 预期结果：
+  - SmsMessageRecord 状态变为 submit_failed。
+  - 记录 errorCode/errorMessage。
+  - 失败数统计增加。
+
+### TC-SEND-006 Receipt delivered
+
+- 优先级：P0
+- 步骤：模拟 deliver 回执 `DELIVRD`。
+- 预期结果：
+  - 创建 SmsReceiptRecord。
+  - SmsMessageRecord 状态变为 delivered。
+  - 成功数统计增加。
+
+### TC-SEND-007 Receipt unknown 后超时
+
+- 优先级：P0
+- 步骤：
+  1. 模拟 unknown 回执。
+  2. 将 deliveredAt 调整为 72 小时前。
+  3. 执行超时补偿。
+- 预期结果：
+  - unknown 记录转为 timeout。
+  - timeoutTotal 增加。
+  - 错误信息说明 72 小时未收到明确回执。
+
+### TC-SEND-008 上行短信匹配
+
+- 优先级：P1
+- 步骤：模拟带 messageId 的上行事件。
+- 预期结果：
+  - 创建 SmsUplinkMessage。
+  - tenantId 可通过 messageId 关联。
+  - 客户端和运营端均可查询。
+
+### TC-SEND-009 未匹配上行短信入库
+
+- 优先级：P1
+- 步骤：模拟不带 messageId 或匹配不到下发记录的上行事件。
+- 预期结果：
+  - 上行短信仍入库。
+  - tenantId 可为空。
+  - 运营端可查询并人工判断。
+
+## 8. Gateway 专项用例
+
+### TC-GW-001 SEQID/MSGID 追踪
+
+- 优先级：P0
+- 步骤：
+  1. Gateway 接收 SubmitCommand。
+  2. 分配 sequenceId。
+  3. 模拟 submit resp 返回 gatewayMessageId。
+  4. 按 gatewayMessageId 查询映射。
+- 预期结果：
+  - messageId、sequenceId、gatewayMessageId 三者可互查。
+  - 并发提交时映射不串。
+
+### TC-GW-002 重连后继续消费
+
+- 优先级：P0
+- 步骤：
+  1. 模拟 SMSC 连接失败。
+  2. Gateway 执行重连。
+  3. 重连成功后继续处理新 SubmitCommand。
+- 预期结果：
+  - 重连次数可观测。
+  - 未成功连接时不丢失任务。
+  - 连接恢复后继续消费。
+
+### TC-GW-003 Health 检查
+
+- 优先级：P0
+- 步骤：访问 Gateway `/health`。
+- 预期结果：
+  - 返回 HTTP 200。
+  - payload 包含 `status=ok` 和服务名。
+
+### TC-GW-004 gocmpp submit/resp 模拟器
+
+- 优先级：P0
+- 步骤：
+  1. 启动或调用模拟 SMSC。
+  2. Gateway 发起 submit。
+  3. 模拟器返回 submit resp 和 deliver。
+- 预期结果：
+  - submit resp 可解析。
+  - deliver 回执可转为队列事件。
+  - 不依赖真实运营商。
+
+### TC-GW-005 重复回执
+
+- 优先级：P1
+- 步骤：同一 gatewayMessageId 连续发送两次 delivered 回执。
+- 预期结果：
+  - 第一条更新最终状态。
+  - 第二条记录历史或被幂等处理。
+  - 不重复扣费或重复变更最终状态。
+
+## 9. 契约与队列用例
+
+### TC-CONTRACT-001 SubmitCommand Schema 校验
+
+- 优先级：P0
+- 步骤：运行 `npm run spike:contracts`。
+- 预期结果：`submit-command.json` 通过 schema 校验。
+
+### TC-CONTRACT-002 SubmitResult Schema 校验
+
+- 优先级：P0
+- 步骤：运行 `npm run spike:contracts`。
+- 预期结果：`submit-result.json` 通过 schema 校验。
+
+### TC-CONTRACT-003 ReceiptEvent Schema 校验
+
+- 优先级：P0
+- 步骤：运行 `npm run spike:contracts`。
+- 预期结果：`receipt-event.json` 通过 schema 校验。
+
+### TC-CONTRACT-004 UplinkEvent Schema 校验
+
+- 优先级：P0
+- 步骤：运行 `npm run spike:contracts`。
+- 预期结果：`uplink-event.json` 通过 schema 校验。
+
+## 10. 端到端 Smoke 用例
+
+### TC-E2E-001 核心发送闭环
+
+- 优先级：P0
+- 前置条件：使用测试替身或本地 PostgreSQL/Redis 环境。
+- 步骤：
+  1. 创建租户、应用、签名、模板、通道、路由。
+  2. 审核签名和模板通过。
+  3. 创建发送任务。
+  4. 发送入队。
+  5. 模拟 Gateway submit accepted。
+  6. 模拟 receipt delivered。
+  7. 查询 trace 和 reconciliation。
+- 预期结果：
+  - 任务从 created/ready 流转到 finished。
+  - 单条短信状态为 delivered。
+  - trace 链路完整。
+  - 对账差异为 0。
+
+### TC-E2E-002 风控人工审核闭环
+
+- 优先级：P0
+- 步骤：
+  1. 提交命中人工审核规则的发送任务。
+  2. 运营端查看审核原因。
+  3. 审核通过。
+  4. 发送入队并完成回执。
+- 预期结果：
+  - 审核前不入队。
+  - 审核原因包含命中规则。
+  - 审核通过后进入发送链路。
+
+### TC-E2E-003 失败退款闭环
+
+- 优先级：P0
+- 步骤：
+  1. 创建余额充足的发送任务。
+  2. 发送前冻结或 submit 成功扣费。
+  3. 模拟最终失败回执。
+  4. 查询账单流水和对账。
+- 预期结果：
+  - 失败短信触发退款。
+  - 账务流水可追溯。
+  - 对账 diff 为 0。
+
+## 11. 前端 Smoke 用例
+
+### TC-WEB-001 客户端主页面加载
+
+- 优先级：P1
+- 步骤：打开客户端工作台、短信发送、批量任务、发送详情、上行短信、账单流水。
+- 预期结果：
+  - 页面无白屏。
+  - 关键表格、筛选项、按钮可见。
+  - 控制台无阻断错误。
+
+### TC-WEB-002 运营端主页面加载
+
+- 优先级：P1
+- 步骤：打开运营看板、发送监控、短信审核、通道管理、报备任务、短信记录、账单流水。
+- 预期结果：
+  - 页面无白屏。
+  - 表格和操作按钮可见。
+  - 彩信相关页面仍保持第一版边界，不进入短信主链路。
+
+### TC-WEB-003 响应式 Smoke
+
+- 优先级：P2
+- 步骤：在桌面宽屏和移动宽度打开核心页面。
+- 预期结果：
+  - 文本不重叠。
+  - 表格或卡片可滚动/适配。
+  - 主要操作按钮不被遮挡。
+
+## 12. 性能 Smoke 用例
+
+### TC-PERF-001 BullMQ 500 TPS Smoke
+
+- 优先级：P0
+- 步骤：运行 `npm run spike:bullmq`。
+- 预期结果：
+  - 15000 条消息处理完成。
+  - endToEndTps 不低于 500。
+  - submitResults 和 receiptEvents 均等于 15000。
+
+### TC-PERF-002 队列积压恢复
+
+- 优先级：P1
+- 步骤：
+  1. 连续提交 15000 条消息。
+  2. 观察处理完成时间和队列积压。
+- 预期结果：
+  - 压测停止后队列可恢复到无积压。
+  - 无重复最终状态。
+  - 错误率满足阶段 0/8 性能报告要求。
+
+## 13. 回归执行建议
+
+每次阶段回归至少执行：
+
+```bash
+npm run spike:contracts
+npm run test:api
+npm run test:gateway
+npm run verify:phase8
+```
+
+若测试环境具备 PostgreSQL、Redis、MinIO，再补充执行 E2E smoke 和真实 API HTTP 测试。

docs/testing-plan.md

@@ -4,6 +4,8 @@
 
 第一版测试优先保证短信业务主链路可回归：风控、计费、发送编排、通道路由与报备、查询统计、Gateway 追踪和模拟链路。不依赖真实运营商 CMPP 网关；本地没有 PostgreSQL、Redis、MinIO 时，优先使用 mock、测试替身或 spike 模拟器。
 
+系统功能测试用例详见 `docs/system-functional-test-cases.md`。该文档面向第一版验收、人工测试和后续 E2E 自动化改造，覆盖客户端、运营端、API、Gateway 和性能 smoke 场景。
+
 ## 2. 测试分层
 
 ### 2.1 单元测试