1
0

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

README 精简为项目概览和使用说明,开发相关内容(项目结构、构建、测试、规范等)迁入 DEVELOPMENT.md。同步更新 openspec/config.yaml 中的文档引用。
This commit is contained in:
2026-05-12 12:55:03 +08:00
parent 9f2b906063
commit c677b4f756
3 changed files with 108 additions and 99 deletions

View File

@@ -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)。