# ZCLAW 全系统功能测试设计规格书

> **日期**: 2026-04-17
> **类型**: 全系统功能测试 (Full System Functional Test)
> **执行方式**: AI Agent 自动执行 (Chrome DevTools MCP + Tauri MCP + HTTP)
> **验证深度**: 深度验证 (结构完整性 + 数据合理性 + 状态一致性 + 错误合理性 + 跨系统流通)

---

## 1. 背景与目标

### 1.1 为什么需要这次测试

ZCLAW 已完成发布前稳定化阶段的核心功能开发，系统包含：
- 10 个 Rust Crates (~77K 行)
- 190 个 Tauri 命令 (104 个有前端 invoke 调用)
- 137 个 SaaS HTTP 端点 (.route())
- 14 层 Runtime 中间件 + 10 层 SaaS HTTP 中间件
- 9 个 Hands + 75 个 Skills + 17 个 Pipeline 模板

之前的 E2E 测试 (04-16, 22 条, 77% 通过率) 覆盖有限，且主要是冒烟级别验证。本测试方案旨在：
1. **全面覆盖** — 10 个子系统逐一验证，不留盲区
2. **深度断言** — 不仅验证"能运行"，还验证"数据真实、逻辑正确、状态一致"
3. **跨系统流通** — 验证数据在系统间的端到端流转，而非孤立功能点

### 1.2 先决条件

| 条件 | 状态 |
|------|------|
| PostgreSQL 运行 + SaaS 后端 (8080 端口) | 已就绪 |
| Tauri 桌面端 (1420 端口) | 已就绪 |
| Admin V2 开发服务器 (5173 端口) | 已就绪 |
| 至少一个 LLM Provider + 有余额的 API Key | 已就绪 |

### 1.3 不覆盖范围

| 排除项 | 原因 |
|--------|------|
| Model Groups 7 个端点 | 前端无调用方 |
| Account API Keys (/keys) | 与 /tokens 重叠，疑似孤儿 |
| A2A Multi-Agent 5 个命令 | feature-gated 禁用 |
| Webhook 系统 | 已 deprecated |
| 负载/压力测试 | 非功能测试范畴 |

---

## 2. 测试架构

### 2.1 三层结构

```
Layer 0: 基础设施健康 (5 条)
  └─ DB 连接、SaaS 健康、Admin 加载、Tauri 窗口、LLM 可达性

Layer 1: 子系统垂直测试 (10 组 × 7-15 条 = 100 条)
  ├─ V1:  认证与安全       (12 条)
  ├─ V2:  聊天流与流式响应   (10 条)
  ├─ V3:  管家模式与行业路由  (10 条)
  ├─ V4:  记忆管道           (8 条)
  ├─ V5:  Hands 自主能力     (10 条)
  ├─ V6:  SaaS Relay 与 Token 池 (10 条)
  ├─ V7:  Admin 后台全页面    (15 条)
  ├─ V8:  模型配置与计费       (10 条)
  ├─ V9:  Pipeline 与工作流   (8 条)
  └─ V10: 技能系统            (7 条)

Layer 2: 跨系统横向验证 (4 角色 × 6 条 = 24 条)
  ├─ R1: 医院行政 — 日常使用全链路
  ├─ R2: IT 管理员 — 后台配置全链路
  ├─ R3: 开发者 — API + 工作流全链路
  └─ R4: 普通用户 — 注册→首次体验→持续使用
```

### 2.2 断言标准（深度验证）

每条链路的断言覆盖以下维度：

| 维度 | 验证内容 |
|------|----------|
| **结构完整性** | 响应包含所有必填字段、字段类型正确 |
| **数据合理性** | token 用量 > 0、时间戳在合理范围、ID 格式正确 |
| **状态一致性** | 创建后能查询到、删除后不存在、更新后值已变更 |
| **错误合理性** | 错误响应包含明确 message、HTTP 状态码正确、不泄露内部信息 |
| **跨系统流通** | 聊天后记忆被提取、计费记录增加、审计日志有记录 |

