zclaw_openfang/docs/superpowers/specs/2026-04-05-pre-launch-functional-audit-design.md

# ZCLAW 上线前功能审计方案

> **目标**: 对 ZCLAW 全部功能模块进行系统性的端到端验证，确保每个功能按设计文档正常工作，发现并修复所有 P0/P1 缺陷。
> **方法**: 基于 V12 模块化审计框架，12 模块逐个测试 + 端到端用户场景集成验证。
> **状态**: 设计完成，待执行。

---

## 1. 背景

### 1.1 当前状态

ZCLAW 已完成稳定化阶段（2026-04-03），V12 模块化审计给出了 76/100 的整体健康度。各模块健康度差异显著（58-91/100），低分模块存在未发现的功能缺陷风险。上线前需要一次系统性的全量功能验证。

### 1.2 已有基础设施

- **V12 审计**: V12 审计覆盖了 11 个功能模块（M1-M9, M11；M10 编号跳过无对应报告），含健康度评分和已知问题清单。本测试方案重组为 12 个测试模块（T1-T12），其中 T11（SaaS 后端 API）无独立 V12 审计报告，T12 为跨模块集成测试。
- **自动化测试**: Vitest (desktop + admin) + Playwright E2E (~278 tests) + cargo test (~595 tests, 含 386 同步 + 209 异步)
- **测试工具**: tauri-mcp（Tauri 端）、Playwright（Web E2E）、cargo test（Rust）、HTTP 脚本（SaaS API）
- **环境**: Tauri 桌面端 + SaaS 后端 + Admin V2 + LLM API Key 全部可用

### 1.3 设计决策

| 决策 | 选择 | 理由 |
|------|------|------|
| 测试方案 | 模块化系统测试 + 端到端用户场景 | 与 V12 审计对齐，效率最高 |
| Tauri 端测试工具 | tauri-mcp | 用户指定 |
| SaaS API 测试工具 | cargo test + HTTP | 已有 86+ 单元测试基础 |
| Admin V2 测试工具 | Playwright + vitest | 已有 ~71 单元测试 + Playwright 配置 |
| 测试范围 | 全量覆盖（12 模块） | 上线前无死角验证 |

---

## 2. 测试模块矩阵

### 2.1 模块清单（按风险排序）

| 序号 | 模块 | V12 健康度 | 风险等级 | 主要测试工具 | 关键验证点 |
|------|------|-----------|---------|------------|-----------|
| T1 | Hands 自主能力 | 58/100 | HIGH | tauri-mcp + cargo test | 9 Hands 触发/执行/审批闭环 |
| T2 | 智能层（记忆/反思/心跳/自主） | 61/100 | HIGH | tauri-mcp + cargo test | 记忆提取/注入、反思触发、心跳周期 |
| T3 | Agent 分身 | 67/100 | HIGH | tauri-mcp | Agent CRUD、身份切换、SOUL.md |
| T4 | 课堂系统 | 70/100 | HIGH | tauri-mcp | 场景播放、TTS、白板、笔记（含 3 个 P1 问题） |
| T5 | Pipeline 工作流 | 72/100 | MEDIUM | tauri-mcp + cargo test | DSL 解析、7 种 Action 执行、导出 |
| T6 | SaaS 桌面集成 | 85/100 | MEDIUM | tauri-mcp + HTTP | 登录/订阅/Relay/配置同步 |
| T7 | 技能生态 | 85/100 | LOW | tauri-mcp + cargo test | 75 Skills 加载/路由/执行（采样策略：5 个/执行模式 + 全量解析验证；重点验证 M5-01 tags-triggers 映射问题） |
| T8 | 智能对话 | 91/100 | LOW | tauri-mcp | 8 Provider 流式响应/Markdown/多模型切换 |
| T9 | Admin V2 后台 | 82/100 | MEDIUM | Playwright + vitest | 15 页面 CRUD、认证、数据流（10 页有测试，5 页缺失：Billing/ConfigSync/Knowledge/Roles/ScheduledTasks） |
| T10 | 通信与安全 | 86/100 | LOW | cargo test + HTTP | JWT/TOTP/Ed25519/CSP/限流 |
| T11 | SaaS 后端 API | N/A | MEDIUM | cargo test + HTTP | 131 API 端点、34 表、7 Worker |
| T12 | 端到端用户场景 | N/A | HIGH | tauri-mcp | 跨模块真实用户流程 |

