116 lines
6.9 KiB
Markdown
116 lines
6.9 KiB
Markdown
# 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) |
|
||
|
||
## 已知限制
|
||
|
||
当前不做告警通知、拨测目标动态增删、认证鉴权和分布式部署。
|