zclaw_openfang/BREAKS.md

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

生成时间: 2026-04-10 测试范围: Layer 1 断裂探测 — 30 个 Smoke Test 最终结果: 19/30 通过 (63%), 2 个 P0 bug, 3 个 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: 账户锁定未强制执行

• 测试: S2 (s2_account_lockout)
• 严重度: P0 — 安全漏洞
• 断裂描述: 5 次错误密码后 locked_until 正确写入 DB，但登录时不检查此字段，正确密码仍可登录
• 根因: auth/routes.rs login handler 只检查 failed_login_attempts >= 5 但不检查 locked_until > now()
• 证据:

  locked_until = Some(2026-04-10T12:00:00Z)  ← DB 中已设置
  POST /auth/login (correct password) → 200 OK  ← 应该是 401/403
  

• 修复: login handler 增加 if locked_until > now() { return 403 } 检查
• 影响: 暴力破解防护失效

---

P1 断裂 (当天修复)

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

• 测试: S1 (s1_auth_full_lifecycle)
• 严重度: P1 — 安全缺陷
• 断裂描述: POST /auth/logout 后，refresh token 仍可用于获取新 access token
• 根因: logout handler 只清除 HttpOnly cookie，未在 DB 中撤销 refresh token
• 证据:

  POST /auth/logout → 204 No Content
  POST /auth/refresh (old token) → 200 OK + new tokens  ← 应该是 401
  

• 修复: logout 时将 refresh token 的 revoked_at 设为当前时间

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

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

P1-03: Provider 创建 API 必需 display_name

• 测试: A2 (Provider CRUD)
• 严重度: P1 — API 兼容性
• 断裂描述: POST /api/v1/providers 要求 display_name 字段，否则返回 422
• 证据: 422 — missing field 'display_name'
• 修复: 将 display_name 设为可选（用 name 作为 fallback）

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