### 2.1.1 T-M 映射表

本测试方案按风险重排了模块顺序。V12 审计编号 M10 跳过（无对应报告），T11 无 V12 审计基线。

| 测试模块 | V12 审计模块 | 说明 |
|---------|------------|------|
| T1 Hands 自主能力 | M3 | 健康度最低 (58/100) |
| T2 智能层 | M4 | 含 2 个 P0 问题 |
| T3 Agent 分身 | M2 | 14 个已知问题 |
| T4 课堂系统 | M11 | 3 个 P1 问题 |
| T5 Pipeline 工作流 | M6 | 2 个 P1 问题 |
| T6 SaaS 桌面集成 | M7 | SaaS 前端集成 |
| T7 技能生态 | M5 | 重点验证 M5-01 |
| T8 智能对话 | M1 | 健康度最高 (91/100) |
| T9 Admin V2 后台 | M8 | 15 页面，5 页缺测试 |
| T10 通信与安全 | M9 | 安全基线验证 |
| T11 SaaS 后端 API | 无 | 无 V12 审计，使用功能文档 + 集成测试作为基线 |
| T12 端到端用户场景 | 多模块 | 跨模块集成验证 |

### 2.2 测试工具分配

| 端 | 测试工具 | 用途 |
|----|---------|------|
| Tauri 桌面端 | tauri-mcp | UI 交互、组件状态、Tauri 命令调用、实时截图 |
| Rust 后端 | cargo test | 单元测试、集成测试（~595 已有 + 补充） |
| SaaS API | cargo test + HTTP | API 端点验证、权限检查、并发测试 |
| Admin V2 | Playwright + vitest | 页面交互、数据流（~71 已有测试，5 页需新增） |
| E2E 集成 | tauri-mcp | 跨模块端到端用户场景（桌面端真实交互） |

---

## 3. 测试用例设计

### 3.1 用例模板

```
TC-{模块编号}-{序号} | {用例名称}
前置条件: ...
测试步骤: ...
预期结果: ...
优先级: P0/P1/P2
场景类型: 正常(Normal) / 边界(Boundary) / 异常(Exception)
验证方法: tauri-mcp query_page + screenshot / cargo test / HTTP
```

### 3.2 三类场景定义

| 场景类型 | 定义 | 示例 |
|---------|------|------|
| **正常** | 核心功能的 Happy Path | 发送消息 -> 收到流式响应 -> 消息正确显示 |
| **边界** | 极限输入和状态转换 | 10000 字消息、同时触发 5 个 Hands、模型列表为空 |
| **异常** | 错误处理和降级 | API Key 无效错误提示、网络断开离线模式、LLM 超时重试 |

### 3.3 每模块用例数量

风险分级规则：HIGH = 健康度 < 75 或 P1 问题 >= 3；MEDIUM = 健康度 75-89；LOW = 健康度 >= 90 或安全模块。

| 风险等级 | 正常 | 边界 | 异常 | 合计 | 适用模块 |
|---------|------|------|------|------|---------|
| HIGH | 8-12 | 4-6 | 4-6 | 16-24 | T1, T2, T3, T4 |
| MEDIUM | 6-8 | 3-4 | 3-4 | 12-16 | T5, T6, T9, T11 |
| LOW | 4-6 | 2-3 | 2-3 | 8-12 | T7, T8, T10 |
| 集成 | 8-10 | 2-3 | 2-3 | 12-16 | T12 |

**预估总用例数: ~170-230 个**

### 3.4 缺陷分级标准