---

## 3. Layer 0: 基础设施健康检查 (5 条)

| # | 链路 | 验证方式 | 预期 |
|---|------|----------|------|
| L0-01 | PostgreSQL 连接 | `SELECT 1` via SaaS health | 200 + `{"status": "ok"}` |
| L0-02 | SaaS 后端健康 | `GET /api/health` | 200 + 服务信息 |
| L0-03 | Admin V2 加载 | 浏览器导航到 `localhost:5173` | 页面标题含 "ZCLAW" + 无 JS 错误 |
| L0-04 | Tauri 桌面端运行 | Chrome DevTools 连接 `localhost:1420` | 页面可见 + 无白屏 |
| L0-05 | LLM Provider 可达 | `GET /api/v1/relay/models` | 返回至少 1 个可用模型 |

---

## 4. Layer 1: 子系统垂直测试

### V1: 认证与安全 (12 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V1-01 | 注册新用户 | 用户名/邮箱/密码校验规则生效；响应含 account_id(非空) + JWT(可解码) + refresh_token；GET /auth/me 返回 status=active + role=user + totp_enabled=false |
| V1-02 | 重复注册拒绝 | 相同用户名→409 + 明确 message；相同邮箱→409；用户名<3字符→400；密码<8字符→400 |
| V1-03 | 登录获取 Token | 响应含 access_token + refresh_token；JWT 解码后 sub=account_id, role 正确, pwv=1；HttpOnly cookie 设置正确 |
| V1-04 | 错误密码锁定 | 连续 5 次错误密码→账户锁定 15 分钟；第 6 次尝试→423 + "账户已锁定"；正确密码在锁定期内也不可登录 |
| V1-05 | Token 刷新轮换 | 用 refresh_token 换新 token 对；旧 refresh_token 立即失效(二次使用→401)；新 token 的 jti 不同 |
| V1-06 | 密码修改使旧 Token 失效 | 修改密码后 pwv 递增；旧 JWT 访问受保护端点→401；重新登录后正常 |
| V1-07 | 登出撤销 | 登出后 refresh_token 失效；access_token 仍在有效期但 refresh 不可用 |
| V1-08 | TOTP 设置与验证 | setup 返回 secret+QR；verify 成功后 totp_enabled=true；login 需额外 totp_code |
| V1-09 | API Token CRUD | 创建→返回明文 token(仅一次)；列表→hash 不含明文；用 token 调 API→成功；撤销→不可用 |
| V1-10 | 权限中间件 | user 角色访问 admin 端点→403；admin 角色→成功；无 token→401 |
| V1-11 | 限流验证 | 登录接口 >5次/分钟→429；注册 >3次/小时→429；公共接口 >20次/分钟→429 |
| V1-12 | 并发会话 | 同一账户多设备同时登录；各设备 token 独立有效；一处修改密码全部失效 |

### V2: 聊天流与流式响应 (10 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V2-01 | KernelClient 流式聊天 | 发消息→收到 text_delta 事件流；最终消息完整(非截断)；token 统计 input>0, output>0；消息持久化到 IndexedDB |
| V2-02 | SaaS Relay SSE 流式 | 走 Relay 路径→SSE 格式正确(data: [DONE])；Admin Usage 页可见新增 token 记录；GET /relay/tasks 返回对应任务记录 |
| V2-03 | 模型切换后聊天 | 切换到不同模型→发送消息→验证响应确实来自新模型；模型字段正确 |
| V2-04 | 流式取消 | 发消息→中途 cancelStream→收到已生成部分+取消标记；不产生完整 token 计费；session 状态恢复为 idle |
| V2-05 | 多轮对话上下文 | 连续 3 轮对话；第 3 轮能引用第 1 轮内容；上下文窗口不溢出 |
| V2-06 | 错误恢复 | 模拟 401→自动 token 刷新→重试成功；模拟网络断开→优雅降级+重连 |
| V2-07 | thinking_delta 处理 | 模型返回 thinking 内容→前端正确展示折叠/展开；thinking 不计入 output token 统计 |
| V2-08 | tool_call 事件流 | LLM 调用工具→收到 tool_call 事件→工具执行→tool_result 事件→最终回复包含工具结果 |
| V2-09 | Hand 触发事件流 | 触发 Hand→handStart 事件→handEnd 事件+结果；消息列表含 role=hand 消息 |
| V2-10 | 消息持久化验证 | 发送 5 条消息→刷新页面→消息恢复完整(含时间戳、角色、内容)；IDB 中数据结构正确 |

