lanyuanxiaoyao
2ea4bd4410
测试基础设施 - 统一 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 使用说明
Alfred·阿福 文档
本文档是 Alfred·阿福 的文档路由入口。AI 工具和开发者应先阅读本文件判断本次任务需要读取和更新哪些专题文档，再按任务类型读取最小必要上下文。
目录索引
docs/
README.md
development/
README.md
architecture.md
backend.md
frontend.md
release.md
user/
README.md
usage.md
config.md
deploy.md
troubleshoot.md
prompts/
README.md
prompt-smart-merge.md
prompt-proposal-review.md
prompt-apply-review.md
docs/prompts/ 是提示词资产目录，不属于常规开发流程和用户使用文档。代码、配置或部署变更不需要更新该目录，除非任务明确要求维护提示词资产。
入口文档
| 入口 | 定位 |
|---|---|
| 项目 README | 项目整体介绍、快速开始、文档引导 |
| 开发文档 | 开发入口、全局规则、常用命令、质量门禁 |
| 用户文档 | 使用、配置、部署、排障入口 |
按任务阅读路径
| 任务 | 必读文档 |
|---|---|
| 修改项目介绍或快速开始 | 项目 README、本文档 |
| 修改开发流程、质量门禁或工程规则 | 开发文档、本文档、OpenSpec 配置 |
| 修改架构边界或启动流程 | 开发文档、架构与边界 |
| 修改后端 API、配置加载、日志 | 开发文档、后端开发 |
| 修改前端 | 开发文档、前端开发 |
| 修改构建、脚本、发布 | 构建与发布、部署文档 |
| 修改配置 schema | 配置文件、后端开发 |
| 修改文档规则或文档目录结构 | 本文档、OpenSpec 配置 |
| 首次安装或配置 | 快速开始、配置文件 |
| 排查运行或构建问题 | 故障排查 |
文档归属矩阵
| 变更类型 | 默认更新位置 |
|---|---|
| 项目定位、核心能力、快速开始、顶层文档导航 | README.md |
| 文档路由、文档更新规则、文档归属矩阵 | docs/README.md、openspec/config.yaml |
| 开发入口、常用命令、质量门禁、全局工程规则、OpenSpec 约定 | docs/development/README.md |
| 架构边界、启动流程、运行时流程、前后端边界 | docs/development/architecture.md |
| 后端 API、配置加载、logger、helpers、类型规范、后端测试 | docs/development/backend.md |
| 前端技术栈、组件、样式、数据层、前端测试 | docs/development/frontend.md |
| 构建、发布、脚本、前后端静态资源集成 | docs/development/release.md |
| 快速开始、安装配置 | docs/user/usage.md |
| YAML 配置、变量语法、server/storage/logging、JSON Schema | docs/user/config.md |
| 生产构建、可执行文件运行、运行时配置 | docs/user/deploy.md |
| 常见运行问题、配置校验、变量解析、构建失败 | docs/user/troubleshoot.md |
development 文档如何更新
开发文档解释"如何实现和维护"。代码变更影响开发者理解、开发流程、测试方式或架构边界时，必须更新 docs/development/ 对应文档。
- 全局规则、常用命令、质量门禁、目录边界、OpenSpec 约定更新到
docs/development/README.md。 - 架构图、启动链路、运行时流程、前后端边界更新到
docs/development/architecture.md。 - 后端 API、配置加载、logger、helpers、类型规范和后端测试规范更新到
docs/development/backend.md。 - 前端技术栈、组件边界、数据流、样式规则和前端测试规范更新到
docs/development/frontend.md。 - 构建、脚本和发布验证更新到
docs/development/release.md。 - 不新增"杂项"开发文档；优先把内容放入上述最贴近的专题，确需新增专题时先更新本文档和
openspec/config.yaml。
user 文档如何更新
用户文档解释"如何使用"和"用户能观察到什么"。变更影响使用方式、配置、部署或运行行为时，必须更新 docs/user/ 对应文档。
- 安装、配置、快速开始更新到
docs/user/usage.md。 - 配置结构、变量语法、server/storage/logging 字段更新到
docs/user/config.md。 - 生产构建、可执行文件运行、运行时依赖更新到
docs/user/deploy.md。 - 常见错误和排查路径更新到
docs/user/troubleshoot.md。 - 用户文档避免解释内部实现细节，需要实现细节时链接到
docs/development/。
文档影响分析
每次代码变更都必须执行文档影响分析。
代码或配置变更
-> 用户能感知吗？更新 docs/user/ 或 README.md
-> 开发者需要知道吗？更新 docs/development/
-> 文档规则变化吗？更新 docs/README.md 和 openspec/config.yaml
-> 都不是？收尾说明写明无需更新文档及原因
同一事实只在最贴近读者的文档中完整展开，其他文档使用链接引用。根目录 README 保持轻量，不承载完整配置参考或实现教程。
收尾说明示例
文档影响分析：本次修改了后端日志配置字段，已更新 docs/development/backend.md 和 docs/user/config.md。
无需更新文档时：
文档影响分析：本次仅调整内部测试 helper，未改变用户可见行为、配置、架构边界或开发流程，因此无需更新文档。