docs: 拆分 README 为 README.md 和 DEVELOPMENT.md
README 精简为项目概览和使用说明,开发相关内容(项目结构、构建、测试、规范等)迁入 DEVELOPMENT.md。同步更新 openspec/config.yaml 中的文档引用。
This commit is contained in:
99
README.md
99
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)。
|
||||
|
||||
Reference in New Issue
Block a user