### V3: 管家模式与行业路由 (10 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V3-01 | 关键词分类命中 | 发送医疗相关查询→ButlerRouter 分类为 healthcare；响应 system prompt 包含 `<butler-context>` XML 块 |
| V3-02 | 行业关键词动态加载 | Admin 创建自定义行业+关键词→Tauri 加载→查询命中该行业关键词→分类正确 |
| V3-03 | 未命中默认行为 | 发送无关查询→无 `<butler-context>` 注入→正常对话流程不受影响 |
| V3-04 | 多关键词饱和度 | 连续命中 3+关键词→饱和度达到 1.0→分类置信度最高 |
| V3-05 | 痛点记录 | 用户表达痛点→butler_record_pain_point→痛点存入 SQLite→list 可查询 |
| V3-06 | 方案生成 | 累积足够痛点→butler_generate_solution→返回结构化方案(标题+描述+步骤) |
| V3-07 | 简洁/专业模式切换 | 切换到简洁模式→UI 隐藏高级选项→对话风格变化(管家更主动) |
| V3-08 | 跨会话连续性 | 新会话→管家引用上次痛点→通过 Tauri 命令 `butler_list_pain_points` 查询痛点数据并验证正确 |
| V3-09 | 冷启动体验 | 新用户首次聊天→管家自我介绍+引导→不出现空白或错误 |
| V3-10 | 4 内置行业覆盖 | 分别用医疗/数据报告/政策合规/会议协调关键词查询→4 个行业各至少命中一次 |

### V4: 记忆管道 (8 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V4-01 | 对话后记忆提取 | 3 轮对话含明确偏好→对话结束后触发 extraction→SQLite 中有新记忆记录 |
| V4-02 | FTS5 全文检索 | 存入 3 条记忆(A="我喜欢 Python 编程", B="我偏好 Rust 开发", C="今天天气很好")→搜索"编程语言"→viking_find 返回 [A, B]；A/B 排在 C 之前 |
| V4-03 | TF-IDF 语义评分 | 存入多条不同主题记忆→查询特定主题→viking_find 返回按 TF-IDF 相似度排序；语义最相关的排在首位 |
| V4-04 | 记忆注入系统提示 | 用户有偏好记忆→新对话→system prompt 中包含 `## 用户偏好` 段+记忆内容 |
| V4-05 | Token 预算约束 | 大量记忆→注入后不超过 500 token 预算；低分记忆被截断 |
| V4-06 | 记忆去重 | 重复表达相同偏好→不产生重复记录；或旧记录更新而非新增 |
| V4-07 | Agent 级记忆隔离 | Agent A 的记忆不出现在 Agent B 的上下文中；切换 Agent 后记忆正确加载 |
| V4-08 | 记忆统计 | memory_stats 返回正确的记忆总数/各类型计数/存储大小 |

