62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
# 架构与边界
|
||
|
||
## 启动流程
|
||
|
||
```text
|
||
dev.ts / main.ts
|
||
-> parseRuntimeArgs(cli args) — 必须指定 config.yaml
|
||
-> bootstrap({ configPath, mode })
|
||
-> loadServerConfig(configPath)
|
||
-> createRuntimeLogger(config.logging)
|
||
-> mkdirSync(dataDir)
|
||
-> 加载 migrations（生产：嵌入 bytes；开发：磁盘 drizzle/）
|
||
-> createDatabase(dataDir)
|
||
-> runMigrations(db, migrations) — pending 时先备份 DB
|
||
-> startServer({ config, logger, db })
|
||
-> SIGINT/SIGTERM -> db.close() -> logger.flush() -> exit
|
||
```
|
||
|
||
## HTTP 请求流程
|
||
|
||
```text
|
||
Request -> Bun.serve routes 声明式匹配 -> routes/*.ts handler -> helpers/ 响应格式化 -> Response
|
||
```
|
||
|
||
- 生产模式：非 API 路径由 fetch fallback 处理，有扩展名返回静态资源或 404，无扩展名返回 SPA index.html。
|
||
- 开发模式：Vite proxy 将 /api 转发到 Bun。
|
||
|
||
## 前后端边界
|
||
|
||
- 前端只通过 HTTP /api/\* 调用后端。
|
||
- 共享类型在 `src/shared/`。
|
||
- 前端禁止 import `src/server/` 运行时实现；后端禁止依赖 `src/web/` 运行时代码（HTML import 集成除外）。
|
||
|
||
## 主要模块
|
||
|
||
| 模块 | 职责 |
|
||
| ------------------------- | ------------------------------------------------ |
|
||
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化、shutdown 编排 |
|
||
| `src/server/server.ts` | Bun HTTP server + routes 注册 |
|
||
| `src/server/routes/` | API handler，按资源端点拆分 |
|
||
| `src/server/db/` | SQLite 连接、schema、migration、data access |
|
||
| `src/server/ai/` | AI Provider Registry + Agent 流式调用 |
|
||
| `src/server/config/` | 配置解析（types、variables、normalizer、schema） |
|
||
| `src/server/helpers/` | 响应格式化、URL 工具 |
|
||
| `src/server/middleware/` | 参数校验 + 错误处理 |
|
||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||
| `src/shared/app.ts` | 应用全局常量 |
|
||
|
||
## 路由分组
|
||
|
||
| 资源 | 路径前缀 | 文件目录 |
|
||
| --------- | ----------------------------------------------- | ------------------- |
|
||
| meta | `/api/meta` | `routes/meta.ts` |
|
||
| providers | `/api/providers` | `routes/providers/` |
|
||
| models | `/api/models` | `routes/models/` |
|
||
| projects | `/api/projects` | `routes/projects/` |
|
||
| chat | `/api/projects/:id/conversations` 和 `:id/chat` | `routes/chat/` |
|
||
|
||
## 更新触发条件
|
||
|
||
修改项目结构、启动流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。
|