# ZCLAW 项目上线前全面审查计划

## 背景

ZCLAW 系统开发已进入收尾阶段，需要执行全面的最终审查以确保上线发布质量。本计划基于对代码库的深度探索，识别出关键问题和改进方向。

## 当前状态摘要

| 审查维度 | 当前状态 | 目标状态 | 风险等级 |
|---------|---------|---------|---------|
| 功能完整性 | 核心功能完成，5个功能开发中 | 全部完成 | 🟡 中 |
| 测试覆盖率 | ~60% | 80% | 🔴 高 |
| 代码规范 | 无 ESLint/Prettier | 配置并执行 | 🔴 高 |
| 类型安全 | 106处 `any` 类型 | 最小化使用 | 🟡 中 |
| 部署文档 | 缺失 | 完整 | 🟡 中 |
| CI/CD | 完全缺失 | Gitea Actions 配置 | 🔴 高 |

---

## 审查任务清单

### 阶段 1：功能完整性审查

#### 1.1 核心功能验证
- [ ] 运行 E2E 测试套件：`cd desktop && pnpm test:e2e`
- [ ] 验证 11 个 Hand 配置文件完整性
- [ ] 验证 68 个技能定义文件
- [ ] 检查 19 个 Store 初始化状态

#### 1.2 边缘情况测试
- [ ] 聊天系统：空消息、超长消息、特殊字符、网络断开
- [ ] Hands 系统：无效 ID、缺少参数、依赖未满足、超时处理
- [ ] 配置系统：无效 TOML、环境变量缺失、路径不存在

#### 1.3 开发中功能 (必须完成)
以下 5 个开发中功能**必须在上线前完成**：
- [ ] 批量调度功能 (`AutomationPanel.tsx:365`)
- [ ] 工作流创建向导 (`AutomationPanel.tsx:416`)
- [ ] Cron 调度管理 (`AutomationPanel.tsx:444`)
- [ ] 课堂导出功能 (`ClassroomPreviewer.tsx:353`)
- [ ] 课堂预览功能 (`PipelineResultPreview.tsx:223`)

---

### 阶段 2：代码质量审查

#### 2.1 配置 ESLint + Prettier

**关键文件：**
- `g:/ZClaw_openfang/desktop/eslint.config.js` (新建)
- `g:/ZClaw_openfang/desktop/prettier.config.js` (新建)

**执行步骤：**
```bash
cd desktop
pnpm add -D eslint typescript-eslint eslint-plugin-react eslint-plugin-react-hooks prettier prettier-plugin-tailwindcss
# 创建配置文件后执行
pnpm eslint src/ --fix
pnpm prettier --write "src/**/*.{ts,tsx,css}"
```

#### 2.2 清理 `any` 类型

**高优先级文件：**
| 文件 | `any` 次数 | 路径 |
|------|-----------|------|
| gateway-client.ts | 31 | `desktop/src/lib/gateway-client.ts` |
| gateway-api.ts | 26 | `desktop/src/lib/gateway-api.ts` |
| gatewayStore.ts | 10 | `desktop/src/store/gatewayStore.ts` |
| PropertyPanel.tsx | 13 | `desktop/src/components/WorkflowBuilder/PropertyPanel.tsx` |

**修复方案：** 使用 `unknown` + 类型守卫替代 `any`

#### 2.3 静态分析
```bash
# TypeScript 检查
cd desktop && pnpm tsc --noEmit

# Rust 检查
cd desktop/src-tauri && cargo clippy -- -D warnings
```

---

### 阶段 3：测试验证

#### 3.1 提升测试覆盖率 (60% → 80%)

**需补充测试的文件：**
| 文件 | 路径 |
|------|------|
| gateway-client.test.ts | `desktop/tests/lib/` |
| kernel-client.test.ts | `desktop/tests/lib/` |
| chatStore.test.ts | `desktop/tests/store/` |

**执行步骤：**
```bash
cd desktop
pnpm vitest run --coverage
# 查看 coverage/lcov-report/index.html 识别低覆盖文件
```

#### 3.2 性能测试
| 指标 | 目标值 |
|------|--------|
| 应用启动时间 | < 3s |
| 首屏渲染 | < 1s |
| 消息发送延迟 | < 100ms |
| 流式首字节 | < 500ms |
| 内存占用 | < 500MB |

