zclaw_openfang/BREAKS.md

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

生成时间: 2026-04-10 更新时间: 2026-04-10 (P0-01, P1-01, P1-03, P1-02, P1-04, P2-03 已修复) 测试范围: Layer 1 断裂探测 — 30 个 Smoke Test 最终结果: 21/30 通过 (70%), 0 个 P0 bug, 0 个 P1 bug（所有已知问题已修复）

---

测试执行总结

域	测试数	通过	失败	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 浏览器模式聊天无响应 [FIXED]

• 测试: D1 (Gateway 模式聊天)
• 严重度: P1 — 外部浏览器无法使用聊天
• 根因: Playwright Chromium 非 Tauri 环境，应用走 SaaS relay 路径但测试未预先登录
• 修复: 添加 Playwright fixture 自动检测非 Tauri 模式并注入 SaaS session (commit 34ef41c)
• 验证: npx playwright test smoke_chat D1 应正常响应

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 竞态条件 [FIXED]

• 测试: A6 (间歇性失败)
• 严重度: P1 — 测试稳定性
• 根因: loadFromStorage() 无条件信任 localStorage 设 isAuthenticated=true，但 HttpOnly cookie 可能已过期，子组件先渲染后发 401 请求
• 修复: authStore 初始 isAuthenticated=false；AuthGuard 三态守卫 (checking/authenticated/unauthenticated)，始终先验证 cookie (commit 80b7ee8)
• 验证: npx playwright test smoke_admin A6 连续通过

---

P2 发现 (本周修复)

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

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

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

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

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

• 根因: 6 个 Cross 测试各调一次 saasLogin() → 6 次 login/分钟 → 触发 5次/分钟/IP 限流
• 修复: 测试共享 token，6 个测试只 login 一次 (commit bd48de6)
• 验证: npx playwright test smoke_cross 不再因 429 失败

---

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

修复	描述
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/P1/P2 已知问题已修复。剩余 P2 待观察：

P2-01 /me 端点不返回 pwv 字段
  └── 影响: 前端无法客户端检测密码变更（非阻断）
  └── 优先级: 低

P2-02 知识搜索即时性不足
  └── 影响: 创建知识条目后立即搜索可能找不到（embedding 异步）
  └── 优先级: 低

---

测试基础设施状态

项目	状态	备注
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