lanyuanxiaoyao
b1dec691e9
- consoles/admin/ → layouts/admin-layout/ - consoles/workbench/ → layouts/workbench-layout/ + features/chat/ - pages/ → features/ (dashboard, models, projects, not-found) - components/ → shared/components/ - hooks/ → shared/hooks/ - utils/ → shared/utils/ - 更新所有 import 路径 (src/web/ + tests/web/) - 更新开发文档 (README.md, frontend.md, architecture.md)
67 lines
3.5 KiB
Markdown
67 lines
3.5 KiB
Markdown
# 架构与边界
|
||
|
||
## 启动流程
|
||
|
||
```text
|
||
dev.ts / main.ts
|
||
-> parseRuntimeArgs(cli args) — 必须指定 config.yaml
|
||
-> bootstrap({ configPath, mode })
|
||
-> loadServerConfig(configPath) — 加载并校验配置（config.ts）
|
||
-> createRuntimeLogger(config.logging) — 创建 Logger 实例
|
||
-> 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/config.ts` | 配置加载入口：YAML 解析、规范化、契约校验、运行时校验 |
|
||
| `src/server/config/` | 配置子系统：types、variables、issues、normalizer、schema |
|
||
| `src/server/logger.ts` | Logger 接口 + Pino 实现 + 测试替身 |
|
||
| `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/helpers/` | 响应格式化、URL 工具 |
|
||
| `src/server/middleware/` | 参数校验 + 错误处理 |
|
||
| `src/web/layouts/` | 前端布局组件（AdminLayout / WorkbenchLayout） |
|
||
| `src/web/features/` | 前端功能模块（dashboard / projects / models / chat） |
|
||
| `src/web/shared/` | 前端共享代码（components / hooks / utils） |
|
||
| `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 请求流程、前后端边界或主要模块职责时，必须更新本文档。
|