lanyuanxiaoyao/Alfred
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 增加项目管理功能

Browse Source 
引入 SQLite 数据库（Drizzle ORM + bun:sqlite），实现项目 CRUD 与归档/恢复/删除
生命周期管理，新增项目管理前端页面，migration 嵌入单文件构建产物保持部署体验。

- src/server/db: schema、connection、migration 执行器、项目数据访问层
- src/server/routes/projects: 7 个 API 端点（列表/创建/详情/更新/归档/恢复/删除）
- src/web: 项目管理页面（TDesign Table/Tabs/Dialog/Form），TanStack Query hooks
- scripts: 构建时嵌入 migration SQL，开发期独立 generate-migrations-data 脚本
- tests: 60 个后端测试 + 27 个前端测试，覆盖 DB/migration/API/路由/页面
- docs: 更新架构、后端、发布、配置、部署、使用文档
This commit is contained in:
兰缘小妖
2026-05-27 18:54:44 +08:00
parent 348b35ef8c
commit d5a0ba9e9e
44 changed files with 2458 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/development/README.md
View File

@@ -71,16 +71,18 @@
## 目录边界
| 目录 | 约定 |
| ------------------- | -------------------------------------------------------- |
| `src/server/` | Bun 后端代码，不能 import src/web/，HTML import 集成除外 |
| `src/web/` | React 前端，不能 import src/server/ 运行时实现 |
| `src/shared/` | 前后端共享 TypeScript 类型 |
| `scripts/` | 独立运行脚本，可 import 项目源码 |
| `tests/` | 测试目录，结构镜像 src/ |
| `docs/user/` | 用户使用、配置、部署和排障文档 |
| `docs/development/` | 架构、后端、前端、发布开发文档 |
| `openspec/` | OpenSpec 变更管理与规格文档 |
| 目录 | 约定 |
| ------------------- | -------------------------------------------------------------------- |
| `src/server/` | Bun 后端代码，不能 import src/web/，HTML import 集成除外 |
| `src/server/db/` | SQLite 数据库模块，包含 schema、connection、migration 和 data access |
| `src/web/` | React 前端，不能 import src/server/ 运行时实现 |
| `src/shared/` | 前后端共享 TypeScript 类型 |
| `scripts/` | 独立运行脚本，可 import 项目源码 |
| `drizzle/` | Drizzle Kit 生成的 SQL migration 文件（开发期产出） |
| `tests/` | 测试目录，结构镜像 src/ |
| `docs/user/` | 用户使用、配置、部署和排障文档 |
| `docs/development/` | 架构、后端、前端、发布开发文档 |
| `openspec/` | OpenSpec 变更管理与规格文档 |
## 文档影响分析

35
docs/development/architecture.md
View File

@@ -9,9 +9,15 @@
```text
src/
server/
bootstrap.ts 统一启动引导（loadServerConfig -> startServer）
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 项目数据访问函数
dev.ts 开发模式启动入口
main.ts 生产模式启动入口
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由）
@@ -49,9 +55,13 @@ dev.ts / main.ts
-> bootstrap({ configPath, mode })
-> loadServerConfig(configPath)
-> createRuntimeLogger(config.logging)
-> startServer({ config, logger })
-> 确保 dataDir 就绪（mkdirSync）
-> 加载 migrations（生产：嵌入的 bytes；开发：磁盘 drizzle/ 目录）
-> createDatabase(dataDir)
-> runMigrations(db, migrations)（pending migration 存在时先备份 DB）
-> startServer({ config, logger, db })
-> logger 记录启动成功
-> SIGINT/SIGTERM -> logger.flush() -> exit
-> SIGINT/SIGTERM -> db.close() -> logger.flush() -> exit
```
## HTTP 请求流程
@@ -77,15 +87,16 @@ Request
## 主要模块职责
| 模块 | 职责 |
| ------------------------- | ---------------------------------------- |
| `src/server/bootstrap.ts` | 统一启动引导和 shutdown 编排 |
| `src/server/server.ts` | Bun HTTP server 和 routes 注册 |
| `src/server/routes/` | API handler，按端点拆分 |
| `src/server/config/` | 配置解析模块（types、variables、schema） |
| `src/web/` | React 前端 |
| `src/shared/api.ts` | 前后端共享 API 类型 |
| `src/shared/app.ts` | 应用全局常量 |
| 模块 | 职责 |
| ------------------------- | --------------------------------------------- |
| `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/config/` | 配置解析模块（types、variables、schema） |
| `src/web/` | React 前端 |
| `src/shared/api.ts` | 前后端共享 API 类型 |
| `src/shared/app.ts` | 应用全局常量 |
## 更新触发条件

37
docs/development/backend.md
View File