### V5: Hands 自主能力 (10 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V5-01 | Browser Hand 执行 | 触发 browser_hand→创建浏览器实例→导航到 URL→返回页面内容；hand_run_status 正确流转 |
| V5-02 | Researcher Hand | 触发 researcher→返回研究报告结构(摘要+来源+建议)；执行时间合理 |
| V5-03 | Speech Hand + TTS | 触发 speech→文本生成→浏览器 TTS 播放(检查 speechSynthesis.speak 调用) |
| V5-04 | Quiz Hand | 触发 quiz→返回题目结构(题干+选项+答案)；格式可解析 |
| V5-05 | Slideshow Hand | 触发 slideshow→返回幻灯片数据(标题+内容+布局) |
| V5-06 | Hand 审批流程 | needs_approval 的 Hand→审批前状态=pending→approve 后执行→状态=completed |
| V5-07 | Hand 并发限制 | 同一 Hand 并发触发超过 semaphore 限制→排队等待；不崩溃 |
| V5-08 | Hand 依赖检查 | Clip Hand 无 FFmpeg→check_dependencies 返回缺失依赖→graceful 错误消息 |
| V5-09 | Hand 列表与注册 | hand_list 返回 9 个启用的 Hand；每个含 name+description+tool_count |
| V5-10 | Hand 审计日志 | Hand 执行后→Admin 日志审计页可见对应记录(action=hand_execute, target=hand_name) |

### V6: SaaS Relay 与 Token 池 (10 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V6-01 | Relay 聊天完成 | POST /relay/chat/completions→SSE 流返回；GET /relay/tasks 返回该任务且状态为 completed |
| V6-02 | Token 池轮换 | provider_keys 有多个 key→连续请求→RPM/TPM 跟踪正确→key 自动轮换 |
| V6-03 | Key 限流生效 | 单个 key 达到 RPM 限制→自动切换到下一个 key；所有 key 耗尽→返回 429 |
| V6-04 | Relay 任务列表 | 完成多次 relay→list_tasks 返回历史；分页正确；状态字段准确 |
| V6-05 | Relay 失败重试 | 使用 intentionally invalid API key 创建 provider→通过 relay 发送聊天→期望失败→使用有效 key 调用 retry 端点→验证成功 |
| V6-06 | 可用模型列表 | list_available_models 返回当前 key 池支持的模型；不含已禁用模型 |
| V6-07 | 配额检查 | 用户配额已满→relay 请求→被 quota middleware 拦截→返回 429 + quota exceeded |
| V6-08 | Key 创建/切换/删除 | Admin CRUD provider_key→创建后可见→toggle 禁用→删除后不可用 |
| V6-09 | Usage 记录完整性 | relay 请求→GET /usage 返回新增记录→account_id, model, input_tokens, output_tokens 全部正确 |
| V6-10 | Relay 超时处理 | 长时间请求→15s 超时→返回 timeout 错误(非 hang) |

### V7: Admin 后台全页面 (15 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V7-01 | Dashboard 统计数据 | 加载 Dashboard→stats 数值与 DB 一致(用户数/请求数/收入)；图表渲染完整 |
| V7-02 | 账户管理 CRUD | 列表→分页+搜索→创建账户→编辑角色/状态→状态切换(冻结/解冻)→DB 同步 |
| V7-03 | 模型服务配置 | 列表 providers→添加 provider→配置 key→关联模型→切换回桌面端→模型可选 |
| V7-04 | 计费套餐管理 | 查看 plans→切换用户订阅→GET /billing/subscriptions/:userId 返回更新后的订阅→用户下次登录新配额生效 |
| V7-05 | 知识库管理 | 创建分类→添加知识条目→编辑→版本历史→搜索功能→返回匹配结果 |
| V7-06 | 知识库分析 | knowledge/analytics 返回 overview+trends+top_items+quality+gaps 各端点数据合理 |
| V7-07 | 结构化数据源 | 上传 Excel→解析为 structured_rows→SQL 查询返回结果→删除后不可查 |
| V7-08 | Prompt 模板管理 | 创建 prompt→编辑→查看版本→回滚到旧版本→版本号正确 |
| V7-09 | 角色权限矩阵 | 创建角色→配置权限→分配给用户→用户权限生效(可访问/不可访问的端点) |
| V7-10 | 行业配置管理 | 创建行业+关键词→配置 pain_seeds→关联到用户→用户查询命中该行业 |
| V7-11 | Agent 模板管理 | 创建模板→配置 soul/scenarios→分配给用户→用户端创建 Agent 基于→Agent 配置正确 |
| V7-12 | 定时任务管理 | 创建 cron 任务→列表显示→下次执行时间计算正确→手动触发→结果记录 |
| V7-13 | Relay 监控 | 查看任务列表→按状态筛选→查看任务详情→包含完整的 input/output/error |
| V7-14 | 日志审计 | 操作日志列表→按时间/用户/操作类型筛选→日志详情含 IP+UA+变更详情 |
| V7-15 | Config 同步 | 修改配置→同步到桌面端→桌面端 configStore 更新→sync_logs 有记录 |

