zclaw_openfang/BREAKS.md

ZCLAW 断裂探测报告 (BREAKS.md)

生成时间: 2026-04-10 更新时间: 2026-04-10 (P0-01, P1-01, P1-03 已修复并验证) 测试范围: Layer 1 断裂探测 — 30 个 Smoke Test 最终结果: 21/30 通过 (70%), 0 个 P0 bug, 1 个 P1 bug (P1-02 Desktop 浏览器聊天)

---

测试执行总结

域	测试数	通过	失败	Skip	备注
SaaS API (S1-S6)	6	5	0	1	S3 需 LLM API Key 已 SKIP
Admin V2 (A1-A6)	6	5	1	0	A6 间歇性失败 (AuthGuard 竞态)
Desktop Chat (D1-D6)	6	3	1	2	D1 聊天无响应; D2/D3 非 Tauri 环境 SKIP
Desktop Feature (F1-F6)	6	6	0	0	全部通过 (探测模式)
Cross-System (X1-X6)	6	2	4	0	4个因登录限流 429 失败
总计	30	21	6	3

---

P0 断裂 (立即修复)

P0-01: 账户锁定未强制执行 [FIXED]

• 测试: S2 (s2_account_lockout)
• 严重度: P0 — 安全漏洞
• 修复: 使用 SQL 层 locked_until > NOW() 比较替代 broken 的 RFC3339 文本解析 (commit b0e6654)
• 验证: cargo test -p zclaw-saas --test smoke_saas -- s2 PASS

---

P1 断裂 (当天修复)

P1-01: Refresh Token 注销后仍有效 [FIXED]

• 测试: S1 (s1_auth_full_lifecycle)
• 严重度: P1 — 安全缺陷
• 修复: logout handler 改为接受 JSON body (optional refresh_token)，撤销账户所有 refresh token (commit b0e6654)
• 验证: cargo test -p zclaw-saas --test smoke_saas -- s1 PASS

P1-02: Desktop 浏览器模式聊天无响应

• 测试: D1 (Gateway 模式聊天)
• 严重度: P1 — 外部浏览器无法使用聊天
• 断裂描述: 在 Playwright Chromium 中发送聊天消息后，无 assistant 响应气泡出现
• 根因: 可能是 Desktop Store 检测到非 Tauri 环境，__ZCLAW_STORES__ 未暴露给外部浏览器
• 证据: sendMessage 成功填写输入框并发送，但 30s 超时内无响应

P1-03: Provider 创建 API 必需 display_name [FIXED]

• 测试: A2 (Provider CRUD)
• 严重度: P1 — API 兼容性
• 修复: display_name 改为 Option<String>，缺失时 fallback 到 name (commit b0e6654)
• 验证: cargo test -p zclaw-saas --test smoke_saas -- s3 PASS

P1-04: Admin V2 AuthGuard 竞态条件

• 测试: A6 (间歇性失败)
• 严重度: P1 — 测试稳定性
• 断裂描述: 通过 API 设置 localStorage 认证后，导航到页面时 AuthGuard 有时未检测到登录状态

---

P2 发现 (本周修复)

P2-01: /me 端点不返回 pwv 字段

• JWT claims 含 pwv（password_version），但 GET /me 不返回 → 前端无法客户端检测密码变更

P2-02: 知识搜索即时性不足

• 创建知识条目后立即搜索可能找不到（embedding 异步生成中）

P2-03: 测试登录限流冲突

• Cross 测试因 429 (5次/分钟/IP) 失败 → 需要共享 token 或串行执行

---

已修复 (本次探测中修复)

修复	描述
P0-02 Desktop CSS	@import "@tailwindcss/typography" → @plugin "@tailwindcss/typography" (Tailwind v4 语法)
Admin 凭据	testadmin/Admin123456 → admin/admin123 (来自 .env)
Dashboard 端点	/dashboard/stats → /stats/dashboard
Provider display_name	添加缺失的 display_name 字段

---

已通过测试 (21/30)

ID	测试名称	验证内容
S1	认证闭环	register→login→/me→refresh→logout
S2	账户锁定	5次失败→locked_until设置→DB验证
S4	权限矩阵	super_admin 200 + user 403 + 未认证 401
S5	计费闭环	dashboard stats + billing usage + plans
S6	知识检索	category→item→search→DB验证
A1	登录→Dashboard	表单登录→统计卡片渲染
A2	Provider CRUD	API 创建+页面可见
A3	Account 管理	表格加载、角色列可见
A4	知识管理	分类→条目→页面加载
A5	角色权限	页面加载+API验证
D4	流取消	取消按钮点击+状态验证
D5	离线队列	断网→发消息→恢复→重连
D6	错误恢复	无效模型→错误检测→恢复
F1	Agent 生命周期	Store 检查+UI 探测
F2	Hands 触发	面板加载+Store 检查
F3	Pipeline 执行	模板列表加载
F4	记忆闭环	Store 检查+面板探测
F5	管家路由	ButlerRouter 分类检查
F6	技能发现	Store/Tauri 检查
X5	TOTP 流程	setup 端点调用
X6	计费查询	usage + plans 结构验证

---

修复优先级路线图

P0-01 账户锁定未强制 (安全漏洞)
  └── 修复 auth/routes.rs login handler
  └── 验证: cargo test -p zclaw-saas --test smoke_saas -- s2

P1-01 Refresh Token 注销后仍有效
  └── 修复 logout handler 撤销 refresh token
  └── 验证: cargo test -p zclaw-saas --test smoke_saas -- s1

P1-02 Desktop 浏览器聊天无响应
  └── 调查 __ZCLAW_STORES__ 是否暴露给外部浏览器
  └── 验证: npx playwright test smoke_chat --config tests/e2e/playwright.config.ts

---

测试基础设施状态

项目	状态	备注
SaaS 集成测试框架	✅ 可用	crates/zclaw-saas/tests/common/mod.rs
Admin V2 Playwright	✅ 可用	Chromium 147 + 正确凭据
Desktop Playwright	✅ 可用	CSS 已修复
PostgreSQL 测试 DB	✅ 运行中	localhost:5432/zclaw
SaaS Server	✅ 运行中	localhost:8080
Admin V2 dev server	✅ 运行中	localhost:5173
Desktop (Tauri dev)	✅ 可用	localhost:1420

验证命令

# SaaS (需 PostgreSQL)
cargo test -p zclaw-saas --test smoke_saas -- --test-threads=1

# Admin V2
cd admin-v2 && npx playwright test smoke_admin

# Desktop
cd desktop && npx playwright test smoke_chat smoke_features --config tests/e2e/playwright.config.ts

# Cross (需先等 1 分钟让限流重置)
cd desktop && npx playwright test smoke_cross --config tests/e2e/playwright.config.ts