zclaw_openfang/docs/archive/old-audits/V11_REMEDIATION_PLAN.md

# ZCLAW V11 修复优先级计划

> **生成日期**: 2026-04-02
> **关联审计**: COMPREHENSIVE_AUDIT_V11.md + V11_GAP_ANALYSIS.md

---

## Sprint 分配建议

### Sprint 1 (P1 — 紧急修复)

#### V11-P1-01: trigger_update 参数修复
- **影响**: Trigger 配置更新静默失败
- **修复复杂度**: 低（1 文件修改）
- **文件**: `desktop/src/lib/kernel-triggers.ts:99`
- **方案**: 将嵌套 `updates` 对象展开为扁平参数
```typescript
// 修复前:
await invoke('trigger_update', { id, updates });

// 修复后:
await invoke('trigger_update', {
  id,
  name: updates.name,
  enabled: updates.enabled,
  handId: updates.handId,
});
```
- **同时修复**: Rust 端添加 `trigger_type` 参数支持（trigger.rs:183-189）
- **验证**: 修改 trigger 配置后检查 Kernel 状态

#### V11-P1-02: SaaS 配置同步传播
- **影响**: SaaS 管理员修改配置后不影响 Kernel 运行时
- **修复复杂度**: 中（需要新增 Tauri 命令或事件机制）
- **方案**:
  - 选项 A: saasStore.pullConfig 完成后调用 Tauri command 通知 Kernel 重新加载配置
  - 选项 B: Kernel 定期检查配置文件变更（watcher）
  - 选项 C: 明确记录为 "前端缓存同步，不影响 Kernel"
- **建议**: 先选 C（文档对齐），后续迭代实现 A
- **验证**: 在 SaaS 后台修改配置 → 检查 Kernel 日志是否反映变更

#### V11-P1-03: 孤立 SQL 表处理
- **影响**: 数据写入但无法读取，浪费存储
- **修复复杂度**: 低
- **方案**:
  - `prompt_sync_status`: 实现读取查询（OTA 端点需要）
  - `telemetry_reports`: 添加 admin-v2 查询端点
  - `key_usage_window`: 确认是否需要（限流可能已改用内存方案）
- **验证**: `grep -rn "SELECT.*FROM.*<table>" crates/zclaw-saas/src/` 有结果

---

### Sprint 2 (P2 — 高优先级)

#### V11-P2-01: 删除 saas-admin.ts
- **修复复杂度**: 低（删除 1 文件 + saas-client.ts 中的 install 调用）
- **前置条件**: 确认 admin-v2 完全不依赖此文件
- **验证**: admin-v2 所有页面功能正常

#### V11-P2-02: Role/Permission 管理
- **选项 A**: 为 admin-v2 添加 roles service 和页面
- **选项 B**: 移除 SaaS role 路由（如果当前不需要 RBAC）
- **建议**: 评估业务需求后决定

#### V11-P2-03: 迁移 deprecated gateway-storage 调用者
- **文件**: `gateway-client.ts:44,71,211`, `configStore.ts:252`
- **方案**: 将 sync 方法调用替换为 async 版本
- **验证**: Gateway 连接功能测试

#### V11-P2-04: ToolDefinition 去重
- **文件**: `zclaw-runtime/src/driver/mod.rs:94`
- **方案**: 重导出 `zclaw-types::tool::ToolDefinition`
- **验证**: `cargo build` 通过

#### V11-P2-05: 未调用 Tauri 命令评估
- **62 个命令**需逐一评估：
  - classroom_*: 确认 classroomStore 是否真正调用（可能是 store 中调用的）
  - pipeline_*: 确认 workflowStore 是否调用
  - gateway_*: 确认是否有侧车进程调用
  - viking_*: 确认 Settings 页面是否调用
- **验证**: 对每个命令 grep `invoke('command_name'`

#### V11-P2-06: SQL LIMIT 添加
- **文件**: `migration/service.rs`, `knowledge/service.rs`
- **方案**: 为 config_items SELECT 添加 LIMIT 1000，knowledge_categories 添加 LIMIT 100
- **验证**: SQL 执行计划验证

---

### Sprint 3 (P3 — 中优先级)