| 级别 | 定义 | 示例 | 修复时限 |
|------|------|------|---------|
| **P0 阻塞** | 核心功能完全不可用 | 聊天无法发送、App 崩溃 | 立即修复 |
| **P1 严重** | 主要功能异常但有 workaround | Hand 触发失败但手动可恢复 | 当天修复 |
| **P2 一般** | 次要功能异常或体验问题 | 设置页布局错位 | 本周修复 |
| **P3 轻微** | 视觉/文案/优化建议 | 按钮间距不一致 | 下个迭代 |
| **P4 建议** | 改进建议 | 交互体验优化 | 记录不修 |

---

## 4. 测试执行流程

### 4.1 四阶段执行计划

```
阶段 1: 环境准备 (预计 0.5-1 天)
  1.1 启动所有服务 (Tauri + SaaS + Admin + PostgreSQL)
  1.2 验证 tauri-mcp 连接
  1.3 确认至少 1 个 LLM Provider API Key 可用
  1.4 执行现有自动化测试基线
      - cargo test --workspace
      - cd desktop && pnpm vitest run
      - cd admin-v2 && pnpm vitest run
  1.5 记录基线结果

阶段 2: 高风险模块 (T1-T4) (预计 3-5 天)
  T1 Hands 自主能力 (58/100) -- 最优先
  T2 智能层 (61/100)
  T3 Agent 分身 (67/100)
  T4 课堂系统 (70/100)
  目标: P0/P1 缺陷清零
  注: 测试与修复并行，每发现 P0/P1 立即修复并回归验证

阶段 3: 中低风险模块 (T5-T11) (预计 3-5 天)
  T5 Pipeline -> T6 SaaS 集成 -> T7 技能 -> T8 对话
  T9 Admin V2 -> T10 安全 -> T11 SaaS API
  每模块完成后立即修复发现的问题
  注: T11 无 V12 审计报告，以功能文档 (docs/features/08-saas-platform/)
      和现有集成测试 (crates/zclaw-saas/tests/) 为基线

阶段 4: 端到端集成验证 (T12) (预计 2-3 天)
  8-10 个跨模块用户场景
  回归验证阶段 2-3 修复的问题
  生成最终测试报告

总计预估: 8-14 天
```

### 4.2 每模块执行流程

```
Step 1: 读取该模块的 V12 审计报告 (docs/features/audit-v12/M{n}-{name}.md)
        确认已知问题清单
        注: T11 (SaaS 后端 API) 无 V12 审计报告，跳过此步，
            以 docs/features/08-saas-platform/ 和 crates/zclaw-saas/tests/ 为基线

Step 2: 读取功能设计文档 (docs/features/{module-dir}/{doc}.md)
        理解预期行为和设计规范
        具体路径参见 Section 8 文件索引

Step 3: 执行该模块的现有自动化测试
        cargo test / vitest run -- 相关文件
        记录基线通过率

Step 4: 用 tauri-mcp 执行手动测试用例
        - query_page(mode='map') 获取页面结构
        - 执行用户交互 (click, type_text, navigate)
        - take_screenshot 截图记录
        - 验证 Store 状态 (execute_js 检查 Zustand)

Step 5: 发现问题 -> 立即修复 -> 回归验证
        修复后重新执行相关用例

Step 6: 模块完成 -> 生成测试报告
        更新 docs/features/audit-v12/ 中的模块报告
```

### 4.3 tauri-mcp 测试工作流

Tauri 端测试的标准化流程：

```
1. 窗口管理
   manage_window(action='list') -> 获取窗口列表
   manage_window(action='focus') -> 聚焦目标窗口

2. 页面状态检查
   query_page(mode='state') -> URL/title/scroll 状态
   query_page(mode='map') -> DOM 元素结构
   query_page(mode='find_element') -> 精确定位交互目标

3. 用户交互
   click(selector_type='ref', selector_value='{ref}') -> 点击
   type_text(text='{text}') -> 输入
   mouse_action(action='scroll', direction='down') -> 滚动
   navigate(action='goto', url='{url}') -> 导航

4. 状态验证
   take_screenshot() -> 截图记录
   wait_for(text=['{expected}']) -> 等待预期结果
   Store 状态验证优先级:
     a) DOM 元素内容检查 (query_page mode='map' 验证渲染结果)
     b) execute_js 检查 React 组件渲染状态 (document.querySelector)
     c) 如需直接访问 Store，通过 query_page(mode='map') 的 interactive_only=true
        检查受控组件值间接推断 Store 状态

5. 结果记录
   截图保存到 docs/test-results/{module}/
   测试结果记录到测试报告
```

