117 lines
4.8 KiB
Markdown
117 lines
4.8 KiB
Markdown
# 架构与边界
|
||
|
||
本文档说明 alfred 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。
|
||
|
||
适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/
|
||
server/
|
||
bootstrap.ts 统一启动引导（loadServerConfig -> DB 初始化 -> startServer）
|
||
config.ts CLI 参数解析与配置文件加载 facade
|
||
config/ 配置解析模块（types、issues、variables、normalizer、schema）
|
||
db/ SQLite 数据库模块
|
||
schema.ts Drizzle ORM schema 定义
|
||
connection.ts 数据库连接与 PRAGMA 设置
|
||
load-migrations.ts 从文件系统加载 migration SQL
|
||
migrate.ts migration 执行器（备份 + 事务应用）
|
||
projects.ts 项目数据访问函数
|
||
providers.ts 供应商数据访问函数
|
||
models.ts 模型数据访问函数
|
||
conversations.ts 会话数据访问函数
|
||
index.ts 数据库模块导出
|
||
ai/ AI 服务层
|
||
types.ts AI 配置类型定义
|
||
registry.ts AI Provider Registry 构建与连接测试
|
||
agent-stream.ts AI Agent 流式调用
|
||
dev.ts 开发模式启动入口
|
||
main.ts 生产模式启动入口
|
||
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由）
|
||
static.ts 生产模式静态资源服务
|
||
helpers.ts 共享响应格式化工具
|
||
middleware.ts API 参数校验中间件
|
||
logger.ts 结构化日志（基于 pino + pino-roll）
|
||
version.ts 运行时版本号读取
|
||
routes/ API 路由处理器
|
||
providers/ 供应商 CRUD 路由
|
||
models/ 模型 CRUD 路由
|
||
chat/ 聊天会话与消息路由
|
||
shared/
|
||
api.ts 前后端共享 TypeScript 类型定义
|
||
app.ts 应用全局常量（name、title、subtitle、description）
|
||
web/ React 前端（通过 Vite 构建）
|
||
index.html HTML 入口
|
||
main.tsx React 入口
|
||
app.tsx 根组件
|
||
routes.tsx 路由配置
|
||
styles.css 全局样式
|
||
pages/ 页面组件
|
||
models/ 模型管理页面
|
||
components/ UI 组件
|
||
hooks/ React Hooks
|
||
utils/ 前端工具函数
|
||
scripts/ 独立运行脚本
|
||
tests/ 测试文件（镜像 src 目录结构）
|
||
docs/ 项目文档
|
||
openspec/ OpenSpec 规格、变更与 fast-drive workflow schema
|
||
```
|
||
|
||
## 启动流程
|
||
|
||
```text
|
||
dev.ts / main.ts
|
||
-> parseRuntimeArgs(cli args)
|
||
-> 必须指定 config.yaml
|
||
-> bootstrap({ configPath, mode })
|
||
-> loadServerConfig(configPath)
|
||
-> createRuntimeLogger(config.logging)
|
||
-> 确保 dataDir 就绪（mkdirSync）
|
||
-> 加载 migrations（生产：嵌入的 bytes；开发：磁盘 drizzle/ 目录）
|
||
-> createDatabase(dataDir)
|
||
-> runMigrations(db, migrations)（pending migration 存在时先备份 DB）
|
||
-> startServer({ config, logger, db })
|
||
-> logger 记录启动成功
|
||
-> SIGINT/SIGTERM -> db.close() -> logger.flush() -> exit
|
||
```
|
||
|
||
## HTTP 请求流程
|
||
|
||
```text
|
||
Request
|
||
-> Bun.serve routes 声明式匹配
|
||
-> routes/*.ts handler
|
||
-> helpers.ts 响应格式化
|
||
-> Response
|
||
```
|
||
|
||
生产模式下，非 API 路径由 fetch fallback 处理：有文件扩展名的返回静态资源或 404，无扩展名的返回 SPA index.html。
|
||
|
||
开发模式下，Vite proxy 将 /api 请求转发到 Bun API server。
|
||
|
||
## 前后端边界
|
||
|
||
- 前端只通过 HTTP 调用后端，API 路径为 /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、schema） |
|
||
| `src/web/` | React 前端 |
|
||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||
| `src/shared/app.ts` | 应用全局常量 |
|
||
|
||
## 更新触发条件
|
||
|
||
修改项目结构、启动流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。
|