lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity

docs: 重构文档体系

Browse Source 
- 合并 DEVELOPMENT.md 至 docs/development/README.md
- 合并 CONTRIBUTING.md 至 docs/development/checker.md
- 合并 build-release.md 至 release.md
- 合并 testing-quality.md 内容至各专题文档
- 合并 status-model.md 至 expectations.md
- 新增 docs/user/README.md 用户入口
- 简化 docs/README.md 文档路由
- 各专题文档新增适用场景和更新触发条件
- 更新 openspec/config.yaml 文档规则
This commit is contained in:
兰缘小妖
2026-05-25 10:47:52 +08:00
parent a6504d5a62
commit 714b635aef
18 changed files with 428 additions and 542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
docs/development/README.md
View File

@@ -1,25 +1,115 @@
# 开发文档
本目录承载 DiAL 的开发和维护专题。日常开发入口见 [`../../DEVELOPMENT.md`](../../DEVELOPMENT.md)，新增或修改 checker 前先阅读 [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md)。
本文档是 DiAL 的开发入口。AI 工具和开发者应先阅读 [`../README.md`](../README.md) 判断文档归属，再阅读本文和最小必要专题。
适用场景：修改源码、测试、构建脚本、开发流程、架构边界、checker 开发机制或项目工程规则。
## 专题索引
| 文档 | 内容 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 |
| [backend.md](backend.md) | 后端库优先级、API 路由、共享 helpers、类型规范、配置契约、store、engine、logger、expect、错误模型 |
| [frontend.md](frontend.md) | React、TDesign、TanStack Query、组件、样式和前端测试规范 |
| [checker-development.md](checker-development.md) | 新增或修改 checker 的实现机制和完整 checklist |
| [build-release.md](build-release.md) | 开发服务、前后端集成、构建、Docker、release、脚本、环境变量 |
| [testing-quality.md](testing-quality.md) | lint、format、typecheck、test、hooks 和测试编写规范 |
| [../../DEVELOPMENT.md](../../DEVELOPMENT.md) | 包管理、依赖、目录、提交、OpenSpec 和项目级约定 |
| [../README.md](../README.md) | 文档影响分析、文档归属矩阵和按任务阅读路径 |
| 文档 | 内容 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 |
| [backend.md](backend.md) | 后端库优先级、API 路由、共享 helpers、类型规范、配置契约、store、engine、logger、expect、错误模型 |
| [frontend.md](frontend.md) | React、TDesign、TanStack Query、组件、样式和前端测试规范 |
| [checker.md](checker.md) | 新增或修改 checker 的实现机制、测试要求、文档同步和 checklist |
| [release.md](release.md) | 开发服务、前后端集成、构建、Docker、release、脚本、环境变量 |
| [../README.md](../README.md) | 文档路由、文档归属矩阵、development/user 文档更新规则 |
## 常用命令
| 命令 | 说明 |
| -------------------------------- | ---------------------------------------- |
| `bun install` | 安装依赖 |
| `bun run dev probes.yaml` | 启动双进程开发环境 |
| `bun run dev:server probes.yaml` | 仅启动后端 API server |
| `bun run dev:web` | 仅启动 Vite dev server |
| `bun run schema` | 生成 `probe-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 release` | 跨平台发布打包 |
| `bun run clean` | 清理构建缓存与产物 |
## 质量门禁
代码变更必须按影响范围执行验证。
| 变更类型 | 必跑命令 |
| -------------------------------- | --------------------------------------------------------- |
| 常规代码变更 | `bun run check` |
| 构建、部署、发布、前后端集成变更 | `bun run verify` |
| 配置 schema 变化 | `bun run schema`、`bun run schema:check`、`bun run check` |
| checker 新增或修改 | `bun run schema`、`bun run schema:check`、`bun run check` |
| 仅文档变更 | 检查链接、索引和文档归属一致性 |
正式提交或影响构建产物时优先运行 `bun run verify`。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。
## 全局工程规则
- 使用中文编写注释、文档和项目内交流内容。
- 仅使用 `bun` 作为包管理器，禁止使用 npm、pnpm、yarn。
- 运行工具使用 `bunx`，禁止使用 npx、pnpx。
- 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。
- 后端优先使用 Bun 内置 API，其次是 es-toolkit、标准 Web API、主流三方库，最后才自行实现。
- 前端样式优先使用 TDesign 组件、组件 props、TDesign CSS tokens、`styles.css` CSS 类，最后才自行开发组件。
- 前端禁止组件内联 `style`、覆盖 TDesign 内部类名、使用 `!important`、硬编码色值。
- 当前项目未上线，不需要为旧行为做向前兼容，除非用户明确要求。
## 包管理、依赖与提交
- 仅使用 `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/web/` | React Dashboard，不能 import `src/server/` 运行时实现 |
| `src/shared/` | 前后端共享 TypeScript 类型 |
| `scripts/` | 独立运行脚本，可 import 项目源码 |
| `tests/` | 测试目录，结构镜像 `src/` |
| `docs/user/` | 用户使用、配置、部署、checker 和排障文档 |
| `docs/development/` | 架构、后端、前端、发布和 checker 开发文档 |
| `openspec/` | OpenSpec 变更管理与规格文档 |
## 文档影响分析
每次代码变更都必须执行文档影响分析。
| 如果变更影响 | 更新 |
| --------------------------------------------------- | ------------------------------------------ |
| 用户可见行为、配置、checker、expect、部署、状态模型 | `docs/user/` 对应文档 |
| 开发流程、架构、测试、构建发布、checker 开发机制 | `docs/development/` 对应文档 |
| 项目定位、快速开始、核心能力列表、文档导航 | `README.md` |
| 文档同步规则或文档归属矩阵 | `docs/README.md` 和 `openspec/config.yaml` |
如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../README.md)。
## OpenSpec 协作规则
- 本项目 OpenSpec 使用 `fast-drive` schema，变更文档只包含 `design.md` 和 `tasks.md`，不创建 `proposal.md` 或 `specs/*.md`。
- `design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth。
- `tasks.md` 必须从 `design.md` 派生，一行一个 checkbox 任务。
- 实现阶段按 `tasks.md` 顺序执行，完成后立即标记任务状态。
## 事实来源
| 主题 | 事实来源 |
| ---------------- | ---------------------------------------------------------- |
| 代码结构和实现 | `src/`、`scripts/`、`tests/` |
| 配置 schema | TypeBox fragments、`probe-config.schema.json`、schema 测试 |
| 项目全局规则 | `openspec/config.yaml`、`DEVELOPMENT.md`、本目录专题文档 |
| checker 贡献流程 | `CONTRIBUTING.md`、`checker-development.md` |
| 主题 | 事实来源 |
| -------------- | ---------------------------------------------------------- |
| 代码结构和实现 | `src/`、`scripts/`、`tests/` |
| 配置 schema | TypeBox fragments、`probe-config.schema.json`、schema 测试 |
| 项目全局规则 | `openspec/config.yaml`、本文档、本目录专题文档 |
| checker 流程 | [checker.md](checker.md) |
## 更新触发条件
修改常用命令、质量门禁、全局工程规则、目录边界、OpenSpec 协作方式或开发文档索引时，必须更新本文档。