---

## 5. 端到端用户场景 (T12)

### 5.1 核心用户场景

| # | 场景名称 | 涉及模块 | 关键步骤 |
|---|---------|---------|---------|
| E2E-01 | 新用户首次对话 | T8, T3, T7 | 打开应用 -> 首次引导 -> 选择模型 -> 发送消息 -> 收到回复 |
| E2E-02 | Agent 创建与使用 | T3, T8, T2 | 创建新 Agent -> 配置个性/技能 -> 切换到新 Agent -> 发送消息验证身份 |
| E2E-03 | Hand 触发与审批 | T1, T2, T8 | 对话中触发 Hand -> 查看执行状态 -> 审批确认 -> 查看结果 |
| E2E-04 | SaaS 登录与订阅 | T6, T10 | 登录 SaaS -> 查看订阅状态 -> 配置同步 -> 验证本地状态 |
| E2E-05 | Pipeline 创建与执行 | T5, T1 | 创建 Pipeline -> 配置 Action -> 执行 -> 查看结果 -> 导出 |
| E2E-06 | 记忆与反思闭环 | T2, T3, T8 | 多轮对话 -> 触发记忆提取 -> 验证记忆存储 -> 反思触发 -> 身份演化 |
| E2E-07 | Admin 管理全流程 | T9, T11 | 登录 Admin -> 管理账户 -> 配置模型 -> 查看日志 -> 管理 Prompt |
| E2E-08 | 离线与重连 | T1, T2, T6, T8 | 断开网络（tauri-mcp: 关闭 SaaS 后端模拟服务端不可达）-> 离线模式验证（聊天降级、Hand 事件队列、心跳检测）-> 恢复网络 -> 自动重连 -> 消息同步 |
| E2E-09 | 课堂场景播放 | T4, T1 | 进入课堂 -> 播放场景 -> TTS 朗读 -> 白板互动 -> 笔记记录 |
| E2E-10 | 技能发现与执行 | T7, T8 | 浏览技能市场 -> 安装技能 -> 对话中触发技能 -> 验证执行结果 |

---

## 6. 上线达标标准

### 6.1 强制达标项（全部必须通过）

| # | 达标项 | 标准 |
|---|--------|------|
| 1 | P0 缺陷 | 0 个 |
| 2 | P1 缺陷 | <= 2 个（且有明确修复计划） |
| 3 | 核心流程 | 聊天、Agent CRUD、Hand 触发、SaaS 登录 4 条主路径 100% 通过 |
| 4 | 自动化测试 | `cargo test --workspace` + `cd desktop && pnpm vitest run` + `cd admin-v2 && pnpm vitest run` + `cargo check --workspace` 全部通过 |
| 5 | 安全 | 无 HIGH 级别安全缺陷（复用渗透测试 V1 标准） |

### 6.2 建议达标项

| # | 达标项 | 目标 |
|---|--------|------|
| 1 | 整体通过率 | >= 95% |
| 2 | 模块最低健康度 | >= 65/100（所有模块），争取 >= 70/100。健康度重评采用与 V12 相同的 5 维度框架（功能完整性、代码质量、测试覆盖、文档完备、集成连通性），由测试执行者在每模块完成后打分 |
| 3 | 平均健康度 | >= 85/100 |
| 4 | E2E 用户场景通过率 | >= 90% |

---

## 7. 测试报告格式

### 7.1 模块测试报告模板

