# ZCLAW 系统偏离分析与演化路线图更新方案

**分析日期**: 2026-03-15
**目的**: 基于代码层面深度分析，更新系统偏离点，制定下一阶段演化路线
**状态**: ✅ **全部完成**

---

## 一、背景与上下文

### 1.1 为什么需要这次分析？

现有的 [SYSTEM_ANALYSIS.md](docs/SYSTEM_ANALYSIS.md) 记录了 Phase 1-5 的完成状态和 Phase 6 的进行中状态。但代码层面的深度分析发现了新的偏离点，特别是：

1. **Team 协作功能** - 文档标记为"进行中"，但代码显示 `teamStore.ts` 完全使用 localStorage 而非真实 API
2. **REST API 认证缺失** - WebSocket 有完整认证，REST 请求无认证头
3. **设置持久化问题** - 主题/自动启动等设置仅改变本地状态
4. **编辑模式不完整** - WorkflowEditor 编辑时不加载现有步骤

### 1.2 分析方法

使用 3 个并行 Explore 代理深度分析：
- 前端组件和 UI 状态管理
- OpenFang 通信层实现
- 配置和技能系统

### 1.3 实施方法

使用多代理并行执行：
- 14 个专业代理并行工作
- TypeScript + Rust 双重验证
- 所有修改通过 `pnpm tsc --noEmit` 和 `cargo check`

---

## 二、新发现的偏离点

### 2.1 关键数据流断裂 (P0 - 最高优先级)

