lanyuanxiaoyao
714b635aef
- 合并 DEVELOPMENT.md 至 docs/development/README.md - 合并 CONTRIBUTING.md 至 docs/development/checker.md - 合并 build-release.md 至 release.md - 合并 testing-quality.md 内容至各专题文档 - 合并 status-model.md 至 expectations.md - 新增 docs/user/README.md 用户入口 - 简化 docs/README.md 文档路由 - 各专题文档新增适用场景和更新触发条件 - 更新 openspec/config.yaml 文档规则
115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
# 架构与边界
|
||
|
||
本文档说明 DiAL 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。
|
||
|
||
适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/
|
||
server/
|
||
bootstrap.ts
|
||
config.ts
|
||
dev.ts
|
||
logger.ts
|
||
main.ts
|
||
server.ts
|
||
helpers.ts
|
||
middleware.ts
|
||
version.ts
|
||
routes/
|
||
checker/
|
||
config-loader.ts
|
||
variables.ts
|
||
schema/
|
||
store.ts
|
||
engine.ts
|
||
expect/
|
||
runner/
|
||
shared/
|
||
api.ts
|
||
web/
|
||
app.tsx
|
||
main.tsx
|
||
styles.css
|
||
components/
|
||
constants/
|
||
hooks/
|
||
utils/
|
||
scripts/
|
||
tests/
|
||
docs/
|
||
openspec/
|
||
probe-config.schema.json
|
||
```
|
||
|
||
## 启动流程
|
||
|
||
```text
|
||
dev.ts / main.ts
|
||
-> readRuntimeConfig(cli args)
|
||
-> bootstrap({ configPath, mode })
|
||
-> loadConfig(yaml)
|
||
-> createRuntimeLogger(logging)
|
||
-> ProbeStore(db)
|
||
-> store.syncTargets(targets)
|
||
-> ProbeEngine(...).start()
|
||
-> startServer({ config, mode, store, logger })
|
||
-> 注册 SIGINT/SIGTERM shutdown
|
||
```
|
||
|
||
`loadConfig()` 的处理顺序：YAML 解析 -> Authoring normalize（变量替换 + expect 简写展开）-> Normalized 契约校验 -> 语义校验 -> resolve。
|
||
|
||
## 运行时流程
|
||
|
||
```text
|
||
定时器 tick
|
||
-> ProbeEngine.probeGroup()
|
||
-> checkerRegistry.get(target.type).execute()
|
||
-> runner/*/expect.ts 校验
|
||
-> engine.writeResult()
|
||
-> store.insertCheckResult()
|
||
```
|
||
|
||
数据清理由 engine 定时调用 `store.prune(retentionMs)`，每小时执行一次。
|
||
|
||
## HTTP 请求流程
|
||
|
||
```text
|
||
Request
|
||
-> Bun.serve routes 声明式匹配
|
||
-> routes/*.ts handler
|
||
-> middleware.ts 参数校验
|
||
-> helpers.ts 响应格式化
|
||
-> Response
|
||
```
|
||
|
||
生产模式下，非 API 路径由 fetch fallback 处理静态资源和 SPA fallback。开发模式下，Vite proxy 将 `/api` 和 `/health` 请求转发到 Bun API server。
|
||
|
||
## 前后端边界
|
||
|
||
- 前端只通过 HTTP 调用后端，API 路径为 `/api/*`。
|
||
- 共享类型放在 `src/shared/`。
|
||
- 前端不得 import `src/server/` 的运行时实现。
|
||
- 后端不得依赖 `src/web/` 运行时代码，HTML import 集成除外。
|
||
|
||
## 主要模块职责
|
||
|
||
| 模块 | 职责 |
|
||
| ------------------------------------- | ------------------------------------------- |
|
||
| `src/server/bootstrap.ts` | 统一启动引导和 shutdown 编排 |
|
||
| `src/server/server.ts` | Bun HTTP server 和 routes 注册 |
|
||
| `src/server/routes/` | API handler，按端点拆分 |
|
||
| `src/server/checker/config-loader.ts` | YAML 解析、契约校验、语义校验、resolve 调度 |
|
||
| `src/server/checker/store.ts` | SQLite 数据存储 |
|
||
| `src/server/checker/engine.ts` | 定时调度、并发控制、结果写入、数据清理 |
|
||
| `src/server/checker/runner/` | 各 checker 自包含实现 |
|
||
| `src/server/checker/expect/` | 跨 checker 复用的断言基础设施 |
|
||
| `src/web/` | React Dashboard |
|
||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||
|
||
## 更新触发条件
|
||
|
||
修改项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。
|