```markdown
## T{n} {模块名} 测试报告

### 摘要
- 执行用例数: X/Y
- 通过率: Z%
- 发现缺陷: P0: a, P1: b, P2: c, P3: d

### V12 已知问题验证
| V12 Issue ID | 描述 | V12 严重度 | 验证结果 | 备注 |
|-------------|------|-----------|---------|------|

### 新发现问题
| TC-ID | 描述 | 场景类型 | 优先级 | 状态 | 截图 |
|-------|------|---------|--------|------|------|

### 健康度评估
- V12 基线: XX/100
- 本次评估: YY/100
- 变化: +/-ZZ
- 关键改善: ...
- 残留风险: ...
```

### 7.2 最终交付物

| # | 交付物 | 路径 |
|---|--------|------|
| 1 | 测试计划文档 | `docs/test-results/TEST_PLAN.md` |
| 2 | 模块测试报告 | `docs/test-results/T{n}-{module}/REPORT.md` |
| 3 | 缺陷清单 | `docs/test-results/DEFECT_LIST.md` |
| 4 | 截图证据 | `docs/test-results/T{n}-{module}/screenshots/` |
| 5 | 上线评估 | `docs/test-results/RELEASE_READINESS.md` |
| 6 | 自动化脚本 | 新增的测试脚本（如有） |

---

## 8. 关键文件索引

### 8.1 功能设计文档

| 模块 | 文档路径 |
|------|---------|
| 通信层 | `docs/features/00-architecture/01-communication-layer.md` |
| 状态管理 | `docs/features/00-architecture/02-state-management.md` |
| 安全认证 | `docs/features/00-architecture/03-security-auth.md` |
| 聊天界面 | `docs/features/01-core-features/00-chat-interface.md` |
| Agent 分身 | `docs/features/01-core-features/01-agent-clones.md` |
| Hands 系统 | `docs/features/01-core-features/02-hands-system.md` + `docs/features/05-hands-system/` |
| 智能层 | `docs/features/02-intelligence-layer/` (8 files) |
| 技能生态 | `docs/features/04-skills-ecosystem/` |
| Pipeline | `docs/features/07-pipeline-dsl/` |
| SaaS 平台 | `docs/features/08-saas-platform/` |
| Tauri 后端 | `docs/features/06-tauri-backend/` |

### 8.2 V12 审计报告

| 模块 | 报告路径 |
|------|---------|
| M1 智能对话 | `docs/features/audit-v12/M1-intelligent-chat.md` |
| M2 Agent 分身 | `docs/features/audit-v12/M2-agent-clones.md` |
| M3 Hands | `docs/features/audit-v12/M3-hands-system.md` |
| M4 智能层 | `docs/features/audit-v12/M4-intelligence-layer.md` |
| M5 技能生态 | `docs/features/audit-v12/M5-skill-ecosystem.md` |
| M6 Pipeline | `docs/features/audit-v12/M6-pipeline-workflow.md` |
| M7 SaaS 桌面 | `docs/features/audit-v12/M7-saas-desktop.md` |
| M8 Admin V2 | `docs/features/audit-v12/M8-admin-v2.md` |
| M9 安全 | `docs/features/audit-v12/M9-communication-security.md` |
| M11 课堂 | `docs/features/audit-v12/M11-classroom.md` |

### 8.3 测试基础设施

| 类型 | 路径 |
|------|------|
| Desktop Vitest 配置 | `desktop/vitest.config.ts` |
| Desktop 测试文件 | `desktop/tests/` |
| E2E Playwright 配置 | `desktop/tests/e2e/playwright.config.ts` |
| E2E 测试文件 | `desktop/tests/e2e/specs/` |
| E2E 测试工具 | `desktop/tests/e2e/fixtures/` + `utils/` |
| Admin Vitest 配置 | `admin-v2/vitest.config.ts` |
| Admin 测试文件 | `admin-v2/tests/` |
| Root 测试文件 | `tests/` |
| Root Mock Server | `tests/fixtures/zclaw-mock-server.ts` |
| SaaS 集成测试 | `crates/zclaw-saas/tests/` |