lanyuanxiaoyao
c677b4f756
README 精简为项目概览和使用说明，开发相关内容（项目结构、构建、测试、规范等）迁入 DEVELOPMENT.md。同步更新 openspec/config.yaml 中的文档引用。
105 lines
3.7 KiB
Markdown
105 lines
3.7 KiB
Markdown
# DiAL 开发文档
|
||
|
||
本文档面向 DiAL 项目的开发者，介绍项目结构、构建流程、测试、代码规范等内容。
|
||
|
||
用户使用说明请参阅 [README.md](README.md)。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/
|
||
server/
|
||
app.ts Bun HTTP 路由（API + 静态资源 + SPA fallback）
|
||
config.ts CLI 参数解析
|
||
dev.ts 开发期启动入口
|
||
server.ts HTTP server 启动
|
||
checker/
|
||
types.ts 类型定义
|
||
config-loader.ts YAML 配置解析与校验
|
||
store.ts SQLite 数据存储
|
||
fetcher.ts HTTP 拨测执行
|
||
command-runner.ts 命令行拨测执行
|
||
size.ts 大小单位解析
|
||
engine.ts 调度引擎（按 interval 分组、组内并发）
|
||
expect/
|
||
http.ts HTTP 响应断言
|
||
command.ts 命令行输出断言
|
||
body.ts HTTP body 断言（JSONPath/XPath/CSS）
|
||
failure.ts 失败信息类型
|
||
shared/
|
||
api.ts 前后端共享 TypeScript 类型
|
||
web/ Vite + React 前端 Dashboard
|
||
components/ UI 组件（表格、分组、Drawer、状态条等）
|
||
constants/ 常量定义（列配置、类型映射、排序/筛选/颜色阈值函数）
|
||
hooks/ TanStack Query 数据层（useTargetDetail 集成轮询/条件查询）
|
||
utils/ 前端工具函数
|
||
scripts/ 开发、构建和 smoke test 脚本
|
||
tests/ Bun test 测试
|
||
openspec/ OpenSpec 变更与规格文档
|
||
```
|
||
|
||
## 构建 executable
|
||
|
||
```bash
|
||
bun run build
|
||
```
|
||
|
||
构建流程：
|
||
|
||
1. 运行 `vite build`，输出前端资源到 `dist/web`
|
||
2. 生成临时 `.build/static-assets.ts`，嵌入 Vite 产物
|
||
3. 生成临时 `.build/server-entry.ts`，作为生产入口
|
||
4. 运行 `Bun.build({ compile })`，输出 `dist/dial-server`
|
||
|
||
运行 executable：
|
||
|
||
```bash
|
||
./dist/dial-server probes.yaml
|
||
```
|
||
|
||
## 代码质量
|
||
|
||
```bash
|
||
bun run lint
|
||
bun run format:check
|
||
bun run format
|
||
bun run check
|
||
```
|
||
|
||
- `check` 依次运行 `typecheck`、`lint`、`format:check` 和单元测试。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
bun run check
|
||
bun run verify
|
||
```
|
||
|
||
- `check` 适合日常开发，包含类型检查、lint、格式检查和单元测试。
|
||
- `verify` 先运行 `check`，再重新构建生产 executable 并运行 smoke test。
|
||
|
||
## 前后端边界
|
||
|
||
前端只通过 HTTP 调用后端，API 路径为 `/api/*`。共享类型放在 `src/shared`，前端不得 import `src/server` 的运行时实现。
|
||
|
||
## 前端样式规范
|
||
|
||
前端基于 TDesign React 构建UI，样式开发遵循以下优先级（从高到低）：
|
||
|
||
1. **使用 TDesign 组件**：布局、间距、排版优先使用 TDesign 组件（如 Space、Divider、Typography）
|
||
2. **使用 TDesign 组件 props**：通过组件的 props 参数控制外观（如 `theme`、`variant`、`size`）
|
||
3. **使用 TDesign CSS tokens**：颜色、间距、字体等使用 `--td-*` CSS 变量（如 `--td-success-color`、`--td-comp-margin-xxl`）
|
||
4. **在 styles.css 中定义 CSS 类**：无法通过上述方式满足的样式需求，集中定义在 `styles.css` 中
|
||
5. **自行开发组件**：仅在 TDesign 无法满足需求时自行开发
|
||
|
||
**红线**：
|
||
|
||
- **严禁在组件中使用 `style` 属性内联调整样式**
|
||
- **严禁通过 CSS 覆盖 TDesign 组件内部类名**（如 `.t-tab-panel`），如需定制使用组件的 `className` prop
|
||
- **严禁使用 `!important`**
|
||
- 颜色统一使用 TDesign CSS tokens（`--td-success-color`、`--td-error-color`、`--td-warning-color` 等），不使用硬编码色值
|
||
|
||
## 已知限制
|
||
|
||
当前不做告警通知、数据自动清理、拨测目标动态增删、认证鉴权和分布式部署。Command 类型拨测不支持 Windows 环境。
|