test: 测试体系全面优化，修复 Windows SQLite EBUSY 和前端产品缺陷

测试基础设施
- 统一 SQLite 测试 DB/临时目录 helper（tests/helpers.ts），支持 Windows EBUSY 重试清理
- 测试库使用 PRAGMA journal_mode=DELETE 避免 WAL 句柄延迟
- 路由 handler 测试改用 createMigratedMemoryTestDatabase 避免 File DB 锁
- SQLite 聚焦 --rerun-each=20 全部通过（720 pass）

后端测试补强
- 新增 tests/server/app.test.ts 真实 startServer 集成测试
- 覆盖 /api/meta、项目 CRUD、错误路径、静态 fallback、安全 header
- bootstrap/logger 测试捕获预期输出，消除测试噪音

前端测试补强
- 移除 .ant-* 内部类名依赖，改为角色/文本/导航/请求契约断言
- 项目页补充搜索、Tab 切换、表单、表格操作、错误反馈行为测试
- 新增 hooks（use-theme-preference、use-sidebar-collapsed、use-projects）纯逻辑测试
- 新增 ErrorBoundary 错误展示和刷新按钮测试
- 新增搜索清空行为测试
- 测试 setup 过滤 antd/rc-trigger NaN height warning

产品修复（测试暴露）
- 修复 ProjectToolbar 搜索框无法输入（新增 draftKeyword 状态）
- 加固 ProjectFormModal 表单字段同步（useEffect 替代不可靠的 afterOpenChange）
- 清理 ProjectFormModal 冗余 afterOpenChange 同步逻辑

重构与合规
- ProjectContext 拆分为三文件满足 React Fast Refresh 规则
- use-projects.ts 导出内部 helper 函数供测试验证
- scripts/build.ts 提取纯生成函数供测试使用，修复构建步骤日志编号
- 修复 build 测试覆盖真实生成逻辑

文档同步
- 更新后端/前端/开发文档测试规范、质量门禁和 helper 使用说明

docs/development/README.md

@@ -41,12 +41,13 @@
 
 代码变更必须按影响范围执行验证。
 
-| 变更类型                   | 必跑命令                                                  |
-| -------------------------- | --------------------------------------------------------- |
-| 常规代码变更               | `bun run check`                                           |
-| 构建、部署、前后端集成变更 | `bun run verify`                                          |
-| 配置 schema 变化           | `bun run schema`、`bun run schema:check`、`bun run check` |
-| 仅文档变更                 | 检查链接、索引和文档归属一致性                            |
+| 变更类型                   | 必跑命令                                                      |
+| -------------------------- | ------------------------------------------------------------- |
+| 常规代码变更               | `bun run check`                                               |
+| 构建、部署、前后端集成变更 | `bun run verify`                                              |
+| 配置 schema 变化           | `bun run schema`、`bun run schema:check`、`bun run check`     |
+| SQLite 测试基础设施变化    | 相关单文件测试 + SQLite 聚焦 `--rerun-each` + `bun run check` |
+| 仅文档变更                 | 检查链接、索引和文档归属一致性                                |
 
 正式提交或影响构建产物时优先运行 `bun run verify`。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。
 

docs/development/backend.md

@@ -119,6 +119,13 @@ bun run version:set     # 显式设置版本号
 | 配置 schema        | schema 导出、合法/非法配置        |
 | helpers/middleware | 单元测试                          |
 
+后端测试约定：
+
+- API 路由集成测试必须通过真实 `startServer` 覆盖路由注册、HTTP method、fallback、响应 header 和核心错误路径。
+- SQLite 相关测试必须复用 `tests/helpers.ts` 中的测试数据库 helper，不要在测试文件内分散实现临时目录清理或直接裸用 `rmSync(dir, { recursive: true })`。
+- DAO 和路由边界测试应优先使用真实 migration 初始化测试库，只有 migration 执行器单测可以使用最小 fake migration。
+- logger/bootstrap 中预期的 fallback 输出必须在测试中捕获并断言，正常通过的测试不应污染 stdout/stderr。
+
 ## 更新触发条件
 
 修改后端 API、共享类型、配置契约、日志模块、版本管理或后端测试规范时，必须更新本文档。

docs/development/frontend.md

@@ -157,6 +157,9 @@ Workbench 项目上下文通过 `ProjectContext` 提供，在 `WorkbenchProjectG
 - 组件测试环境由 tests/setup.ts 和 bunfig.toml preload 提供
 - 断言优先基于用户可见文本、role、按钮和交互结果，不依赖 `.ant-*` 内部类名。
 - 对 antd 组件只断言本项目传入的可观察行为或配置结果，避免把 antd 内部 DOM 结构当作稳定契约。
+- fetch mock、路由、QueryClientProvider 等系统边界优先复用 tests/web/test-utils.tsx，避免在每个测试文件重复安装 `window.fetch`。
+- 项目页这类数据驱动页面至少覆盖请求 URL/query、method/body、成功后的用户可见结果，以及关键错误路径或失败后状态。
+- ErrorBoundary、hooks 纯逻辑和 fetch request helper 应使用单元测试覆盖异常回退，页面测试只保留真实用户路径。
 
 ## 更新触发条件