wip: baseline changes before channel-conversation-task boundary implementation

2026-07-08 16:23:09 +08:00
parent 89c9e6a066
commit 1298a558e8
139 changed files with 11781 additions and 666 deletions
--- a/docs/testing/2026-07-07-test-plan.md
+++ b/docs/testing/2026-07-07-test-plan.md
@@ -0,0 +1,326 @@
+# sino-mci 测试补齐计划
+
+> **日期**：2026-07-07  
+> **范围**：backend（mci-server）单元/集成测试、API 冒烟测试、前端手工测试、Chrome DevTools 测试场景、Docker 部署验证  
+> **执行标准命令**：见第 7 节
+
+---
+
+## 1. 单元测试（已存在）
+
+| 测试类 | 路径 | 覆盖内容 |
+|--------|------|---------|
+| `PolicyEngineTest` | `send/service/PolicyEngineTest.java` | 频率限制（rate_limit）、时间窗（time_window）、黑名单（blacklist）及组合策略的允许/拒绝判定 |
+| `SendServiceFailoverTest` | `send/service/SendServiceFailoverTest.java` | 发送记录主备账号切换、全部账号不可用、无健康账号三种场景下的 `SendService.dispatchRecord` |
+| `AccountSelectorTest` | `channel/service/AccountSelectorTest.java` | 会话发送账号选择：主号健康、主号不健康切备用、`backup` 策略优先、无健康账号返回 null |
+| `FlowEngineTest` | `inbound/engine/FlowEngineTest.java` | 入站流程引擎：条件分支命中 webhook、未命中执行 reply、无发布流程时标记已处理 |
+| `IntentRecognitionServiceTest` | `inbound/intent/IntentRecognitionServiceTest.java` | 规则 + 槽位抽取的意图识别，无规则/无 LLM 时返回 `unknown` |
+| `InboundContextServiceTest` | `inbound/service/InboundContextServiceTest.java` | 根据会话/联系人解析业务上下文，合并时优先保留会话维度字段 |
+| `WebhookPayloadBuilderTest` | `inbound/webhook/WebhookPayloadBuilderTest.java` | 入站 webhook payload 结构、方向映射、`null` 意图/空白 JSON 处理 |
+| `WebhookSignatureServiceTest` | `inbound/webhook/WebhookSignatureServiceTest.java` | HMAC-SHA256/512 签名、默认算法、不同 secret/算法签名差异 |
+| `AccountControllerTest` | `admin/controller/AccountControllerTest.java` | 租户创建接口 |
+| `ChannelControllerTest` | `channel/controller/ChannelControllerTest.java` | 渠道主体与渠道账号创建、企微回调 echo 校验 |
+| `ChannelAccountHeartbeatTest` | `channel/ChannelAccountHeartbeatTest.java` | 心跳更新账号在线/风险状态、超时离线检测 |
+| `WeComSessionArchiveTest` | `channel/controller/WeComSessionArchiveTest.java` | 企微 `msgaudit_notify` 回调、会话存档拉取并保存消息事件/媒体记录 |
+| `WeComSyncTest` | `channel/controller/WeComSyncTest.java` | 企微通讯录同步（人员+渠道身份）、群聊同步（会话+参与者+账号绑定） |
+| `CrmControllerTest` | `crm/controller/CrmControllerTest.java` | 联系人、标签、会话的创建与列表查询 |
+| `IvrFlowControllerTest` | `flow/controller/IvrFlowControllerTest.java` | IVR 流程的增删改查、发布、下线生命周期 |
+| `InboundFlowControllerTest` | `inbound/controller/InboundFlowControllerTest.java` | 入站流程创建/发布、接收消息事件 |
+| `SendControllerTest` | `send/controller/SendControllerTest.java` | 发送接口：单聊发送、规则目标 `and/or` 逻辑、发送记录查询 |
+| `SendPreviewControllerTest` | `send/controller/SendPreviewControllerTest.java` | 发送预览：会话/规则目标、渠道拆分、账号用量、黑名单命中但不做限流计数 |
+| `SendMessageConsumerTest` | `send/mq/SendMessageConsumerTest.java` | MQ 异步消费：成功回调、失败重试、超过最大重试后的失败回调 |
+| `TenantWebhookControllerTest` | `admin/controller/TenantWebhookControllerTest.java` | 租户 webhook 配置查询/更新、测试推送成功/失败 |
+
+---
+
+## 2. 集成测试（补齐）
+
+### 2.1 现有集成测试缺口
+
+- 现有 controller 级测试大多聚焦单接口或局部链路，缺少**从租户创建到发送记录生成**的完整出站链路。
+- 缺少**从消息事件接收到 webhook 推送**的完整入站链路验证。
+
+### 2.2 新增集成测试
+
+#### `SendEndToEndTest.java`
+
+- **路径**：`backend/mci-server/src/test/java/com/sino/mci/send/service/SendEndToEndTest.java`
+- **技术**：`@SpringBootTest` + `@AutoConfigureMockMvc` + `@Transactional`，直接复用真实数据库（Docker 中 MySQL）。
+- **覆盖步骤**：
+  1. 创建租户并登录，获取 `authToken`；
+  2. 创建渠道主体（wecom）；
+  3. 创建渠道账号并关联主体；
+  4. 创建会话并关联主体；
+  5. 绑定账号为会话发送主号；
+  6. 调用 `/api/v1/send/test` 模拟发送；
+  7. 查询 `/api/v1/send/{taskId}/records`，校验记录数、状态、渠道类型、会话/账号 ID、内容。
+
+#### `InboundEndToEndTest.java`
+
+- **路径**：`backend/mci-server/src/test/java/com/sino/mci/inbound/engine/InboundEndToEndTest.java`
+- **技术**：`@SpringBootTest` + `@AutoConfigureMockMvc` + `@Transactional`，通过 `@TestConfiguration` 将 `RestTemplate` bean 替换为 mock。
+- **覆盖步骤**：
+  1. 创建租户并登录；
+  2. 配置租户入站 webhook URL 与签名密钥；
+  3. 创建并发布入站流程：`receive -> intent -> webhook`；
+  4. 调用 `/api/v1/inbound/receive` 发送消息事件；
+  5. 校验返回事件 `isProcessed=1`；
+  6. 验证 `RestTemplate.exchange` 被调用，且目标 URL 为租户配置的 webhook URL。
+
+---
+
+## 3. API 冒烟测试
+
+> 基础地址：`http://localhost:8080/msg-platform`  
+> 所有业务接口需携带 `X-Tenant-Code` 与 `Authorization: Bearer <token>`。
+
+### 3.1 健康检查
+
+```bash
+curl -fsS http://localhost:8080/msg-platform/api/v1/health
+```
+
+### 3.2 创建租户
+
+```bash
+curl -X POST http://localhost:8080/msg-platform/api/v1/account/tenant \
+  -H 'Content-Type: application/json' \
+  -d '{"tenantCode":"rescue","tenantName":"救援业务"}'
+```
+
+### 3.3 登录（获取 token）
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:8080/msg-platform/api/v1/account/login \
+  -H 'X-Tenant-Code: rescue' \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"admin","password":"admin123"}' | jq -r '.data.token')
+echo "Bearer $TOKEN"
+```
+
+### 3.4 渠道主体 CRUD
+
+```bash
+curl -X POST http://localhost:8080/msg-platform/api/v1/channel-subject \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"channelType":"wecom","subjectCode":"sino","subjectName":"Sino"}'
+
+curl -s http://localhost:8080/msg-platform/api/v1/channel-subject/list \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### 3.5 渠道账号创建
+
+```bash
+curl -X POST http://localhost:8080/msg-platform/api/v1/channel-account \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"accountType":1,"channelType":"wecom","accountId":"ZhangSan","accountName":"张三"}'
+```
+
+### 3.6 会话创建与账号绑定
+
+```bash
+CONV_ID=$(curl -s -X POST http://localhost:8080/msg-platform/api/v1/conversation \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"conversationType":2,"channelType":"wecom","channelConversationId":"room-001","conversationName":"测试群"}' | jq -r '.data.id')
+
+curl -X POST "http://localhost:8080/msg-platform/api/v1/conversation/$CONV_ID/bind-account" \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"accountId":1,"bindingType":1,"sortOrder":1}'
+```
+
+### 3.7 发送消息（模拟发送）
+
+```bash
+TASK_ID=$(curl -s -X POST http://localhost:8080/msg-platform/api/v1/send/test \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d "{\"targetType\":\"conversation\",\"targetValue\":{\"conversation_id\":$CONV_ID},\"contentType\":\"text\",\"content\":{\"text\":\"hello\"},\"channelStrategy\":{\"channel_type\":\"wecom\",\"strategy\":\"primary\"}}" | jq -r '.data.taskId')
+
+curl -s "http://localhost:8080/msg-platform/api/v1/send/$TASK_ID/records" \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### 3.8 入站消息接收
+
+```bash
+curl -X POST http://localhost:8080/msg-platform/api/v1/inbound/receive \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"eventId":"evt-001","channelType":"wecom","eventType":"message","messageSource":"realtime","conversationId":1,"personId":1,"content":{"type":"text","body":"我要救援"}}'
+```
+
+### 3.9 入站流程管理
+
+```bash
+curl -X POST http://localhost:8080/msg-platform/api/v1/inbound/flow \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"flowCode":"inbound_default","flowName":"默认入站流程","flowType":"inbound","definitionJson":{"nodes":[{"id":"n1","type":"receive"},{"id":"n2","type":"intent"},{"id":"n3","type":"webhook"}],"edges":[{"source":"n1","target":"n2"},{"source":"n2","target":"n3"}]}}'
+
+curl -X POST http://localhost:8080/msg-platform/api/v1/inbound/flow/inbound_default/publish \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### 3.10 租户 webhook 配置
+
+```bash
+curl -X POST http://localhost:8080/msg-platform/api/v1/account/tenant/webhook \
+  -H 'X-Tenant-Code: rescue' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"inbound_webhook_url":"https://example.com/webhook","auth_config":{"sign_algorithm":"hmac-sha256","webhook_secret":"secret-123"}}'
+```
+
+---
+
+## 4. 前端手工测试
+
+前端地址：`http://localhost`
+
+| 页面 | 路由 | 测试步骤 | 预期结果 |
+|------|------|---------|---------|
+| 登录 | `/login` | 输入租户编码、用户名 `admin`、密码 `admin123` 登录 | 跳转 `/dashboard`，本地存储 token |
+| 渠道主体 | `/channel-subject` | 新增 wecom 主体 → 保存 → 刷新列表 → 编辑主体名称 | 列表展示新增/更新后的主体，无报错 |
+| 渠道账号 | `/channel-account` | 选择主体 → 新增企微内部账号 → 保存 → 触发同步通讯录/群聊 | 账号列表更新，同步返回成功提示 |
+| 会话/群聊 | `/conversation` | 新增群聊 → 绑定发送/接收账号 → 绑定标签 | 会话详情正确显示绑定关系 |
+| 发送策略 | `/send-policy` | 新建策略组 → 添加限流/时间窗/黑名单规则 → 保存 | 策略列表展示，规则 JSON 可预览 |
+| 入站 Webhook | `/inbound-webhook` | 配置 URL 与签名密钥 → 点击测试推送 | 页面提示推送结果（200/失败原因） |
+| 入站流程编排 | `/inbound-flow` | 拖拽 receive / intent / condition / webhook 节点 → 连线 → 保存并发布 | 流程定义持久化，发布状态变为已发布 |
+| 发送记录 | `/send-record` | 发送消息后进入页面 → 按任务 ID/时间/状态筛选 | 列表展示发送记录及状态 |
+| IVR 流程 | `/ivr-flow` | 新建 IVR 流程 → 配置 start / menu 节点 → 保存/发布/下线 | 生命周期状态正常切换 |
+| 消息测试 | `/message-test` | 选择会话 → 填写内容 → 点击发送 | 返回任务 ID，发送记录可查询 |
+
+---
+
+## 5. Chrome DevTools 测试场景
+
+### 5.1 通用检查项
+
+1. 打开 `DevTools → Console`，切换页面/提交表单，确认无未处理异常。
+2. 打开 `Network` 面板，过滤 `XHR/Fetch`，确认所有 API 请求：
+   - 携带 `X-Tenant-Code`；
+   - 携带 `Authorization: Bearer <token>`；
+   - 返回 `code: 0`（业务成功）。
+3. 检查请求/响应 Payload 与架构文档字段是否一致（snake_case / camelCase）。
+4. 模拟弱网：在 `Network` 面板选择 `Slow 3G`，观察加载状态与超时提示。
+5. 模拟后端 500：在 `Network` 面板对 `/api/v1/send/test` 请求右键 `Block request URL`，观察前端错误处理。
+
+### 5.2 页面级场景
+
+| 页面 | DevTools 操作 | 验证点 |
+|------|---------------|--------|
+| `/login` | 登录后查看 `Application → Local Storage` | `auth-store` 中保存 token、tenantCode、userInfo |
+| `/channel-subject` | 新增主体后查看 Network | POST `/api/v1/channel-subject` 返回 `code: 0`，列表 GET 包含新主体 |
+| `/channel-account` | 点击同步通讯录 | POST `/api/v1/channel-account/{id}/sync-contacts` 返回 `syncedCount` |
+| `/conversation` | 绑定账号 | POST `/api/v1/conversation/{id}/bind-account` 请求体字段正确 |
+| `/send-policy` | 保存策略 | POST `/api/v1/policy-group` 请求体 `policies` JSON 与表单一致 |
+| `/inbound-webhook` | 点击测试推送 | POST `/api/v1/account/tenant/webhook/test` 返回 `success` 与 `message` |
+| `/inbound-flow` | 保存/发布流程 | POST `/api/v1/inbound/flow` 与 `/publish` 顺序正确，payload 含 nodes/edges |
+| `/message-test` | 发送消息 | POST `/api/v1/send/test` 返回 `taskId`，随后 GET `/api/v1/send/{taskId}/records` 返回状态 2 |
+| `/send-record` | 筛选/分页 | GET `/api/v1/send/records` 含 page/size 参数，响应 `records` 非空 |
+| `/ivr-flow` | 发布/下线 | POST `/api/v1/flow/{code}/publish` 与 `/offline` 后状态码正确 |
+
+---
+
+## 6. Docker 部署测试
+
+### 6.1 启动基础设施
+
+```bash
+cd /Users/marsal/Projects/sino-project/sino-mci
+cp .env.example .env
+# 按需编辑 .env
+docker compose --profile infra up -d
+```
+
+等待所有 `infra` 服务 healthy：
+
+```bash
+docker compose --profile infra ps
+```
+
+### 6.2 启动应用服务
+
+```bash
+docker compose --profile app up -d
+```
+
+### 6.3 验证健康检查
+
+```bash
+# MySQL
+docker exec mci-mysql mysqladmin ping -h localhost -u root -proot
+
+# Redis
+docker exec mci-redis redis-cli ping
+
+# RabbitMQ
+docker exec mci-rabbitmq rabbitmq-diagnostics ping
+
+# mci-server
+curl -fsS http://localhost:8080/msg-platform/api/v1/health
+
+# channel-service
+curl -fsS http://localhost:8000/health
+
+# admin-web（通过首页判断）
+curl -fsS -o /dev/null -w '%{http_code}' http://localhost/
+```
+
+### 6.4 查看日志
+
+```bash
+docker compose --profile app logs -f mci-server
+docker compose --profile app logs -f channel-service
+```
+
+---
+
+## 7. 标准测试命令与结果
+
+### 7.1 命令
+
+```bash
+cd /Users/marsal/Projects/sino-project/sino-mci/backend
+docker run --rm --network sino-mci_mci-network --dns 8.8.8.8 \
+  -v "$HOME/.m2:/root/.m2" -v "$(pwd):/app" -w /app \
+  -e SPRING_DATASOURCE_URL='jdbc:mysql://mci-mysql:3306/sino_mci?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true' \
+  -e SPRING_DATASOURCE_USERNAME=root -e SPRING_DATASOURCE_PASSWORD=root \
+  -e SPRING_DATA_REDIS_HOST=mci-redis -e SPRING_RABBITMQ_HOST=mci-rabbitmq \
+  maven:3.9-eclipse-temurin-21-alpine \
+  mvn -B -pl mci-server -am test
+```
+
+### 7.2 运行结果
+
+- **总测试数**：59
+- **失败**：0
+- **错误**：0
+- **跳过**：0
+- **构建状态**：`BUILD SUCCESS`
+
+新增测试类 `SendEndToEndTest` 与 `InboundEndToEndTest` 均通过。
+
+---
+
+## 8. 后续可补充项
+
+- 引入 Testcontainers 或 H2 以支持无 Docker 环境的本地单元测试运行。
+- 为 `channel-service` 增加 Python 侧端到端测试。
+- 补充前端自动化测试（Playwright / Cypress）覆盖第 4、5 节手工场景。
+- 增加性能/稳定性测试：高并发发送、MQ 堆积恢复、会话存档大批量拉取。