d0c6319fc1
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
style: 格式化代码文件并修复样式问题 docs: 新增部署文档和系统要求文档 test: 更新测试截图和覆盖率报告 refactor: 重构SchedulerPanel加载状态逻辑 ci: 添加lint和format脚本到package.json build: 更新依赖项并添加开发工具 chore: 添加验证报告和上线审查计划
252 lines
6.9 KiB
Markdown
252 lines
6.9 KiB
Markdown
# 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` |
|