# 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 环境。