# ZCLAW 模块化端到端深度功能验证审计方案

> **版本**: v1.1 (review fix)
> **日期**: 2026-04-04
> **状态**: 设计完成，待执行
> **审计目标**: 端到端功能验证——系统性找出每个模块从 UI 到后端的断链

---

## 1. 背景与动机

ZCLAW 项目已有 14 次审计历史（V1-V11 共 11 轮版本化审计 + 3 轮专项审计），前几轮以"技术层横向扫描"为主：检查 Tauri 命令调用率、SaaS API 前端消费、死代码清理等。这些审计修复了大量问题，但存在三个结构性盲区：

1. **缺乏功能视角** — 已知 24 个 Tauri 命令无前端调用，但不知属于哪些用户故事
2. **缺乏边界验证** — 只查"调了没有"，没查"调错了怎么表现"、"空数据怎么表现"
3. **缺乏累积性** — 每轮从头扫，无模块级基线

本方案以**功能领域为主轴**组织审计，以标准化的**五维检查清单**确保不遗漏，以**三波并行策略**高效执行。

---

## 2. 审计模块划分

### 模块清单

| 模块 | 功能领域 | 核心链路 | 涉及关键文件 |
|------|---------|---------|-------------|
| **M1** | 智能对话 | 用户输入 → ChatArea → chatStore → Kernel → LLM Driver → 流式回传 | `components/ai/*`, `store/chat/*`, `lib/kernel-chat.ts`, `kernel_commands/chat.rs`, `zclaw-runtime/src/driver/*` |
| **M2** | Agent 分身 | 创建/切换/配置 Agent → agentStore → Kernel → SQLite | `agentStore.ts`, `lib/kernel-agent.ts`, `kernel_commands/agent.rs`, `zclaw-memory/src/agent_store.rs` |
| **M3** | Hands 自主能力 | 触发 Hand → handStore → Kernel → Hand 执行 → 事件回调 | `handStore.ts`, `lib/kernel-hands.ts`, `crates/zclaw-hands/src/hands/*`, `hands/*.HAND.toml` |
| **M4** | 智能层 | 记忆/身份/反思/心跳/自主授权/压缩 各链路 | `intelligence-client/*`, `store/memoryGraphStore.ts`, `intelligence/*.rs` |
| **M5** | 技能生态 | 技能浏览/搜索/执行 → Skills 语义路由 → SKILL.md | `lib/kernel-skills.ts`, `crates/zclaw-skills/src/*`, `skills/*.md` |
| **M6** | Pipeline 工作流 | 创建/编辑/执行 Pipeline → workflowStore → DSL Engine | `components/pipeline/*`, `workflowStore.ts`, `crates/zclaw-pipeline/src/*` |
| **M7** | SaaS 平台(Desktop) | 登录/配置/支付 → saasStore → saas-client → SaaS API | `components/SaaS/*`, `saasStore.ts`, `lib/saas-client.ts`, `crates/zclaw-saas/src/*` |
| **M8** | Admin V2 | 14 页面 CRUD → 18 services → SaaS API → PostgreSQL | `admin-v2/src/pages/*`, `admin-v2/src/services/*` |
| **M9** | 通信与安全 | 连接管理/认证/TOTP/加密/限流/MCP 协议 | `connectionStore.ts`, `securityStore.ts`, `gateway-client.ts`, `lib/mcp-client.ts`, `crates/zclaw-saas/src/auth/*`, `crates/zclaw-protocols/src/mcp/*` |
| **M10** | 横切关注点 | 错误一致性、类型一致性、并发安全（汇总分析） | 全局横切 |
| **M11** | Classroom 课堂 | 课堂场景播放/聊天/笔记/白板/TTS | `store/classroomStore.ts`, `components/classroom_player/*`, `lib/classroom-adapter.ts` |

---

## 3. 五维检查模板

每个模块必须完成以下五个维度的检查：

### 维度 1: 链路完整性

- 画出该模块的完整调用链（UI → Store → Client → IPC/API → Rust → DB/网络）
- 标注每个节点的文件路径
- 检查每条边的连通性（"写了没接"检查）

### 维度 2: 参数/类型一致性

| 检查点 | 方法 |
|--------|------|
| 前端调用参数 vs Rust 命令签名 | 逐字段比对名称、类型、Optionality |
| 返回值类型链路 | Rust struct → Tauri IPC → TS type → Store state |
| 枚举值/常量两端同步 | 比对 Rust enum 与 TS union type |
| 数据库字段与 API 字段对齐 | SQL 列 vs handler struct field |

