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 使用说明
111 lines
7.4 KiB
Markdown
111 lines
7.4 KiB
Markdown
# 开发文档
|
||
|
||
本文档是 alfred 的开发入口。AI 工具和开发者应先阅读 [`../README.md`](../README.md) 判断文档归属，再阅读本文和最小必要专题。
|
||
|
||
适用场景：修改源码、测试、构建脚本、开发流程、架构边界或项目工程规则。
|
||
|
||
## 专题索引
|
||
|
||
| 文档 | 内容 |
|
||
| ---------------------------------- | ---------------------------------------------------------------- |
|
||
| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 |
|
||
| [backend.md](backend.md) | 后端库优先级、API 路由、共享工具、类型规范、配置契约、日志、测试 |
|
||
| [frontend.md](frontend.md) | React、Ant Design、TanStack Query、组件、样式和前端测试规范 |
|
||
| [release.md](release.md) | 开发服务、前后端集成、构建、脚本、环境变量 |
|
||
| [../README.md](../README.md) | 文档路由、文档归属矩阵、development/user 文档更新规则 |
|
||
|
||
## 常用命令
|
||
|
||
| 命令 | 说明 |
|
||
| -------------------------------- | -------------------------------------- |
|
||
| `bun install` | 安装依赖 |
|
||
| `bun run dev config.yaml` | 启动双进程开发环境 |
|
||
| `bun run dev:server config.yaml` | 仅启动后端 API server |
|
||
| `bun run dev:web` | 仅启动 Vite dev server |
|
||
| `bun run schema` | 生成 config.schema.json |
|
||
| `bun run schema:check` | 检查导出 schema 是否同步 |
|
||
| `bun run typecheck` | TypeScript 类型检查 |
|
||
| `bun run lint` | ESLint 和 Prettier 格式检查 |
|
||
| `bun run format` | Prettier 自动格式化 |
|
||
| `bun test` | 运行全部测试 |
|
||
| `bun run check` | schema:check + typecheck + lint + test |
|
||
| `bun run build` | 构建生产可执行文件 |
|
||
| `bun run verify` | check + build 完整验证 |
|
||
| `bun run clean` | 清理构建缓存与临时文件 |
|
||
| `bun run version:patch` | 升迁 patch 版本（x.y.Z） |
|
||
| `bun run version:minor` | 升迁 minor 版本（x.Y.0） |
|
||
| `bun run version:major` | 升迁 major 版本（X.0.0） |
|
||
| `bun run version:set` | 显式设置版本号 |
|
||
|
||
## 质量门禁
|
||
|
||
代码变更必须按影响范围执行验证。
|
||
|
||
| 变更类型 | 必跑命令 |
|
||
| -------------------------- | ------------------------------------------------------------- |
|
||
| 常规代码变更 | `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`。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。
|
||
|
||
## 全局工程规则
|
||
|
||
- 使用中文编写注释、文档和项目内交流内容。
|
||
- 仅使用 bun 作为包管理器，禁止使用 npm、pnpm、yarn。
|
||
- 运行工具使用 bunx，禁止使用 npx、pnpx。
|
||
- 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。
|
||
- 后端优先使用 Bun 内置 API，其次是 es-toolkit、标准 Web API、主流三方库，最后才自行实现。
|
||
- 前端优先使用 Ant Design 组件默认能力和组件 props 组合界面，具体组件、样式、数据流和测试细节见 [frontend.md](frontend.md)。
|
||
- 当前项目无需考虑向前兼容。
|
||
|
||
## 包管理、依赖与提交
|
||
|
||
- 仅使用 bun 安装依赖和运行项目脚本，锁文件为 bun.lock。
|
||
- 新增依赖前先确认 Bun 内置 API、es-toolkit、标准 Web API、现有三方库和项目公共工具是否已满足需求。
|
||
- Git 提交信息使用中文，格式为"类型: 简短描述"。
|
||
- 提交类型限定为 feat、fix、refactor、docs、style、test、chore。
|
||
- 多行提交描述时，标题和正文之间空一行。
|
||
|
||
## 目录边界
|
||
|
||
| 目录 | 约定 |
|
||
| ------------------- | -------------------------------------------------------------------- |
|
||
| `src/server/` | Bun 后端代码，不能 import src/web/，HTML import 集成除外 |
|
||
| `src/server/db/` | SQLite 数据库模块，包含 schema、connection、migration 和 data access |
|
||
| `src/web/` | React 前端，不能 import src/server/ 运行时实现 |
|
||
| `src/shared/` | 前后端共享 TypeScript 类型 |
|
||
| `scripts/` | 独立运行脚本，可 import 项目源码 |
|
||
| `drizzle/` | Drizzle Kit 生成的 SQL migration 文件（开发期产出） |
|
||
| `tests/` | 测试目录，结构镜像 src/ |
|
||
| `docs/user/` | 用户使用、配置、部署和排障文档 |
|
||
| `docs/development/` | 架构、后端、前端、发布开发文档 |
|
||
| `openspec/` | OpenSpec 变更管理与规格文档 |
|
||
|
||
## 文档影响分析
|
||
|
||
每次代码变更都必须执行文档影响分析。
|
||
|
||
| 如果变更影响 | 更新 |
|
||
| ------------------------------------------ | ------------------------------------------ |
|
||
| 用户可见行为、配置、部署、运行行为 | `docs/user/` 对应文档 |
|
||
| 开发流程、架构、测试、构建发布流程 | `docs/development/` 对应文档 |
|
||
| 项目定位、快速开始、核心能力列表、文档导航 | `README.md` |
|
||
| 文档同步规则或文档归属矩阵 | `docs/README.md` 和 `openspec/config.yaml` |
|
||
|
||
如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../README.md)。
|
||
|
||
## 事实来源
|
||
|
||
| 主题 | 事实来源 |
|
||
| -------------- | -------------------------------------------------- |
|
||
| 代码结构和实现 | `src/`、`scripts/`、`tests/` |
|
||
| 配置 schema | TypeBox fragments、config.schema.json、schema 测试 |
|
||
| 项目全局规则 | `openspec/config.yaml`、本文档、本目录专题文档 |
|
||
|
||
## 更新触发条件
|
||
|
||
修改常用命令、质量门禁、全局工程规则、目录边界或开发文档索引时，必须更新本文档。
|