# DiAL 开发入口

本文档是 DiAL 项目的开发入口，保留常用命令、全局规则和专题导航。详细架构、前端、后端、构建、测试和 checker 开发说明位于 [`docs/development/`](docs/development/README.md)。用户使用说明见 [README.md](README.md) 和 [docs/README.md](docs/README.md)。

## 常用命令

| 命令                             | 说明                                     |
| -------------------------------- | ---------------------------------------- |
| `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 test`                       | 运行全部测试                             |
| `bun run check`                  | `schema:check + typecheck + lint + test` |
| `bun run build`                  | 构建生产可执行文件                       |
| `bun run verify`                 | `check + build` 完整验证                 |
| `bun run release`                | 跨平台发布打包                           |
| `bun run clean`                  | 清理构建缓存与产物                       |

## 质量门禁

代码变更必须按影响范围执行验证。常规变更优先运行：

```bash
bun run check
```

正式提交或影响构建、部署、发布、前后端集成的变更运行：

```bash
bun run verify
```

新增或修改配置 schema 时必须运行：

```bash
bun run schema
bun run schema:check
```

## 全局工程规则

- 使用中文编写注释、文档和项目内交流内容。
- 仅使用 `bun` 作为包管理器，禁止使用 npm、pnpm、yarn。
- 运行工具使用 `bunx`，禁止使用 npx、pnpx。
- 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。
- 后端优先使用 Bun 内置 API，其次是 es-toolkit、主流三方库、项目公共工具，最后才自行实现。
- 前端样式优先使用 TDesign 组件、组件 props、TDesign CSS tokens、`styles.css` CSS 类，最后才自行开发组件。
- 前端禁止组件内联 `style`、覆盖 TDesign 内部类名、使用 `!important`、硬编码色值。
- 当前项目未上线，不需要为旧行为做向前兼容，除非用户明确要求。

## 包管理、依赖与提交

- 仅使用 `bun` 安装依赖和运行项目脚本，锁文件为 `bun.lock`。
- 运行外部工具使用 `bunx`。
- 新增依赖前先确认 Bun 内置 API、es-toolkit、现有三方库和项目公共工具是否已满足需求。
- 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/` | 架构、开发规范、构建发布和测试质量                         |
| `openspec/`         | OpenSpec 变更管理与规格文档                                |

## 文档影响分析

每次代码变更都必须执行文档影响分析。

| 如果变更影响                                        | 更新                                       |
| --------------------------------------------------- | ------------------------------------------ |
| 用户可见行为、配置、checker、expect、部署、状态模型 | `docs/user/` 对应文档                      |
| 开发流程、架构、测试、构建发布、checker 开发机制    | `docs/development/` 或 `CONTRIBUTING.md`   |
| 项目定位、快速开始、核心能力列表、文档导航          | `README.md`                                |
| 开发入口、质量门禁、全局规则、专题导航              | `DEVELOPMENT.md`                           |
| 文档同步规则                                        | `docs/README.md` 和 `openspec/config.yaml` |

如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](docs/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` 顺序执行，完成后立即标记任务状态。

## 专题文档

| 主题             | 文档                                                                               |
| ---------------- | ---------------------------------------------------------------------------------- |
| 开发文档索引     | [docs/development/README.md](docs/development/README.md)                           |
| 架构与边界       | [docs/development/architecture.md](docs/development/architecture.md)               |
| 后端开发         | [docs/development/backend.md](docs/development/backend.md)                         |
| 前端开发         | [docs/development/frontend.md](docs/development/frontend.md)                       |
| Checker 开发机制 | [docs/development/checker-development.md](docs/development/checker-development.md) |
| 构建与发布       | [docs/development/build-release.md](docs/development/build-release.md)             |
| 测试与质量       | [docs/development/testing-quality.md](docs/development/testing-quality.md)         |
| 文档总览         | [docs/README.md](docs/README.md)                                                   |
| 贡献指南         | [CONTRIBUTING.md](CONTRIBUTING.md)                                                 |

## 已知限制

当前不做告警通知、拨测目标动态增删、认证鉴权和分布式部署。