#### 3.3 安全测试
- [ ] 搜索敏感数据泄露：`grep -rn "console.log.*token\|console.log.*key"`
- [ ] 检查硬编码密钥
- [ ] 验证 API Key 存储使用 OS keyring
- [ ] 检查 WebSocket 认证逻辑

---

### 阶段 4：部署准备

#### 4.1 创建部署文档

**需创建的文档：**
- `docs/deployment/README.md` - 部署概述
- `docs/deployment/windows.md` - Windows 安装指南
- `docs/deployment/requirements.md` - 系统要求

#### 4.2 配置 Gitea CI/CD

**关键文件：**
- `g:/ZClaw_openfang/.gitea/workflows/ci.yml` (新建)
- `g:/ZClaw_openfang/.gitea/workflows/release.yml` (新建)

**Gitea Actions CI 流程：**
```yaml
# .gitea/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cd desktop && pnpm install
      - run: cd desktop && pnpm tsc --noEmit
      - run: cd desktop && pnpm eslint src/

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cd desktop && pnpm install
      - run: cd desktop && pnpm test:coverage

  build:
    runs-on: windows-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - run: cd desktop && pnpm install
      - run: cd desktop && pnpm tauri:build
```

**配置步骤：**
1. 在 Gitea 仓库设置中启用 Actions
2. 配置 Runner（Windows 用于构建）
3. 创建 workflow 文件

#### 4.3 代码签名配置
> **决策：不需要代码签名**（应用不分发到公共渠道）

---

### 阶段 5：文档与合规

#### 5.1 文档完整性
| 文档 | 状态 | 操作 |
|------|------|------|
| 用户手册 | ✅ 存在 | 更新版本号 |
| 开发文档 | ✅ 存在 | 无需更新 |
| 故障排查 | ✅ 完整 | 无需更新 |
| 部署文档 | ❌ 缺失 | 需创建 |
| 变更日志 | ❌ 缺失 | 需创建 |

#### 5.2 合规性检查
- [ ] 创建隐私政策
- [ ] 创建用户协议
- [ ] 第三方依赖声明
- [ ] 确认开源许可证合规

---

### 阶段 6：上线准备

#### 6.1 应急预案
- 服务启动失败 → 检查端口占用，重启服务
- WebSocket 断开 → 自动重连（已实现）
- LLM API 限流 → 降级到备用模型
- 数据库损坏 → 从备份恢复

#### 6.2 监控配置
- 应用启动时间监控
- API 响应时间监控
- 错误率监控

#### 6.3 备份策略
- 用户配置：每次修改时备份
- 会话数据：每小时备份
- 记忆向量：每小时备份

---

## 执行优先级

| 优先级 | 任务 | 预估时间 |
|--------|------|---------|
| P0 | 完成 5 个开发中功能 | 3 天 |
| P0 | E2E 测试验证 | 0.5 天 |
| P0 | ESLint/Prettier 配置 | 0.5 天 |
| P0 | 高优先级 `any` 类型清理 | 1 天 |
| P1 | 测试覆盖率提升 | 2 天 |
| P1 | 部署文档编写 | 1 天 |
| P1 | Gitea CI/CD 配置 | 1 天 |
| P2 | 安全测试 | 1 天 |
| P2 | 性能测试 | 0.5 天 |

**总预估：10-11 天**

---

## 验证方法

1. **功能验证**：运行 `pnpm test:e2e`，确保 74 个 E2E 测试全部通过
2. **代码质量**：运行 `pnpm tsc --noEmit` 和 `pnpm eslint src/`，无错误
3. **测试覆盖**：运行 `pnpm test:coverage`，覆盖率 ≥ 80%
4. **构建验证**：运行 `pnpm tauri:build`，生成可安装的 NSIS 包

---

## 关键文件路径

| 类别 | 文件路径 |
|------|---------|
| 核心客户端 | `desktop/src/lib/gateway-client.ts` |
| API 定义 | `desktop/src/lib/gateway-api.ts` |
| Tauri 后端 | `desktop/src-tauri/src/lib.rs` |
| 测试配置 | `desktop/vitest.config.ts` |
| E2E 测试 | `desktop/tests/e2e/specs/` |
| 故障排查文档 | `docs/knowledge-base/troubleshooting.md` |