zclaw_openfang/docs/features/QA_REVIEW_V1.md

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%)，持续补充测试达到目标