Files

lanyuanxiaoyao 714b635aef docs: 重构文档体系

- 合并 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 文档规则

2026-05-25 10:47:52 +08:00

3.4 KiB

Raw Blame History

架构与边界

本文档说明 DiAL 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。

适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。

项目结构

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

启动流程

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。

运行时流程

定时器 tick
  -> ProbeEngine.probeGroup()
  -> checkerRegistry.get(target.type).execute()
  -> runner/*/expect.ts 校验
  -> engine.writeResult()
  -> store.insertCheckResult()

数据清理由 engine 定时调用 store.prune(retentionMs)，每小时执行一次。

HTTP 请求流程

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 请求流程、前后端边界或主要模块职责时，必须更新本文档。

3.4 KiB Raw Blame History Unescape Escape