### V8: 模型配置与计费 (10 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V8-01 | Provider CRUD | 创建 provider→设置 base_url + api_key + rate_limits→列表可见→更新→删除 |
| V8-02 | 模型 CRUD | 创建模型→关联 provider→设置 max_tokens/temperature→列表可见→参数正确 |
| V8-03 | Key 池管理 | Provider 下添加多个 key→各 key 独立 RPM/TPM 跟踪→禁用某 key→请求不再使用 |
| V8-04 | 计费套餐定义 | plans 列表含 Free/Pro/Team；每个 plan 含 features+limits JSON 结构完整 |
| V8-05 | 订阅切换 | 用户从 Free→Pro→配额限制更新；Pro→Free→超出 Free 配额的请求被拒绝 |
| V8-06 | 用量实时递增 | 每次聊天→GET /billing/usage 返回递增后的 used_tokens；数值与 GET /usage 统计一致 |
| V8-07 | 支付流程 | 创建支付→返回支付链接→mock-pay 确认→支付状态变为 paid→订阅生效 |
| V8-08 | 发票生成 | 支付完成后→GET /billing/invoices/:id/pdf 返回有效 PDF (Content-Type: application/pdf) |
| V8-09 | 模型白名单 | Free plan 只能用指定模型→请求不在白名单的模型→被拒绝 |
| V8-10 | Token 配额耗尽 | 配额用完→后续请求→429 + 明确的 quota exceeded 信息→不扣除额外费用 |

### V9: Pipeline 与工作流 (8 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V9-01 | Pipeline 模板列表 | pipeline_templates 返回 17 个模板；每个含 name+description+steps；YAML 格式有效 |
| V9-02 | Pipeline 创建与执行 | 从模板创建 pipeline→执行→progress 事件流→result 包含各步骤输出 |
| V9-03 | Pipeline DAG 验证 | 创建含依赖的 pipeline→验证 DAG 无环→执行顺序正确(依赖先完成) |
| V9-04 | Pipeline 取消 | 执行中 pipeline→cancel→已完成的步骤保留结果+未开始的不执行 |
| V9-05 | Pipeline 错误处理 | 某步骤失败→pipeline 状态=failed→错误信息含失败步骤名+原因 |
| V9-06 | 工作流 CRUD | 创建 workflow→编辑步骤→保存→列表可见→删除后不可见 |
| V9-07 | 工作流执行 | 执行 workflow→各节点按序执行→最终输出正确→运行历史可查 |
| V9-08 | 意图路由 | 发送自然语言描述→route_intent→匹配到正确的 pipeline 模板 |

### V10: 技能系统 (7 条)

| # | 链路 | 深度验证点 |
|---|------|-----------|
| V10-01 | 技能列表 | skill_list 返回已加载技能；每个含 name+description+triggers；非空 |
| V10-02 | 语义路由 | 发送匹配某技能 trigger 的查询→SkillIndex 中间件匹配→执行对应技能 |
| V10-03 | 技能执行 | skill_execute→返回结构化结果；执行时间合理；无 panic |
| V10-04 | 技能 CRUD | skill_create→列表可见→skill_update→字段更新→skill_delete→不可见 |
| V10-05 | 技能刷新 | 添加新 SKILL.md→skill_refresh→列表增加；移除 SKILL.md→刷新后减少 |
| V10-06 | 技能与聊天集成 | 聊天中触发技能→tool_call 事件→技能执行→结果注入对话 |
| V10-07 | 技能按需加载 | 无技能配置时→SkillIndex 中间件不注册；有技能时→正常注册 |

