docs: 拆分 README 为 README.md 和 DEVELOPMENT.md

README 精简为项目概览和使用说明，开发相关内容（项目结构、构建、测试、规范等）迁入 DEVELOPMENT.md。同步更新 openspec/config.yaml 中的文档引用。
2026-05-12 12:55:03 +08:00
parent 9f2b906063
commit c677b4f756
3 changed files with 108 additions and 99 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -0,0 +1,104 @@
 # 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 环境。
--- a/README.md
+++ b/README.md
@@ -2,40 +2,6 @@
 基于 Bun + TypeScript 的多类型拨测监控工具。通过 YAML 配置文件定义 HTTP 和命令行拨测目标，后端按配置定时并发拨测，结果持久化到本地 SQLite，前端 Dashboard 展示各目标实时状态、可用率、耗时趋势等。
 ## 项目结构
 ```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 变更与规格文档
 ```
 ## 快速开始
 ```bash
@@ -211,36 +177,6 @@ API 错误返回 `ApiErrorResponse` 格式：
 | 404    | 目标不存在、API 路由未匹配                                              |
 | 405    | 非 GET 方法请求 API 路由                                                |
 ## 代码质量
 ```bash
 bun run lint
 bun run format:check
 bun run format
 bun run check
 ```
 - `check` 依次运行 `typecheck`、`lint`、`format:check` 和单元测试。
 ## 构建 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
 ```
 ## 运行参数
 CLI 只接受一个参数：YAML 配置文件路径。
@@ -249,37 +185,6 @@ CLI 只接受一个参数：YAML 配置文件路径。
 ./dist/dial-server ./probes.yaml
 ```
 ## 测试
 ```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` 等），不使用硬编码色值
 ## 目标状态判定
 单层判定模型，适用于 HTTP 和 Command 两种类型：
@@ -290,6 +195,6 @@ bun run verify
 执行失败（网络错误、超时、进程崩溃）和 expect 不匹配都统一为 `matched=false`，通过 `failure.kind` 区分（`"error"` vs `"mismatch"`）。
-## 已知限制
+---
-当前不做告警通知、数据自动清理、拨测目标动态增删、认证鉴权和分布式部署。Command 类型拨测不支持 Windows 环境。
+> 开发相关文档（项目结构、构建、测试、代码规范等）请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -3,7 +3,7 @@ schema: spec-driven
 context: |
  - 使用中文（注释、文档、交流），面向中文开发者
  - openspec文档的关键字按openspec规范使用，不要翻译为中文
-  - **优先阅读README.md**获取项目结构与开发规范，所有代码风格、命名、注解、依赖、API等规范以README为准
+  - **优先阅读README.md和DEVELOPMENT.md**获取项目概览与开发规范，所有代码风格、命名、注解、依赖、API等规范以DEVELOPMENT.md为准
  - 涉及模块结构、API、实体等变更时同步更新README.md
  - 新增代码优先复用已有组件、工具、依赖库，不引入新依赖
  - 新增的逻辑必须编写完善的测试，并保证测试的正确性，不允许跳过任何测试
@@ -28,4 +28,4 @@ rules:
    - 一行一个任务，严禁任务内容跨行
    - 如果是代码存在更新必须
      - 执行完整的测试、代码检查、格式检查等质量保障手段
-      - 更新README文档
+      - 更新 README.md 和/或 DEVELOPMENT.md