### 维度 3: 边界与错误处理

| 场景 | 检查内容 |
|------|---------|
| 空状态 | 数据库无数据时 UI 表现；空字符串/空数组/null 参数传递 |
| 错误状态 | 网络 5xx / 4xx / 超时 / 序列化失败 → 是否有用户可见反馈 |
| 并发 | 快速双击；多操作并行；Token 刷新并发 |
| 性能降级 | 大数据量（1000+ 消息）；FTS 全表扫描；连接池满 |
| 输入边界 | 超长文本、特殊字符、非 UTF-8、负数、零值 |

### 维度 4: 状态管理

- Store 状态机完整性（loading / success / error / reset）
- 组件是否正确订阅 Store 变化
- 持久化/恢复路径是否完整
- 竞态条件风险（stale closure、过期 setState）

### 维度 5: 安全与资源

- 敏感数据加密/脱敏
- 资源泄漏（事件监听器未清理、定时器未清除、连接未释放）
- 权限检查完整性
- 日志是否包含敏感信息

---

## 4. 断链检测方法

### 步骤 1: Tauri 命令调用矩阵

```
对模块涉及的所有 Tauri 命令:
  1. 从 kernel_commands/mod.rs 提取 #[tauri::command] 注册名
  2. grep desktop/src/ 找 invoke('commandName') 调用
  3. 对比 → 标注 connected / reserved / broken
```

### 步骤 2: 参数签名级比对

```
对每个 connected 命令:
  1. 提取 Rust 端参数类型定义 (struct/derive)
  2. 提取 TS 端调用参数
  3. 逐字段比对名称/类型/Optionality
  4. 不匹配 → 记为 P1 断链
```

### 步骤 3: 事件链路追踪

```
  1. grep desktop/src-tauri/src/ 找 .emit("event-name") 发射点
  2. grep desktop/src/ 找 .listen("event-name") 监听点
  3. 交叉比对 → 找出 emit 但无 listen 的断裂
```

### 步骤 4: 数据库-API-UI 三端对齐

```
  1. grep crates/zclaw-saas/src/ 找 SELECT/INSERT 语句
  2. 对比 API handler 暴露的端点
  3. 对比前端 service 层调用
  4. 找出"有表无 API" 或 "有 API 前端未调"
```

---

## 5. 边界验证方法

采用三层验证策略：

### 第一层: 静态分析（工具辅助，60% 工作量）

| 检查 | 命令 |
|------|------|
| TypeScript 类型安全 | `tsc --noEmit` |
| Rust 编译检查 | `cargo check` |
| 潜在 panic | `grep -rn "unwrap()" crates/` |
| 静默忽略 | `grep -rn "let _ =" crates/` |
| 类型逃逸 | `grep -rn "as any" desktop/src/` |
| 技术债标记 | `grep -rn "TODO\|FIXME\|HACK"` |

### 第二层: 代码推理（人工审查，30% 工作量）

对每条链路的每个"edge"，推理：
- 上游返回 null/undefined/Err 时，下游如何处理？
- 上游超时 30s 无响应，UI 如何表现？
- 用户在 loading 期间切换页面，状态如何恢复？

### 第三层: 实机验证（P0/P1 必须，高频模块加强）

**标准模块（M2/M4-M11）**: 10% 工作量，仅 P0/P1 级发现做实机验证。

**高频模块（M1/M3）**: 20-30% 工作量，除 P0/P1 外还需验证：
- 并发场景：快速连续发送消息、快速连续触发 Hand
- 流式中断：中途断网、切换模型、切换 Agent
- 大数据场景：1000+ 消息加载、长时间会话压缩

实机验证启动命令：`pnpm start:dev`
- 空数据场景：清空相关表，验证 UI 不崩溃
- 错误场景：关闭后端服务，验证前端降级提示
- 并发场景：快速连续触发同一操作

---

## 6. 优先级分级标准

| 级别 | 定义 | 示例 | 修复时限 |
|------|------|------|---------|
| **P0** | 必然崩溃或数据丢失，用户无法绕过 | skill_execute 空参数导致 serde panic | 立即 |
| **P1** | 功能失效但不崩溃；核心功能断链 | API 路径 404、参数不匹配静默失败 | 24h |
| **P2** | 功能部分可用但不完整；可能演变为 P1 | 静默忽略错误、fire-and-forget spawn | 1 周 |
| **P3** | 不影响功能但影响可维护性 | 类型命名不一致、文档数字偏差 | 下个迭代 |
| **P4** | 信息级建议改进 | 配置参数预留未消费、feature-gated 未启用 | backlog |