---

## 5. Layer 2: 跨系统横向验证 (24 条)

设计原则：每个角色走完一条完整的端到端旅程，每一步的输出是下一步的输入。

### R1: 医院行政 (日常使用全链路)

| # | 链路 | 跨系统验证点 |
|---|------|-------------|
| R1-01 | 新用户注册→管家冷启动 | 注册→登录→首次打开桌面端→管家自我介绍+引导→无报错；saasStore 写入账户信息→connectionStore 选择连接模式→KernelClient 初始化 |
| R1-02 | 医疗排班对话→管家路由→记忆 | 发"这周排班太乱了"→ButlerRouter 分类 healthcare→`<butler-context>` 注入→管家主动追问→痛点记录到 VikingStorage→SQLite 可查 |
| R1-03 | 第二次对话→记忆注入+痛点回访 | 新会话→系统提示含 `## 用户偏好` 段(上次偏好)→管家主动问"排班问题解决了吗"→记忆提取闭环完成 |
| R1-04 | 请求研究报告→Hand 触发→计费 | 发"帮我调研一下智能排班系统"→触发 Researcher Hand→Hand 执行返回结果→GET /usage 返回新增 token 记录→GET /billing/usage 返回递增配额 |
| R1-05 | 管家生成方案→痛点闭环 | 累积痛点足够→butler_generate_solution→返回结构化方案→用户查看→butler_update_proposal_status(accepted)→痛点状态变为 addressed |
| R1-06 | 审计验证全旅程 | Admin 审计日志页可见全旅程日志→上述所有操作均有记录(注册/登录/聊天/Hand 触发/方案生成)；日志含正确的时间戳+操作类型+目标 |

### R2: IT 管理员 (后台配置全链路)

| # | 链路 | 跨系统验证点 |
|---|------|-------------|
| R2-01 | Admin 登录→Provider+Key 配置 | Admin 登录→添加 Provider(DeepSeek)+API Key→GET /providers/:id/keys 返回新 key→key 的 RPM/TPM 初始值为 0 |
| R2-02 | 配置模型→桌面端同步 | 创建模型(deepseek-v3)→关联 Provider→Admin 可见→切换到桌面端→模型列表含新模型→发起聊天→模型字段正确 |
| R2-03 | 配额+计费联动 | 创建计费套餐→给用户分配→desktop 端 saasStore 更新订阅信息→用户发消息→quota 检查通过→聊天后 usage 递增→Admin 端 Usage 页数据同步 |
| R2-04 | 知识库→行业→管家路由 | Admin 创建行业"教育"+关键词+pain_seeds→关联到用户→触发 Tauri 命令 `viking_load_industry_keywords` 加载→用户发教育相关查询→ButlerRouter 命中自定义行业 |
| R2-05 | Agent 模板→用户端创建 | Admin 创建 Agent 模板(含 soul+scenarios)→分配给用户→用户端 AgentTemplates 可见→创建 Agent→配置从模板加载→聊天使用新 Agent 人格 |
| R2-06 | 定时任务→执行→审计 | 创建 cron 定时任务→等待触发(或手动触发)→GET /scheduler/tasks/:id 返回结果记录→操作日志有执行记录→状态流转 pending→running→completed |

### R3: 开发者 (API + 工作流全链路)

