From c677b4f7565495c92d973da9ec4ac30a1030e538 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Tue, 12 May 2026 12:55:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8B=86=E5=88=86=20README=20=E4=B8=BA?= =?UTF-8?q?=20README.md=20=E5=92=8C=20DEVELOPMENT.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README 精简为项目概览和使用说明，开发相关内容（项目结构、构建、测试、规范等）迁入 DEVELOPMENT.md。同步更新 openspec/config.yaml 中的文档引用。 --- DEVELOPMENT.md | 104 +++++++++++++++++++++++++++++++++++++++++++ README.md | 99 +--------------------------------------- openspec/config.yaml | 4 +- 3 files changed, 108 insertions(+), 99 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..e895bb7 --- /dev/null +++ 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 环境。 diff --git a/README.md b/README.md index ed57133..c93c918 100644 --- 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)。 diff --git a/openspec/config.yaml b/openspec/config.yaml index 9fbac0d..8c8c067 100644 --- 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