### 判断流程

```
用户是否看到异常？ → 是 → P0/P1
数据是否丢失/损坏？ → 是 → P0
核心路径是否受阻？ → 是 → P1
是否可能引发 P1？ → 是 → P2
是否仅影响开发者体验？ → 是 → P3/P4
```

---

## 7. 执行策略

### 执行假设与节奏

- **执行者假设**: 单人执行（AI Agent 辅助 + 人工决策）
- **模块粒度**: 每模块约 1 个工作日（含五维检查 + 报告编写）
- **总工期**: 11 个工作日（11 模块 x 1 天/模块），跨约 2.5 周

### 波次安排

| 波次 | 模块 | 耗时 | 说明 |
|------|------|------|------|
| **第一波** | M1(对话) + M2(Agent) + M3(Hands) | 3 天 | 核心路径，历史断链最密集区 |
| **第二波** | M4(智能层) + M5(技能) + M6(Pipeline) | 3 天 | 智能与编排 |
| **第三波** | M7(SaaS) + M8(Admin) + M11(Classroom) | 3 天 | 平台层 |
| **第四波** | M9(通信安全) + M10(横切汇总) | 2 天 | 基础设施+全量汇总 |

每波内模块顺序执行（单 Agent 每日 1 模块），避免 context 窗口溢出。

### 模块内部执行顺序

五维检查串行执行：链路图 → 参数比对 → 边界验证 → 状态管理 → 安全检查

---

## 8. 报告格式

每个模块独立输出一份审计报告，格式如下：

```markdown
# 模块 [Mx] [模块名] 审计报告

## 1. 模块概况
- 功能描述
- 涉及文件清单（按层分类）
- 调用链路图
- 前次审计已知问题继承

## 2. 五维检查结果

### 2.1 链路完整性
| 链路 | 起点 | 终点 | 状态 | 断裂点 |

### 2.2 参数/类型一致性
| 接口 | 前端类型 | 后端类型 | 一致性 | 不匹配字段 |

### 2.3 边界与错误处理
| 场景 | 输入 | 预期行为 | 实际行为 | 级别 |

### 2.4 状态管理
| Store | 状态机完整性 | 持久化 | 竞态风险 |

### 2.5 安全与资源
| 检查项 | 状态 | 说明 |

## 3. 问题清单
| ID | 描述 | 文件:行号 | 级别 | 修复建议 | 验证方法 |

## 4. 改进建议
- 短期修复项（按优先级排序）
- 长期架构建议
```

最终汇总为 `docs/features/MODULE_AUDIT_SUMMARY.md`，包含：
- 各模块问题统计表
- P0/P1 问题优先修复清单
- 整体健康度评分
- 对 TRUTH.md 数字更新的建议

---

## 9. 与已有审计的衔接

- **继承 AUDIT_TRACKER.md**：每个模块开头从已有追踪表继承已知问题
- **更新 TRUTH.md**：审计中发现的数字偏差回写真相源
- **延续版本线**：本审计为 V12（第 15 次），报告编号继续递增
- **新 P0 处理流程**：审计中发现的 P0 级问题立即中断当前模块审计，优先修复并验证，再继续审计
- **避免重复**：已标记为"已修复"的问题仅做验证性检查，不重新审计

---

## 10. 前几轮审计盲区（本次重点关注）

| 盲区 | 说明 | 本次覆盖维度 |
|------|------|-------------|
| Store 状态机完整性 | 前几轮几乎未检查 loading/error/reset | 维度 4 |
| 错误传播链路 | 后端 Err 是否能传到 UI | 维度 3 |
| 事件监听对称性 | emit 但无 listen 的断裂 | 维度 1 |
| 并发安全 | 约 15 处 fire-and-forget spawn 未审计 | 维度 5 |
| 空数据降级 | Desktop 端空数据表现未验证 | 维度 3 |
| Desktop 前端零测试 | 边界验证只能靠代码推理+实机 | 维度 3，M1/M3 加强实机验证 |
| Classroom 课堂 | 27 个 Tauri 命令中 7 个无前端调用，未审计 | 新增 M11 |
| MCP 协议链路 | MCP 服务发现→工具列举→执行 链路未验证 | M9 增加检查项 |