zclaw_openfang/plans/bright-cuddling-wand.md

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 (新建)

执行步骤：

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 静态分析

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

执行步骤：

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 流程：

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