# 架构与边界

## 项目结构

```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 类型                         |