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 模块测试报告模板

## 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/