| # | 链路 | 跨系统验证点 |
|---|------|-------------|
| R3-01 | API Token 认证→Relay 调用 | 创建 API Token→用 token 调 POST /relay/chat/completions→SSE 响应正确→GET /relay/tasks 有记录→GET /usage 有 token 统计 |
| R3-02 | 多模型切换→Token 池→用量 | 连续用 3 个不同模型调 Relay→key 池自动选择对应 Provider→usage 按模型分别记录→Admin Usage 页可按 model 分组查看 |
| R3-03 | Pipeline 创建→执行→结果 | 从模板创建 pipeline→执行→progress 实时推送→result 包含完整输出→pipeline_runs 历史可查 |
| R3-04 | 技能触发→工具调用→结果 | 通过 API 触发技能→tool_call 执行→tool_result 返回→对话中包含工具输出 |
| R3-05 | 浏览器 Hand→自动化流程 | 通过 API 触发 Browser Hand→执行导航+点击+提取→结果返回→审计日志记录 |
| R3-06 | API 限流+权限→错误处理 | 超出 RPM→429 + Retry-After header；用 user 角色 token 调 admin 端点→403；过期 token→401 + 明确 message |

### R4: 普通用户 (注册→首次体验→持续使用)

| # | 链路 | 跨系统验证点 |
|---|------|-------------|
| R4-01 | 注册→邮箱验证→首次登录 | 注册→邮箱格式被验证→密码强度校验→注册成功→自动登录→JWT + refresh_token 存储→saasStore 初始化 |
| R4-02 | 首次聊天→模型选择→流式体验 | 无历史对话→选择模型→发消息→流式响应→消息持久化到 IDB→关闭重开→消息恢复 |
| R4-03 | 多轮对话→记忆积累→个性化 | 在 3 个独立对话会话中分别表达偏好(不模拟时间流逝)→每轮对话后记忆提取→第 4 个会话聊天→记忆检索返回至少 1 个先前偏好→系统提示含偏好段 |
| R4-04 | 触发 Hand→审批→结果查看 | 需要审批的操作→Hand 状态 pending→用户审批→执行→结果展示→操作日志记录 |
| R4-05 | 配额用尽→升级提示 | Free 配额耗尽→聊天返回 429→UI 显示升级提示→引导到计费页→支付后继续使用 |
| R4-06 | 安全设置→密码修改→TOTP | 修改密码→旧 session 失效→重新登录→设置 TOTP→下次登录需要验证码→设备信任管理 |

---

## 6. 执行策略

### 6.1 执行顺序与依赖

```
Phase 0: 基础设施健康检查 (5 条)
  ↓ 全部 PASS 才继续
Phase 1: 垂直测试 — 无依赖组 (并行)
  ├─ V1 认证与安全
  ├─ V2 聊天流 (依赖 V1-03 登录)
  └─ V8 模型配置与计费 (依赖 V1-03 登录)
  ↓ 认证+聊天+模型 PASS 后
Phase 2: 垂直测试 — 依赖组 (并行)
  ├─ V3 管家模式 (依赖 V2 聊天)
  ├─ V4 记忆管道 (依赖 V2 聊天)
  ├─ V5 Hands (依赖 V2 聊天)
  ├─ V6 Relay+Token 池 (依赖 V2 + V8)
  ├─ V9 Pipeline (依赖 V2 聊天)
  └─ V10 技能系统 (依赖 V2 聊天)
  ↓ 所有垂直组完成 (允许 PARTIAL)
Phase 3: 横向验证 (顺序执行)
  ├─ R1 医院行政旅程
  ├─ R2 IT 管理员旅程
  ├─ R3 开发者旅程
  └─ R4 普通用户旅程
```

### 6.2 测试数据策略

| 策略 | 说明 |
|------|------|
| **隔离前缀** | 所有测试创建的数据加前缀 `e2e_test_` |
| **测试账户** | V1 阶段创建：`e2e_admin`, `e2e_user`, `e2e_dev` |
| **幂等性** | 每条链路可独立重跑；检查"已存在则跳过" |
| **清理策略** | 不自动删除数据（保留用于分析），标注为测试数据 |
| **时间锚点** | 记录测试开始时间戳，断言基于 `> 开始时间` 过滤 |