#### V11-P3-01: audit-logger 接入
- **方案**: 在 ApprovalsPanel、AutonomyConfig、chatStore 的关键操作中添加 logAudit 调用
- **或**: 标记为 reserved 并从 index 导出中移除

#### V11-P3-02: OFP 能力处理
- **方案**: 添加 `// Reserved for OpenFang Protocol` 注释或移除变体

#### V11-P3-03: 移除 deprecated extract_structured_facts
- **方案**: 删除 growth.rs:224 的 deprecated 方法
- **验证**: `cargo build` 通过

#### V11-P3-04: SaaS knowledge stub 实现
- **文件**: knowledge/handlers.rs:91,293,321
- **方案**: 实现真正的分页查询、回滚、推荐算法
- **验证**: admin-v2 Knowledge 页面功能测试

#### V11-P3-05: 定时任务执行结果持久化
- **方案**: 添加 last_result/last_error 列到 scheduled_tasks 表
- **迁移**: 新增 SQL migration
- **验证**: 创建定时任务 → 执行 → 检查结果是否存储

#### V11-P3-06 ~ P3-08: 其他清理
- 移除 secure-storage sync 方法
- 启用 embedding 生成或注释
- 清理 config 预留参数注释

---

### Sprint 4 (P4 — 低优先级 / 文档)

#### V11-P4-01: ContentBlock 命名规范
- **方案**: 为每个 crate 的 ContentBlock 添加 crate 前缀注释
- `zclaw_types::ContentBlock` = LLM 消息内容
- `zclaw_hands::ContentBlock` = 幻灯片渲染
- `zclaw_protocols::ContentBlock` = MCP 协议格式

#### V11-P4-02: 类型名称统一
- **方案**: 建立共享类型包 `@zclaw/types` 或使用 OpenAPI schema 生成
- 13+ 类型名称不一致需要协调

#### V11-P4-03: 文档数字更新
- Skills: 76
- Hands: 9 目录（CLAUDE.md 应更新 "11" → "9 目录 + 2 禁用配置"）
- Tauri 命令: 175
- SaaS 路由: 58
- Stores: 15

#### V11-P4-04/05: Feature-gated 代码保持现状
- Director/A2A/WASM: 等产品路线图决定
- Embedding 生成: 等 OpenViking 集成完成后启用

---

## 依赖关系图

```
V11-P1-01 (trigger_update 修复)
  └── 无依赖，可独立完成

V11-P1-02 (配置同步传播)
  └── 依赖设计决策（选项 A/B/C）

V11-P1-03 (孤立表处理)
  └── V11-P2-06 (SQL LIMIT) 可同时处理

V11-P2-01 (删除 saas-admin.ts)
  └── V11-P2-04 (ToolDefinition 去重) 可同时完成

V11-P2-03 (迁移 deprecated 调用)
  └── 需要先确认 async 版本稳定性

V11-P3-04 (knowledge stub 实现)
  └── 依赖 V11-P1-03（确认表用途后实现读取）

V11-P4-02 (类型统一)
  └── 长期任务，不阻塞其他修复
```

---

## 修复工作量估算

| Sprint | 项数 | 预估工作量 | 风险等级 |
|--------|------|-----------|----------|
| Sprint 1 (P1) | 3 | 中 | 高（P1-02 需设计决策） |
| Sprint 2 (P2) | 6 | 高 | 中（P2-05 工作量大） |
| Sprint 3 (P3) | 8 | 中 | 低 |
| Sprint 4 (P4) | 5 | 低 | 低 |

---

## 验证检查清单

### 编译验证
```bash
cargo build --workspace
pnpm tsc --noEmit
```

### 功能验证
- [ ] 创建/更新/删除 Trigger → 检查 Kernel 状态
- [ ] SaaS 后台修改配置 → 检查 desktop 前端行为
- [ ] Admin-v2 Knowledge 页面 CRUD
- [ ] 定时任务执行 → 检查结果存储
- [ ] Agent 审批 → Hand 自动执行
- [ ] Pipeline 运行 → 完成事件通知

### 回归验证
```bash
# Rust 测试
cargo test --workspace

# 前端测试
pnpm vitest run

# Admin-v2 测试
cd admin-v2 && pnpm test
```