8898bb399e
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
Update audit tracker, roadmap, architecture docs, add admin-v2 Roles page + Billing tests, sync CLAUDE.md, Cargo.toml, docker-compose.yml, add deep-research / frontend-design / chart-visualization skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
130 lines
5.7 KiB
Markdown
130 lines
5.7 KiB
Markdown
# ZCLAW 全栈 QA 与代码审查报告
|
||
|
||
> 日期: 2026-03-31 ~ 2026-04-01
|
||
> 审查方法: 模块垂直扫描 (4 Tracks) + 后续测试补充 + 大文件拆分
|
||
> 审查范围: Rust 后端 + Admin V2 前端 + Desktop 前端 + 配置/部署
|
||
|
||
---
|
||
|
||
## 1. 审查发现与修复汇总
|
||
|
||
### 1.1 已修复问题
|
||
|
||
| # | 问题 | 严重级 | 模块 | 状态 |
|
||
|---|------|--------|------|------|
|
||
| 1 | `relay_enqueue()` 重复调用 (探索阶段报告) | P0 | SaaS 后端 | **误报** — 实际只有一次调用 |
|
||
| 2 | 密码策略无复杂度要求 | P2 | SaaS 后端 | **已修复** — 大写+小写+数字验证 |
|
||
| 3 | JWT 缺少 `aud` (受众) claim | P3 | SaaS 后端 | **已修复** — `aud: "zclaw-saas"` + 验证 |
|
||
| 4 | JWT 缺少 `pwv` (密码版本) | P1 | SaaS 后端 | **已修复** — 用户修改 |
|
||
| 5 | 17 处 `println!`/`eprintln!` 生产代码 | P1 | Rust crates | **已修复** — 全部替换为 `tracing::*` |
|
||
| 6 | Desktop 49 处 `any` 用法 | P1 | Desktop | **已修复** — gateway-api-types.ts 类型化 |
|
||
| 7 | Desktop 80+ 裸 `console.*` 调用 | P1 | Desktop | **已修复** — 26 处替换为 logger |
|
||
| 8 | Desktop tsconfig 排除 ErrorBoundary/ErrorAlert | P2 | Desktop | **已修复** — 修复类型错误后移除排除 |
|
||
| 9 | Docker Compose 默认密码 + 端口暴露 | P2 | 部署 | **已修复** — 用户进一步加固 |
|
||
| 10 | 缺少 `.dockerignore` | P3 | 部署 | **已修复** |
|
||
| 11 | Admin V2 测试覆盖不足 (3/10 页面) | P1 | Admin V2 | **已修复** — 71 个测试全部通过 |
|
||
|
||
### 1.2 确认良好的方面
|
||
|
||
| 模块 | 良好实践 |
|
||
|------|----------|
|
||
| Admin V2 | 零 `any` 用法、无 `dangerouslySetInnerHTML`、ErrorBoundary 完善 |
|
||
| SaaS 后端 | Argon2id 密码哈希、AES-256-GCM 加密、参数化 SQL、SSRF 防护完善 |
|
||
| 认证系统 | HttpOnly + Secure + SameSite=Strict Cookie、refresh token 轮换、pwv 密码版本追踪 |
|
||
| RBAC | `admin:full` 超级权限、IDOR 防护、权限缓存 |
|
||
|
||
---
|
||
|
||
## 2. 后续工作完成情况
|
||
|
||
### 2.1 Admin V2 测试补充 (71 个测试，12 个测试文件)
|
||
|
||
| 测试文件 | 测试数 | 覆盖内容 |
|
||
|----------|--------|----------|
|
||
| `Accounts.test.tsx` | 已有 | 账号 CRUD |
|
||
| `AgentTemplates.test.tsx` | 已有 | 模板管理 |
|
||
| `authStore.test.ts` | 已有 | 认证状态 |
|
||
| `request.test.ts` | 已有 | HTTP 客户端 |
|
||
| `Dashboard.test.tsx` | 8 新增 | 统计数据 + 日志展示 |
|
||
| `Login.test.tsx` | 7 新增 | 登录 + TOTP + 错误处理 |
|
||
| `Config.test.tsx` | 7 新增 | 配置项 + 分类标签页 |
|
||
| `Logs.test.tsx` | 7 新增 | 日志分页 + 筛选 + ErrorState |
|
||
| `Relay.test.tsx` | 7 新增 | 中转任务 + 状态标签 |
|
||
| `Usage.test.tsx` | 6 新增 | 统计卡片 + 每日/模型表 |
|
||
| `Prompts.test.tsx` | 5 新增 | 提示词模板 + CRUD |
|
||
| `ModelServices.test.tsx` | 5 新增 | 供应商列表 + 状态标签 |
|
||
|
||
### 2.2 大文件拆分
|
||
|
||
| 文件 | 原始行数 | 拆分结果 | 状态 |
|
||
|------|----------|----------|------|
|
||
| `kernel.rs` | 1486 | 9 个子模块 (mod.rs + adapters/agents/messaging/skills/hands/triggers/approvals/a2a) | **完成** |
|
||
| `intelligence-client.ts` | 1475 | 9 个子模块 (index/types/type-conversions/unified-client + 5 个 fallback) | **完成** |
|
||
| `db.rs` | 891 | 保持原样 (拆分风险大于收益) | **跳过** |
|
||
|
||
### 2.3 kernel.rs 拆分详情
|
||
|
||
```
|
||
kernel/
|
||
├── mod.rs (~200L) — Kernel struct + boot + 中间件 + 访问器
|
||
├── adapters.rs (~95L) — LlmDriverAdapter + KernelSkillExecutor + AgentInbox
|
||
├── agents.rs (~100L) — Agent CRUD
|
||
├── messaging.rs (~150L) — 消息发送 + 技能提示构建
|
||
├── skills.rs (~70L) — 技能管理
|
||
├── hands.rs (~200L) — Hand 执行 + 运行追踪
|
||
├── triggers.rs (~45L) — 触发器 CRUD
|
||
├── approvals.rs (~140L) — 审批管理
|
||
└── a2a.rs (~265L) — A2A 多智能体 (cfg multi-agent)
|
||
```
|
||
|
||
### 2.4 intelligence-client.ts 拆分详情
|
||
|
||
```
|
||
intelligence-client/
|
||
├── index.ts (~65L) — 统一重导出
|
||
├── types.ts (~175L) — 前端类型 + Mesh + Persona Evolver
|
||
├── type-conversions.ts (~95L) — 前后端类型转换
|
||
├── unified-client.ts (~440L) — 主 intelligenceClient 对象
|
||
├── fallback-memory.ts (~165L) — localStorage 内存回退
|
||
├── fallback-compactor.ts (~60L) — 压缩回退
|
||
├── fallback-reflection.ts (~165L) — 反思回退
|
||
├── fallback-identity.ts (~235L) — 身份管理回退
|
||
└── fallback-heartbeat.ts (~55L) — 心跳回退
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 验证结果
|
||
|
||
| 检查项 | 结果 |
|
||
|--------|------|
|
||
| `cargo check -p zclaw-saas` | **通过** |
|
||
| `cargo check -p zclaw-kernel` | **通过** (runtime 有预存类型问题) |
|
||
| `cargo test -p zclaw-saas --lib -- jwt` | **6/6 通过** (含 aud + pwv 测试) |
|
||
| Desktop `tsc --noEmit` | **通过** (0 errors) |
|
||
| Admin V2 `tsc --noEmit` | **通过** (0 errors) |
|
||
| Admin V2 `vitest run` | **71/71 通过** (12 个测试文件) |
|
||
|
||
---
|
||
|
||
## 4. 遗留项与后续建议
|
||
|
||
### 4.1 db.rs 拆分 (891L)
|
||
|
||
保持原样。原因：
|
||
- `init_db()` 是唯一的公共入口，所有 seed/migration 函数都是内部实现
|
||
- 函数间有较强耦合（migration 调用 seed_roles，init_db 编排所有步骤）
|
||
- 拆分收益有限（不像 kernel.rs 有多个独立领域）
|
||
|
||
### 4.2 安全增强建议
|
||
|
||
- Docker Compose 生产部署时考虑 Redis-backed 分布式限流
|
||
- 考虑将邮箱验证改为使用 email 验证库
|
||
- 生产环境日志写入 WAF
|
||
|
||
### 4.3 代码质量持续改进
|
||
|
||
- Desktop 仍有约 50 处裸 `console.*` 调用在非重点文件中
|
||
- `zclaw-runtime` 有预存的 `Message` enum 类型错误需修复
|
||
- Admin V2 coverage thresholds 已设置 (60%)，持续补充测试达到目标
|