docs: 重构文档体系

docs/development/architecture.md

@@ -0,0 +1,106 @@
+# 架构与边界
+
+## 项目结构
+
+```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 类型                         |