@@ -6,13 +6,13 @@
## 库使用优先级
| 优先级 | 来源 | 典型用途 |
| ------ | ------------ | ---------------------------------------- |
| 1 | Bun 内置 API | Bun.serve、Bun.file、Bun.YAML、Bun.spawn |
| 2 | es-toolkit | 类型判断、深度比较、并发控制 |
| 3 | 标准 Web API | Headers、fetch、AbortController |
| 4 | 主流三方库 | pino、@sinclair/typebox、ajv |
| 5 | 自行实现 | 仅在以上都无法满足时 |
| 优先级 | 来源 | 典型用途 |
| ------ | ------------ | ---------------------------------------------------- |
| 1 | Bun 内置 API | Bun.serve、Bun.file、Bun.YAML、Bun.spawn、bun:sqlite |
| 2 | es-toolkit | 类型判断、深度比较、并发控制 |
| 3 | 标准 Web API | Headers、fetch、AbortController |
| 4 | 主流三方库 | pino、@sinclair/typebox、ajv、drizzle-orm |
| 5 | 自行实现 | 仅在以上都无法满足时 |
新增依赖前必须先检查上述每一层是否已有可用方案。
@@ -41,6 +41,29 @@ middleware.ts 提供 API 参数校验函数：
- validatePagination(pageParam, pageSizeParam, mode) — 校验分页参数
- validateTimeRange(from, to, mode) — 校验时间范围参数
## 数据库
项目使用 SQLite 作为存储后端，通过 bun:sqlite + Drizzle ORM 实现类型安全的数据访问。
### schema 定义
`src/server/db/schema.ts` 使用 Drizzle ORM 定义表结构，列名使用 snake_case，TypeScript 类型使用 camelCase，Drizzle schema 负责映射。
### 数据库连接
`src/server/db/connection.ts` 的 `createDatabase(dataDir, logger)` 打开 `<dataDir>/alfred.db`，设置 PRAGMA（foreign_keys=ON、journal_mode=WAL、busy_timeout=5000）。
### migration 机制
- 开发期：使用 `drizzle-kit generate` 从 TS schema 生成 SQL migration 文件到 `drizzle/` 目录
- 生产期：构建时将 `drizzle/*.sql` 嵌入可执行文件，启动时自动应用 pending migrations
- 每次 migration 前自动备份现有 DB 到 `<dataDir>/backups/alfred-<timestamp>.db`
- migration 在事务中执行，失败则回滚并停止启动
### 数据访问
`src/server/db/projects.ts` 提供项目数据访问函数，输入输出使用 `src/shared/api.ts` 的类型。函数内部使用 Drizzle query builder 包装 `bun:sqlite` Database。
## 类型规范
- 共享类型以 src/shared/api.ts 为唯一源头

7
docs/development/release.md
View File

@@ -41,9 +41,10 @@ bun run build
构建流程：
```text
1. Vite build -> dist/web/
2. Code generation -> .build/static-assets.ts + .build/server-entry.ts
3. Bun compile -> dist/alfred
1. Vite build -> dist/web/
2. Code generation -> .build/static-assets.ts + .build/migrations-data.ts + .build/server-entry.ts
3. Bun compile -> dist/alfred
4. Cleanup -> 清理 .build/ 临时目录
```
构建参数：

6
docs/user/config.md
View File

@@ -36,9 +36,9 @@ server:
## server.storage
| 字段 | 类型 | 说明 |
| ------- | ------ | --------------------------------------------------- |
| dataDir | string | 数据目录，默认 ./data，相对路径基于配置文件目录解析 |
| 字段 | 类型 | 说明 |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| dataDir | string | 数据目录，默认 ./data，相对路径基于配置文件目录解析。目录下存储 alfred.db（SQLite 数据库）和 backups/（数据库备份） |
## server.logging

10
docs/user/deploy.md
View File

@@ -28,10 +28,18 @@ scripts/build.ts 执行三步流水线：
```
- Vite 构建前端资源到 dist/web/，自动 code splitting（vendor-react、vendor-tdesign、vendor-chart）
- Code generation 扫描 dist/web/ 生成 import with { type: "file" } 声明，将资源嵌入 binary
- Code generation 扫描 dist/web/ 生成 static-assets.ts，读取 drizzle/\*.sql 生成 migrations-data.ts，生成 server-entry.ts 串联入口
- migrations-data.ts 将 migration SQL 嵌入 binary，生产部署无需额外携带 migration 文件
- Bun compile 以 .build/server-entry.ts 为入口编译最终可执行文件
- .build/ 临时目录在构建完成后自动清理
## 运行时数据存储
- 应用使用 SQLite 存储数据，数据库文件位于 `<dataDir>/alfred.db`
- 启动时自动应用 pending database migrations（无需手动迁移）
- 每次 migration 执行前自动备份现有数据库到 `<dataDir>/backups/`
- 数据库文件使用 WAL 模式，支持并发读写
## 产物
| 产物 | 用途 |

9
docs/user/usage.md
View File

@@ -29,3 +29,12 @@ bun run dev config.yaml
- [配置文件](config.md) — 了解 YAML 结构、变量语法和配置字段
- [部署文档](deploy.md) — 生产构建和运行方式
- [开发文档](../development/README.md) — 开发规范、架构和质量门禁
## 功能介绍
| 功能 | 路径 | 说明 |
| -------- | ----------- | ------------------------------------ |
| 仪表盘 | `/` | 应用总览，展示运行时元信息 |
| 项目管理 | `/projects` | 创建、编辑、归档、恢复和永久删除项目 |
| 用户管理 | `/users` | 页面建设中 |
| 系统设置 | `/settings` | 页面建设中 |