### 6.3 断言失败分级

| 级别 | 含义 | 处理 |
|------|------|------|
| **CRITICAL** | 系统核心功能不可用 | 立即停止当前 Phase，报告根因 |
| **HIGH** | 功能可用但数据不正确 | 标记失败，继续执行，汇总报告 |
| **MEDIUM** | 非关键字段缺失或格式不完美 | 记录警告，不阻断 |
| **LOW** | UI 细节问题、性能轻微波动 | 记录观察，不影响判定 |

### 6.4 链路超时与重试

| 参数 | 值 |
|------|-----|
| 单条链路超时 | 120 秒 |
| LLM 响应等待超时 | 60 秒 |
| 页面加载超时 | 15 秒 |
| 截图等待 | 2 秒 |
| 失败重试 | 不重试（记录原始失败，保留现场） |

---

## 7. 结果报告

### 7.1 单条链路结果格式

```json
{
  "id": "V2-01",
  "name": "KernelClient 流式聊天",
  "phase": 1,
  "group": "V2",
  "status": "PASS | FAIL | SKIP | PARTIAL",
  "severity": "CRITICAL | HIGH | MEDIUM | LOW",
  "assertions": [
    {
      "point": "收到 text_delta 事件",
      "expected": ">0 events",
      "actual": "47 events",
      "result": "PASS"
    }
  ],
  "duration_ms": 4230,
  "evidence": {
    "screenshot": "path/to/screenshot.png",
    "api_response": "response snippet"
  },
  "error": null
}
```

### 7.2 汇总报告结构

| 指标 | 说明 |
|------|------|
| 总链路数 | 129 (5 + 100 + 24) |
| 通过率 | PASS / 总数 × 100% |
| 各 Phase 通过率 | Phase 0/1/2/3 分别统计 |
| CRITICAL 失败数 | 需立即修复 |
| Bug 清单 | 按 CRITICAL/HIGH/MEDIUM/LOW 分级 |
| 覆盖热力图 | 10 子系统 × 4 角色 矩阵 |
| SaaS API 覆盖率 | 已测试端点 / 总端点 |
| Admin 页面覆盖率 | 已测试页面 / 总页面 |
| Tauri 命令覆盖率 | 已测试命令 / 有前端调用的命令 |

---

## 8. 规模汇总

| 维度 | 数量 |
|------|------|
| Layer 0 基础设施 | 5 条 |
| Layer 1 垂直测试 | 100 条 |
| Layer 2 横向验证 | 24 条 |
| **总计** | **129 条** |
| 子系统覆盖 | 10/10 |
| 跨系统角色覆盖 | 4/4 |
| SaaS API 端点覆盖 | ~90/137 |
| Admin 页面覆盖 | 14/17 (Login 由 V1 隐式覆盖, ApiKeys/Usage 待后续补充) |
| Tauri 命令覆盖 | ~60/104 (有前端调用的) |
| 预估执行时间 | ~60 分钟 |

---

## 9. 前次 Bug 回归验证

以下为 04-16 E2E 报告中发现的 Bug，在本测试方案中的对应覆盖：

| Bug ID | 描述 | 对应测试链路 | 回归验证点 |
|--------|------|-------------|-----------|
| BUG-01 | Agent 创建返回 HTTP 502 | V7-11 (Agent 模板管理) + R2-05 (Agent 模板→用户端创建) | 验证 Agent 创建返回 201 (非 502)；Agent 配置从模板正确加载 |
| BUG-02 | 8 条历史消息显示"重试"按钮 | V2-10 (消息持久化验证) | 验证历史消息不包含"重试"伪影；刷新后消息状态正确恢复 |
| BUG-03 | Key Pool exhaustion — "所有 Key 均在冷却中" | V6-03 (Key 限流生效) + V6-02 (Token 池轮换) | 验证所有 key 耗尽场景返回 429 + 明确 message；key 冷却后自动恢复 |