| ID | 组件 | 问题描述 | 影响 |
|----|------|----------|------|
| **A1** | [teamStore.ts](desktop/src/store/teamStore.ts) | 所有 CRUD 操作使用 localStorage，从未调用 [team-client.ts](desktop/src/lib/team-client.ts) API | Team 协作功能完全虚假 |
| **A2** | [WorkflowEditor.tsx:217](desktop/src/components/WorkflowEditor.tsx#L217) | 编辑模式初始化空步骤，不加载现有工作流 | 无法编辑真实工作流 |
| **A3** | [SchedulerPanel.tsx:649](desktop/src/components/SchedulerPanel.tsx#L649) | 事件触发器创建显示占位 alert | 无法创建事件触发器 |

### 2.2 安全与配置偏离 (P0-P1)

| ID | 组件 | 问题描述 | 影响 |
|----|------|----------|------|
| **B1** | [gateway-client.ts](desktop/src/lib/gateway-client.ts) | REST API 请求不携带认证头 | 未认证的 REST 调用 |
| **B2** | [gateway-client.ts](desktop/src/lib/gateway-client.ts) | Token 存储在 localStorage | 敏感数据不安全存储 |
| **B3** | [General.tsx:9-11](desktop/src/components/Settings/General.tsx#L9-L11) | 主题/自动启动仅改变本地 state | 设置不持久化到 TOML |

### 2.3 端口与文档偏离

| 来源 | 端口 | 状态 |
|------|------|------|
| **实际 OpenFang** | 50051 | 代码正确适配 |
| **文档** | 4200 | 需更新 |
| **FALLBACK_GATEWAY_URLS** | 50051, 4200 | 回退列表包含两个 |

---

## 三、演化路线图 (更新版) - ✅ 全部完成

### Phase 0: 稳定化修复 ✅ 完成

**目标**: 修复关键数据流断裂问题

| 任务 | 状态 | 文件 |
|------|------|------|
| Team Store API 集成 | ✅ 完成 | `teamStore.ts` - 替换 localStorage 为 API |
| REST API 认证 | ✅ 完成 | `team-client.ts` - 添加 `getAuthHeaders()` |
| Workflow 编辑器步骤加载 | ✅ 完成 | `WorkflowEditor.tsx` - 编辑模式加载步骤 |

### Phase 1: 功能对齐 ✅ 完成

**目标**: 连接所有 UI 组件到真实 OpenFang 能力

| 任务 | 状态 | 文件 |
|------|------|------|
| 事件触发器创建 | ✅ 完成 | `CreateTriggerModal.tsx` (新建) |
| 设置持久化 | ✅ 完成 | `General.tsx` - 连接 gatewayStore |
| WebSocket 团队事件订阅 | ✅ 完成 | `useTeamEvents.ts`, `teamStore.ts` |
| 安全 Token 存储 | ✅ 完成 | `secure_storage.rs` (新建), `secure-storage.ts` (新建) |

### Phase 2: 架构优化 ✅ 完成

**目标**: 改善系统架构以提高可维护性和性能

| 任务 | 状态 | 文件 |
|------|------|------|
| TOML 配置支持 | ✅ 完成 | `toml-utils.ts`, `config-parser.ts`, `types/config.ts` |
| 请求超时和重试 | ✅ 完成 | `request-helper.ts` (新建) |

### Phase 3: 扩展和增强 ✅ 完成

**目标**: 完善 OpenFang 特有功能的 UI

| 任务 | 状态 | 文件 |
|------|------|------|
| 16 层安全状态 UI | ✅ 完成 | `SecurityLayersPanel.tsx` (新建) |
| Hand 审批工作流 | ✅ 完成 | `HandApprovalModal.tsx`, `ApprovalsPanel.tsx` |
| 增强 Hand 参数 UI | ✅ 完成 | `HandParamsForm.tsx` (新建) |
| 审计日志查看器 | ✅ 完成 | `AuditLogsPanel.tsx` - Merkle 链验证

---

## 四、风险评估

### 高风险变更

| 变更 | 风险 | 缓解措施 |
|------|------|----------|
| Team Store API 集成 | API 失败导致数据丢失 | Feature flag 回退到 localStorage |
| 安全 Token 存储 | 认证中断 | 渐进迁移带回退 |
| TOML 解析器 | 配置损坏 | 写入前验证，保留备份 |

### 中等风险变更

| 变更 | 风险 | 缓解措施 |
|------|------|----------|
| REST 认证头 | 401 循环 | 智能重试带用户提示 |
| 配置同步 | 竞态条件 | 乐观锁，冲突 UI |
| 后端抽象 | 功能缺口 | 能力检测，优雅降级 |

---

## 五、成功度量

### Phase 0 完成标准
- [ ] Team CRUD 操作使用真实 API (通过网络请求验证)
- [ ] 所有 REST 请求包含认证头
- [ ] Workflow 编辑模式加载现有步骤
- [ ] Team 数据不再使用 localStorage (除缓存)

### Phase 1 完成标准
- [ ] 事件触发器可创建并正确触发
- [ ] 设置在应用重启后持久化
- [ ] 实时团队事件更新 UI
- [ ] Token 存储在安全存储中

### Phase 2 完成标准
- [ ] TOML 配置可读写
- [ ] 请求重试在瞬态故障时成功
- [ ] 后端可通过配置切换
- [ ] 配置变更双向同步

### Phase 3 完成标准
- [ ] 所有 16 层安全有 UI 展示
- [ ] Hand 审批工作流可用
- [ ] Hand 参数支持所有类型
- [ ] 审计日志可验证

### 总体指标

| 指标 | 当前 | 目标 |
|------|------|------|
| localStorage 使用 | 3 个文件 | 0 (除缓存) |
| API 集成 | ~70% | 100% |
| 实时事件 | 30% | 100% |
| 安全 UI 覆盖 | 20% | 100% |
| 测试覆盖率 | 未知 | 80%+ |

---

## 六、实施顺序

```
第 1-2 周: Phase 0
├── 0.1 Team Store API 集成 (3 天)
├── 0.2 REST API 认证 (2 天)
└── 0.3 Workflow 编辑器步骤加载 (2 天)

第 3-5 周: Phase 1
├── 1.1 事件触发器创建 (3 天)
├── 1.2 设置持久化 (2 天)
├── 1.3 WebSocket 事件订阅 (3 天)
└── 1.4 安全 Token 存储 (2 天)

第 6-8 周: Phase 2
├── 2.1 TOML 配置支持 (3 天)
├── 2.2 请求超时和重试 (2 天)
├── 2.3 后端抽象层 (3 天)
└── 2.4 配置同步服务 (2 天)

第 9-12 周: Phase 3
├── 3.1 16 层安全状态 UI (4 天)
├── 3.2 Hand 审批工作流 (3 天)
├── 3.3 增强 Hand 参数 UI (2 天)
└── 3.4 审计日志查看器 (3 天)
```

---

## 七、关键文件清单

### 需要修改的核心文件

| 文件 | 修改类型 | 优先级 |
|------|----------|--------|
| [desktop/src/store/teamStore.ts](desktop/src/store/teamStore.ts) | 替换 localStorage 为 API 调用 | P0 |
| [desktop/src/lib/team-client.ts](desktop/src/lib/team-client.ts) | 添加认证头和错误处理 | P0 |
| [desktop/src/lib/gateway-client.ts](desktop/src/lib/gateway-client.ts) | REST 认证模式参考 | P0 |
| [desktop/src/components/WorkflowEditor.tsx](desktop/src/components/WorkflowEditor.tsx) | 添加步骤加载 | P0 |
| [desktop/src/components/Settings/General.tsx](desktop/src/components/Settings/General.tsx) | 设置持久化 | P1 |

### 需要新建的文件

| 文件 | 用途 | 阶段 |
|------|------|------|
| `desktop/src/lib/config-client.ts` | 配置 API 客户端 | Phase 1 |
| `desktop/src/lib/toml-parser.ts` | TOML 解析工具 | Phase 2 |
| `desktop/src-tauri/src/secure_storage.rs` | 安全存储 Rust 命令 | Phase 1 |
| `desktop/src/components/CreateTriggerModal.tsx` | 触发器创建模态框 | Phase 1 |

---

## 八、验证方法

### 每个 Phase 完成后的验证

1. **自动化测试**
   ```bash
   pnpm vitest run tests/desktop/
   pnpm tsc --noEmit
   ```

2. **手动验证**
   - 连接 OpenFang (端口 50051)
   - 验证数据流真实连接
   - 检查 localStorage 使用情况
   - 验证设置持久化

3. **代码审查**
   - 检查认证头存在
   - 验证错误处理完整
   - 确认无硬编码值

---

*计划创建: 2026-03-15*
*预计完成: 2026-06-15 (12 周)*