feat: 实现环境变量预设功能 & 移除稀疏检出

## 后端改动 - 添加 Project.envPresets 字段（JSON 格式） - 移除 Deployment.env 字段，统一使用 envVars - 更新部署 DTO，支持 envVars (Record<string, string>) - pipeline-runner 支持解析并注入 envVars 到环境 - 移除稀疏检出模板和相关环境变量 - 优化代码格式（Biome lint & format） ## 前端改动 - 新增 EnvPresetsEditor 组件（支持单选/多选/输入框类型） - 项目创建/编辑界面集成环境预设编辑器 - 部署界面基于预设动态生成环境变量表单 - 移除稀疏检出表单项 - 项目详情页添加环境变量预设配置 tab - 优化部署界面布局（基本参数 & 环境变量分区） ## 文档 - 添加完整文档目录结构（docs/） - 创建设计文档 design-0005（部署流程重构） - 添加 API 文档、架构设计文档等 ## 数据库 - 执行 prisma db push 同步 schema 变更
2026-01-03 22:59:20 +08:00
parent c40532c757
commit d22fdc9618
71 changed files with 9611 additions and 5849 deletions
--- a/docs/.meta/OWNERS.md
+++ b/docs/.meta/OWNERS.md
@@ -0,0 +1,7 @@
+# 文档拥有者
+
+- backend: backend-team@example.com
+- ops: ops-team@example.com
+- product: product-team@example.com
+
+每个文档请在 front-matter 中声明 `owners` 字段。
--- a/docs/.meta/templates/design-template.md
+++ b/docs/.meta/templates/design-template.md
@@ -0,0 +1,116 @@
+---
+title: 设计文档模板
+summary: 记录一个功能/模块的设计方案、权衡与落地计划（建议配套 ADR）。
+owners:
+  - team: <team>
+reviewers:
+  - <name-or-team>
+status: draft
+date: 2026-01-03
+version: 0.1.0
+related:
+  - adr: docs/architecture/adr-xxxx-<slug>.md
+  - pr: <link>
+  - issue: <link>
+---
+
+# 设计文档：<标题>
+
+## 1. 背景（Context）
+
+- 当前问题是什么？为什么现在要做？
+- 相关现状：已有模块/接口/数据模型（附链接）
+- 约束：技术栈、部署方式、团队边界、时间/人力
+
+## 2. 目标（Goals）
+
+- [ ] 目标 1（可验证）
+- [ ] 目标 2（可验证）
+
+## 3. 非目标（Non-goals）
+
+- 不做什么（防止范围膨胀）
+
+## 4. 需求与范围（Requirements & Scope）
+
+- 用户/角色：谁会用？（例如：管理员、开发者、CI runner）
+- 功能需求：
+  - R1:
+  - R2:
+- 非功能需求：性能、可用性、可维护性、可观测性
+
+## 5. 方案概览（High-level Design）
+
+- 用 5-10 行描述整体方案（模块、数据流、调用链）
+- 关键选择：为什么选这个方案？
+
+## 6. 详细设计（Detailed Design）
+
+### 6.1 接口/API 设计
+
+- 新增/变更端点（路径、方法、权限、请求/响应示例）
+- 错误码与错误语义（与 `BusinessError` 对齐）
+
+### 6.2 数据模型/数据库
+
+- Prisma model 变更（字段、索引、迁移策略）
+- 数据一致性与幂等策略（例如：重试/重复提交）
+
+### 6.3 任务/队列/异步处理（如有）
+
+- 队列模型：入队、出队、并发、重试、死信/失败处理
+- 状态机：状态枚举与迁移
+
+### 6.4 配置与环境变量
+
+- 新增 env（默认值、是否敏感、是否需要重启）
+
+### 6.5 可观测性
+
+- 日志：关键日志点、traceId/requestId（如有）
+- 指标：成功率、延迟、队列长度、失败原因分布
+- 告警：P0/P1 触发条件
+
+### 6.6 安全与权限
+
+- 认证：是否要求登录（session）
+- 授权：角色/资源权限（项目级、流水线级）
+- 数据安全：敏感信息、token、日志脱敏
+
+## 7. 影响与权衡（Trade-offs）
+
+- 性能影响
+- 运维影响
+- 对现有接口/调用方的影响
+- 技术债与后续演进
+
+## 8. 兼容性与迁移（Compatibility & Migration）
+
+- 是否 breaking change？
+- 迁移步骤（DB、配置、数据回填）
+- 回滚策略
+
+## 9. 测试计划（Test Plan）
+
+- 单测：覆盖哪些模块
+- 集成测试：关键链路（如：创建部署 -> 入队 -> 执行 -> 状态更新）
+- 手工验证：步骤清单
+
+## 10. 发布计划（Rollout Plan）
+
+- 分阶段：灰度/开关/逐步放量（如有）
+- 监控指标与验收标准
+
+## 11. 备选方案（Alternatives Considered）
+
+- 方案 A：为什么不用
+- 方案 B：为什么不用
+
+## 12. 风险与开放问题（Risks & Open Questions）
+
+- 风险 1
+- 问题 1（需要谁来决定/何时决定）
+
+## 13. 附录（Appendix）
+
+- 相关链接：控制器、DTO、Prisma schema、PR 等
--- a/docs/.meta/templates/runbook-template.md
+++ b/docs/.meta/templates/runbook-template.md
@@ -0,0 +1,22 @@
+---
+title: Runbook 模板
+owners:
+  - ops: ops-team
+status: draft
+---
+
+# Runbook 标题
+
+## 触发条件
+
+## 负责人
+
+## 联系方式
+
+## 暂时性缓解
+
+## 恢复步骤
+
+## 验证
+
+## 回滚（如果适用）
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -0,0 +1,14 @@
+---
+title: API 文档
+summary: 本目录存放 OpenAPI 定义与 API 使用说明。
+tags: [api]
+owners:
+  - team: backend
+status: stable
+---
+
+# API 文档
+
+本目录包含 OpenAPI 规范与示例。可使用 Swagger UI 或 Redoc 渲染 `openapi.yaml`。
+
+- OpenAPI: `openapi.yaml`
--- a/docs/api/endpoints.md
+++ b/docs/api/endpoints.md
@@ -0,0 +1,78 @@
+---
+title: API 端点总览
+summary: 基于 `apps/server` 控制器实现的主要 REST API 端点汇总。
+owners:
+  - team: backend
+status: stable
+---
+
+# API 端点总览
+
+基础前缀：`/api`
+
+下面列出当前实现的主要控制器与常用端点。
+
+## Projects (`/api/projects`)
+
+- GET `/api/projects` : 列表（支持分页与按 name 搜索）
+- GET `/api/projects/:id` : 获取单个项目（包含 workspace 状态）
+- POST `/api/projects` : 创建项目（body: `name`, `repository`, `projectDir` 等）
+- PUT `/api/projects/:id` : 更新项目
+- DELETE `/api/projects/:id` : 软删除（将 `valid` 置为 0）
+
+示例：
+
+```http
+GET /api/projects?page=1&limit=10
+```
+
+## User (`/api/user`)
+
+- GET `/api/user/list` : 模拟用户列表
+- GET `/api/user/detail/:id` : 用户详情
+- POST `/api/user` : 创建用户
+- PUT `/api/user/:id` : 更新用户
+- DELETE `/api/user/:id` : 删除用户
+- GET `/api/user/search` : 搜索用户
+
+## Auth (`/api/auth`)
+
+- GET `/api/auth/url` : 获取 Gitea OAuth 授权 URL
+- POST `/api/auth/login` : 使用 OAuth code 登录（返回 session）
+- GET `/api/auth/logout` : 登出
+- GET `/api/auth/info` : 当前会话用户信息
+
+注意：需要配置 `GITEA_URL`、`GITEA_CLIENT_ID`、`GITEA_REDIRECT_URI`。
+
+## Deployments (`/api/deployments`)
+
+- GET `/api/deployments` : 列表（支持 projectId 过滤）
+- POST `/api/deployments` : 创建部署（会将任务加入执行队列）
+- POST `/api/deployments/:id/retry` : 重新执行某次部署（复制记录并 requeue）
+
+## Pipelines (`/api/pipelines`)
+
+- GET `/api/pipelines` : 列表（含 steps）
+- GET `/api/pipelines/templates` : 获取可用流水线模板
+- GET `/api/pipelines/:id` : 单个流水线（含步骤）
+- POST `/api/pipelines` : 创建流水线
+- POST `/api/pipelines/from-template` : 基于模板创建流水线
+- PUT `/api/pipelines/:id` : 更新流水线
+- DELETE `/api/pipelines/:id` : 软删除
+
+## Steps (`/api/steps`)
+
+- GET `/api/steps` : 列表（支持 pipelineId 过滤）
+- GET `/api/steps/:id` : 单个步骤
+- POST `/api/steps` : 创建步骤（包含 `script` 字段）
+- PUT `/api/steps/:id` : 更新步骤
+- DELETE `/api/steps/:id` : 软删除
+
+## Git (`/api/git`)
+
+- GET `/api/git/commits?projectId=&branch=` : 获取指定项目的提交列表（调用 Gitea）
+- GET `/api/git/branches?projectId=` : 获取分支列表
+
+---
+
+想要更详细的示例（请求 body、响应 schema），我可以为每个端点基于 `dto.ts` 自动生成示例请求/响应片段。是否需要我继续生成？
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -0,0 +1,28 @@
+openapi: 3.0.1
+info:
+  title: Foka-CI 示例 API
+  version: '1.0.0'
+paths:
+  /health:
+    get:
+      summary: 健康检查
+      responses:
+        '200':
+          description: OK
+  /projects:
+    get:
+      summary: 列出项目
+      responses:
+        '200':
+          description: 项目列表
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    name:
+                      type: string
--- a/docs/architecture/adr-0001-service-design.md
+++ b/docs/architecture/adr-0001-service-design.md
@@ -0,0 +1,26 @@
+---
+title: ADR 0001 - 服务设计决策
+date: 2026-01-03
+authors:
+  - backend-team
+status: accepted
+---
+
+# ADR 0001: 服务设计与部署模型
+
+## 背景
+
+需要选择微服务还是单体部署以便平衡开发速度与运维复杂度。
+
+## 决策
+
+采用模块化单体（modular monolith）作为初始阶段部署方式，关键模块解耦、接口明确，后续按需拆分服务。
+
+## 影响
+
+- 优点：降低初期运维成本，便于本地调试与 CI 集成。
+- 缺点：需要在代码边界设计中预留拆分点。
+
+## 备注
+
+在拆分时优先考虑数据库边界和独立部署能力。
--- a/docs/architecture/design-0001-product-prototype.md
+++ b/docs/architecture/design-0001-product-prototype.md
@@ -0,0 +1,175 @@
+---
+title: 设计文档 0001 - 产品原型
+summary: 产品的设计原型
+owners:
+  - team: backend
+reviewers:
+  - ops-team
+status: draft
+date: 2026-01-03
+version: 0.1.0
+---
+
+# 设计文档 0001：产品整体原型
+
+## 1. 背景（Context）
+
+企业内部代码发布是非常频繁的事情，无论是测试环境还是生产环境，发布代码常常面临着一些痛点：频繁发布浪费开发时；手动发布代码可能漏掉某些步骤、造成环境报错。所以需要引入 CI/CD 工具让发布流程自动化，市场上已经存在很多解决类似问题的产品，例如 Drone CI、jenkins 等，但是这些工具不够灵活、不能满足全部场景，所以便有了 Foka-CI 这款产品。
+
+## 2. 拆解需求
+
+### 登录认证页面
+
+仅提供 Gitea 的 OAuth 认证登录，方便获取仓库信息，简化密码登录过程
+
+### 项目列表页面
+
+查看所有项目，项目的基本信息有：
+
+- 项目名
+- 项目描述（可选）
+- 代码仓库地址
+- 项目的工作目录，用于将代码克隆到该目录下，发布流水线脚本在该目录下执行
+
+创建项目，需要填写基本信息
+
+### 项目详情页
+
+
+## 2. 目标（Goals）
+
+- [ ] 明确“部署任务”从创建到执行的状态流转与约束
+- [ ] 明确重试语义（retry 会创建新 deployment，而不是复用原记录）
+- [ ] 降低重复入队/重复执行的风险（幂等与并发边界清晰）
+- [ ] 让运维/排障更容易：关键日志点与可观测性清单
+
+## 3. 非目标（Non-goals）
+
+- 不引入外部消息队列（如 Redis/Kafka），仍以当前内存队列 + DB 恢复为基础
+- 不在本文直接实现大规模调度/分布式 runner（后续 ADR/设计再做）
+
+## 4. 需求与范围（Requirements & Scope）
+
+### 功能需求
+
+- 创建部署：写入一条 Deployment 记录，初始状态为 `pending`，并加入执行队列
+- 重试部署：通过 `/deployments/:id/retry` 创建一条新的 Deployment 记录（复制必要字段），并加入执行队列
+- 服务重启恢复：服务启动后能从 DB 找回仍为 `pending` 的任务并继续执行
+
+### 非功能需求
+
+- 可靠性：服务重启不会“丢任务”（pending 的任务能恢复）
+- 幂等性：避免同一个 deployment 被重复执行
+- 可观测性：能定位某次部署为何失败、何时开始/结束、队列长度
+
+## 5. 方案概览（High-level Design）
+
+当前方案核心链路如下：
+
+1. API 创建 Deployment（status=pending）
+2. `ExecutionQueue.addTask(deploymentId, pipelineId)` 入队
+3. `ExecutionQueue.processQueue()` 串行消费 `pendingQueue`
+4. `executePipeline()` 会读取 Deployment 与关联 Project，获取 `projectDir`，然后创建 `PipelineRunner` 执行
+5. 定时轮询：每 30 秒扫描 DB 中的 pending 任务，若不在 `runningDeployments` 集合则补入队列
+
+## 6. 详细设计（Detailed Design）
+
+### 6.1 接口/API 设计
+
+#### 创建部署
+
+- POST `/api/deployments`
+- 行为：创建 Deployment 后立即入队
+
+#### 重试部署
+
+- POST `/api/deployments/:id/retry`
+- 行为：读取原 deployment -> 创建新 deployment（status=pending）-> 入队
+- 语义：重试是“创建一个新的任务实例”，便于保留历史执行记录
+
+### 6.2 数据模型/数据库
+
+Deployment 当前关键字段（见 schema 注释）：
+
+- `status`: pending/running/success/failed/cancelled（目前入队依赖 pending）
+- `buildLog`: 执行日志（当前创建时写空字符串）
+- `startedAt`/`finishedAt`: 时间标记（目前 created 时 startedAt 默认 now）
+
+建议补齐/明确（文档层面约束，代码后续落地）：
+
+- 状态迁移：
+  - `pending` -> `running`（开始执行前）
+  - `running` -> `success|failed|cancelled`（结束后）
+- 幂等控制：
+  - 以 deploymentId 为“单次执行唯一标识”，同一个 deploymentId 不允许重复开始执行
+
+### 6.3 队列/轮询/并发
+
+现状：
+
+- `runningDeployments` 同时承担“已入队/执行中”的去重集合
+- `pendingQueue` 为内存 FIFO
+- 单实例串行消费（`processQueue` while 循环）
+- 轮询间隔常量 30 秒
+
+风险点（需要在文档中明确约束/后续逐步修正）：
+
+- 多实例部署：如果将来启动多个 server 实例，每个实例都可能轮询到同一条 pending 记录并执行（需要 DB 锁/租约/状态原子更新）
+- 状态更新缺口：当前 `ExecutionQueue` 代码中没有看到明确把 status 从 pending 改成 running/failed/success 的逻辑（可能在 `PipelineRunner` 内处理；若没有，需要补齐）
+
+建议（不改变整体架构前提）：
+
+- 将轮询间隔改为可配置 env：`EXECUTION_POLL_INTERVAL_MS`（默认 30000）
+- 在真正执行前做一次 DB 原子“抢占”：仅当 status=pending 时更新为 running（并记录开始时间）；更新失败则放弃执行
+
+### 6.4 可观测性
+
+最低要求（建议后续落地到代码/日志规范）：
+
+- 日志字段：deploymentId、pipelineId、projectId、projectDir、status
+- 队列指标：pendingQueue length、runningDeployments size
+- 失败记录：捕获异常 message/stack（避免泄露敏感信息）
+
+### 6.5 安全与权限
+
+当前接口层面需要确认：
+
+- `/api/deployments` 与 `/api/deployments/:id/retry` 是否需要登录/鉴权（取决于 middleware 配置）
+- 若需要鉴权：建议限制为有项目权限的用户才能创建/重试部署
+
+## 7. 影响与权衡（Trade-offs）
+
+- 继续采用内存队列：实现简单，但天然不支持多实例并发安全
+- DB 轮询恢复：可靠性提升，但会带来额外 DB 查询压力
+
+## 8. 兼容性与迁移（Compatibility & Migration）
+
+- 文档层面不破坏现有 API
+- 若引入 status 原子抢占，需要确保旧数据/旧状态兼容（例如对历史 pending 记录仍可恢复）
+
+## 9. 测试计划（Test Plan）
+
+- 集成链路：创建 deployment -> 入队 -> 触发执行（可用假 runner）
+- 重启恢复：插入 pending 记录 -> initialize() -> 任务被 addTask
+- 重试接口：原记录存在/不存在的分支
+
+## 10. 发布计划（Rollout Plan）
+
+- 先补齐文档 + 最小日志规范
+- 再逐步落地：status 原子抢占 + 轮询间隔 env
+
+## 11. 备选方案（Alternatives Considered）
+
+- 引入 Redis 队列（BullMQ 等）：更可靠、支持多实例，但复杂度上升
+- 使用 DB 作为队列（表 + 锁/租约）：更可靠，但需要严格的并发控制
+
+## 12. 风险与开放问题（Risks & Open Questions）
+
+- Q1：`PipelineRunner` 是否负责更新 Deployment.status？如果没有，状态机应由谁维护？
+- Q2：服务是否计划多实例部署？如果是，必须补齐“抢占执行”机制
+
+## 13. 附录（Appendix）
+
+- 代码：`apps/server/libs/execution-queue.ts`
+- 控制器：`apps/server/controllers/deployment/index.ts`
+- Schema：`apps/server/prisma/schema.prisma`
--- a/docs/architecture/design-0004-execution-queue.md
+++ b/docs/architecture/design-0004-execution-queue.md
@@ -0,0 +1,166 @@
+---
+title: 设计文档 0001 - 部署执行队列与重试（基于当前实现）
+summary: 记录当前 ExecutionQueue 的行为与下一步改进方向，便于团队对齐。
+owners:
+  - team: backend
+reviewers:
+  - ops-team
+status: draft
+date: 2026-01-03
+version: 0.1.0
+related:
+  - code: apps/server/libs/execution-queue.ts
+  - code: apps/server/controllers/deployment/index.ts
+  - schema: apps/server/prisma/schema.prisma
+---
+
+# 设计文档 0001：部署执行队列与重试
+
+## 1. 背景（Context）
+
+当前服务端在启动时会初始化执行队列（`ExecutionQueue.initialize()`），用于从数据库恢复 `status=pending` 的部署任务并按顺序执行流水线。
+
+现有相关事实（来自当前代码）：
+
+- 服务启动入口：`apps/server/app.ts`
+- 路由：`/api/deployments`（创建部署后入队）与 `/api/deployments/:id/retry`（复制记录后入队）
+- 数据库：SQLite + Prisma，Deployment 存在 `status` 字段（注释标明：pending/running/success/failed/cancelled）
+- 队列实现：内存队列 `pendingQueue` + `runningDeployments` Set，并有轮询机制（默认 30 秒）把 DB 中的 pending 任务补进队列
+
+## 2. 目标（Goals）
+
+- [ ] 明确“部署任务”从创建到执行的状态流转与约束
+- [ ] 明确重试语义（retry 会创建新 deployment，而不是复用原记录）
+- [ ] 降低重复入队/重复执行的风险（幂等与并发边界清晰）
+- [ ] 让运维/排障更容易：关键日志点与可观测性清单
+
+## 3. 非目标（Non-goals）
+
+- 不引入外部消息队列（如 Redis/Kafka），仍以当前内存队列 + DB 恢复为基础
+- 不在本文直接实现大规模调度/分布式 runner（后续 ADR/设计再做）
+
+## 4. 需求与范围（Requirements & Scope）
+
+### 功能需求
+
+- 创建部署：写入一条 Deployment 记录，初始状态为 `pending`，并加入执行队列
+- 重试部署：通过 `/deployments/:id/retry` 创建一条新的 Deployment 记录（复制必要字段），并加入执行队列
+- 服务重启恢复：服务启动后能从 DB 找回仍为 `pending` 的任务并继续执行
+
+### 非功能需求
+
+- 可靠性：服务重启不会“丢任务”（pending 的任务能恢复）
+- 幂等性：避免同一个 deployment 被重复执行
+- 可观测性：能定位某次部署为何失败、何时开始/结束、队列长度
+
+## 5. 方案概览（High-level Design）
+
+当前方案核心链路如下：
+
+1) API 创建 Deployment（status=pending）
+2) `ExecutionQueue.addTask(deploymentId, pipelineId)` 入队
+3) `ExecutionQueue.processQueue()` 串行消费 `pendingQueue`
+4) `executePipeline()` 会读取 Deployment 与关联 Project，获取 `projectDir`，然后创建 `PipelineRunner` 执行
+5) 定时轮询：每 30 秒扫描 DB 中的 pending 任务，若不在 `runningDeployments` 集合则补入队列
+
+## 6. 详细设计（Detailed Design）
+
+### 6.1 接口/API 设计
+
+#### 创建部署
+
+- POST `/api/deployments`
+- 行为：创建 Deployment 后立即入队
+
+#### 重试部署
+
+- POST `/api/deployments/:id/retry`
+- 行为：读取原 deployment -> 创建新 deployment（status=pending）-> 入队
+- 语义：重试是“创建一个新的任务实例”，便于保留历史执行记录
+
+### 6.2 数据模型/数据库
+
+Deployment 当前关键字段（见 schema 注释）：
+
+- `status`: pending/running/success/failed/cancelled（目前入队依赖 pending）
+- `buildLog`: 执行日志（当前创建时写空字符串）
+- `startedAt`/`finishedAt`: 时间标记（目前 created 时 startedAt 默认 now）
+
+建议补齐/明确（文档层面约束，代码后续落地）：
+
+- 状态迁移：
+  - `pending` -> `running`（开始执行前）
+  - `running` -> `success|failed|cancelled`（结束后）
+- 幂等控制：
+  - 以 deploymentId 为“单次执行唯一标识”，同一个 deploymentId 不允许重复开始执行
+
+### 6.3 队列/轮询/并发
+
+现状：
+
+- `runningDeployments` 同时承担“已入队/执行中”的去重集合
+- `pendingQueue` 为内存 FIFO
+- 单实例串行消费（`processQueue` while 循环）
+- 轮询间隔常量 30 秒
+
+风险点（需要在文档中明确约束/后续逐步修正）：
+
+- 多实例部署：如果将来启动多个 server 实例，每个实例都可能轮询到同一条 pending 记录并执行（需要 DB 锁/租约/状态原子更新）
+- 状态更新缺口：当前 `ExecutionQueue` 代码中没有看到明确把 status 从 pending 改成 running/failed/success 的逻辑（可能在 `PipelineRunner` 内处理；若没有，需要补齐）
+
+建议（不改变整体架构前提）：
+
+- 将轮询间隔改为可配置 env：`EXECUTION_POLL_INTERVAL_MS`（默认 30000）
+- 在真正执行前做一次 DB 原子“抢占”：仅当 status=pending 时更新为 running（并记录开始时间）；更新失败则放弃执行
+
+### 6.4 可观测性
+
+最低要求（建议后续落地到代码/日志规范）：
+
+- 日志字段：deploymentId、pipelineId、projectId、projectDir、status
+- 队列指标：pendingQueue length、runningDeployments size
+- 失败记录：捕获异常 message/stack（避免泄露敏感信息）
+
+### 6.5 安全与权限
+
+当前接口层面需要确认：
+
+- `/api/deployments` 与 `/api/deployments/:id/retry` 是否需要登录/鉴权（取决于 middleware 配置）
+- 若需要鉴权：建议限制为有项目权限的用户才能创建/重试部署
+
+## 7. 影响与权衡（Trade-offs）
+
+- 继续采用内存队列：实现简单，但天然不支持多实例并发安全
+- DB 轮询恢复：可靠性提升，但会带来额外 DB 查询压力
+
+## 8. 兼容性与迁移（Compatibility & Migration）
+
+- 文档层面不破坏现有 API
+- 若引入 status 原子抢占，需要确保旧数据/旧状态兼容（例如对历史 pending 记录仍可恢复）
+
+## 9. 测试计划（Test Plan）
+
+- 集成链路：创建 deployment -> 入队 -> 触发执行（可用假 runner）
+- 重启恢复：插入 pending 记录 -> initialize() -> 任务被 addTask
+- 重试接口：原记录存在/不存在的分支
+
+## 10. 发布计划（Rollout Plan）
+
+- 先补齐文档 + 最小日志规范
+- 再逐步落地：status 原子抢占 + 轮询间隔 env
+
+## 11. 备选方案（Alternatives Considered）
+
+- 引入 Redis 队列（BullMQ 等）：更可靠、支持多实例，但复杂度上升
+- 使用 DB 作为队列（表 + 锁/租约）：更可靠，但需要严格的并发控制
+
+## 12. 风险与开放问题（Risks & Open Questions）
+
+- Q1：`PipelineRunner` 是否负责更新 Deployment.status？如果没有，状态机应由谁维护？
+- Q2：服务是否计划多实例部署？如果是，必须补齐“抢占执行”机制
+
+## 13. 附录（Appendix）
+
+- 代码：`apps/server/libs/execution-queue.ts`
+- 控制器：`apps/server/controllers/deployment/index.ts`
+- Schema：`apps/server/prisma/schema.prisma`
--- a/docs/architecture/design-0005-refactor-deply.md
+++ b/docs/architecture/design-0005-refactor-deply.md
@@ -0,0 +1,127 @@
+---
+title: 设计文档 0005 - 部署流程重构（移除稀疏检出 & 环境预设）
+summary: 调整部署相关能力：移除稀疏检出；将部署环境从创建时输入改为在项目设置中预设。
+owners:
+	- team: backend
+reviewers:
+	- team: frontend
+status: draft
+date: 2026-01-03
+version: 0.1.0
+related:
+	- docs: docs/api/endpoints.md
+	- schema: apps/server/prisma/schema.prisma
+---
+
+# 设计文档 0005：部署流程重构（移除稀疏检出 & 环境预设）
+
+## 1. 背景（Context）
+
+当前部署流程在“项目详情页发起部署”时包含“稀疏检出（sparse checkout）”表单项，并且流水线模板中也包含与稀疏检出相关的逻辑。
+
+另外，部署时需要指定环境变量（例如 env），但目前是在“创建部署”时临时输入/选择。随着项目数量增加，这种方式容易造成不一致与误操作。
+
+## 2. 目标（Goals）
+
+- [ ] 移除项目详情页部署表单中的“稀疏检出”相关输入项
+- [ ] 移除流水线模板中与稀疏检出相关的代码逻辑（后端模板/生成逻辑）
+- [ ] 将“部署环境（env）”从创建部署时指定，调整为在“项目设置”中提前预设
+- [ ] 创建部署时仍需要选择/指定环境，但选项来源于项目设置中的预设项
+
+## 3. 非目标（Non-goals）
+
+- 不新增多维度环境变量管理（仅覆盖本次提到的 env 单项预设）
+- 不在本次引入复杂的环境权限、审批流
+
+## 4. 需求与范围（Requirements & Scope）
+
+### 4.1 移除稀疏检出
+
+#### 用户侧
+
+- 项目详情页发起部署时：不再展示/提交稀疏检出字段
+
+#### 系统侧
+
+- 流水线模板：移除任何基于稀疏检出路径的生成/执行逻辑
+
+> 说明：当前 DB 中 Deployment 仍存在 `sparseCheckoutPaths` 字段（见 `schema.prisma`），本次需求仅明确“功能不再需要”。字段是否删除/迁移由本设计后续章节确定。
+
+### 4.2 部署环境 env 改为项目设置预设
+
+#### 核心约束
+
+- 环境变量预设需要支持多选、单选、输入框这几种类型
+- 在项目设置中新增可配置项（预设项）：
+  例如：指定env 环境变量
+	- 类型：单选（single select）
+	- key：`env`，value 及时部署是选中的候选项的值
+	- options：`staging`（测试环境）、`production`（生产环境）
+
+#### 行为
+
+- 创建部署时仍需指定环境（env），但：
+	- 不再由用户自由输入
+	- 只允许从该项目预设的 options 中选择
+
+## 5. 影响面（Impact）
+
+### 5.1 前端
+
+- 项目详情页部署表单：移除“稀疏检出”相关 UI 与字段提交
+- 项目设置页：新增“环境预设（env）”配置入口（单选 + 选项 staging/production）
+- 创建部署交互：环境选项从项目设置读取（不再硬编码/临时输入）
+
+### 5.2 后端
+
+- 部署创建接口：校验 env 必须来自项目预设（避免非法 env）
+- 流水线模板：移除稀疏检出相关的模板字段/生成逻辑
+
+### 5.3 数据库
+
+- 需要新增“项目设置/项目配置”承载 env 预设（落库方案待定）
+- 既有 Deployment 的 `sparseCheckoutPaths` 字段：后续决定是否保留（兼容历史）或迁移删除
+
+## 6. 兼容性与迁移（Compatibility & Migration）
+
+- 对历史部署记录：
+	- 若存在 `sparseCheckoutPaths`，不影响查询展示，但新建部署不再写入该字段
+- 对创建部署：
+	- 若项目未配置 env 预设：创建部署应失败并提示先到项目设置配置（或提供默认值策略，待确认）
+
+## 7. 测试要点（Test Plan）
+
+- 前端：
+	- 项目详情页部署表单不再出现稀疏检出项
+	- 项目设置可保存 env 预设（单选）并在创建部署时正确展示
+- 后端：
+	- 创建部署：env 不在项目预设 options 内时应拒绝
+	- 流水线模板：移除稀疏检出后仍能正常创建并执行
+
+## 8. 实施状态（Implementation Status）
+
+### 已完成（后端）
+
+- ✅ Prisma Schema：在 Project 表添加 `envPresets` 字段（String? 类型，存储 JSON）
+- ✅ 移除部署创建/重试接口中的 `sparseCheckoutPaths` 写入
+- ✅ 在部署创建接口添加环境校验：验证 env 是否在项目 envPresets 的 options 中
+- ✅ 更新 project DTO 和 controller 支持 envPresets 读写
+- ✅ 移除 pipeline-runner 中的 `SPARSE_CHECKOUT_PATHS` 环境变量
+- ✅ 生成 Prisma Client
+
+### 已完成（前端）
+
+- ✅ 创建 EnvPresetsEditor 组件（支持单选、多选、输入框类型）
+- ✅ 在 CreateProjectModal 和 EditProjectModal 中集成环境预设编辑器
+- ✅ 从 DeployModal 移除稀疏检出表单项
+- ✅ 在 DeployModal 中从项目 envPresets 读取环境选项并展示
+- ✅ 移除 DeployModal 中的动态环境变量列表（envVars Form.List）
+- ✅ 从类型定义中移除 sparseCheckoutPaths 字段
+- ✅ 在项目详情页项目设置 tab 中添加环境变量预设的查看和编辑功能
+
+### 待定问题
+
+- Q1：项目设置存储方式 → **已决定**：使用 Project.envPresets JSON 字段
+- Q2：未配置 env 预设的默认行为 → **已实现**：若配置了预设则校验，否则允许任意值（向后兼容）
+- Q3：Deployment.sparseCheckoutPaths 字段 → **已决定**：保留字段（兼容历史），但新建部署不再写入
+
--- a/docs/changelogs/CHANGELOG.md
+++ b/docs/changelogs/CHANGELOG.md
@@ -0,0 +1,9 @@
+# Changelog
+
+所有 notable 更改应在此记录。遵循 Keep a Changelog 格式。
+
+## [Unreleased]
+- 初始文档目录建立。
+
+## [1.0.0] - 2026-01-03
+- 初始发布
--- a/docs/development/setup.md
+++ b/docs/development/setup.md
@@ -0,0 +1,88 @@
+---
+title: 开发与本地环境搭建
+summary: 针对本项目的本地开发、数据库与调试指南。
+owners:
+  - team: backend
+status: stable
+---
+
+# 开发与本地环境搭建
+
+## 1. 安装依赖
+
+建议使用 `pnpm` 管理工作区依赖：
+
+```bash
+# 在仓库根
+pnpm install
+```
+
+或者只在 server 子包安装：
+
+```bash
+cd apps/server
+pnpm install
+```
+
+## 2. 生成 Prisma Client
+
+```bash
+cd apps/server
+npx prisma generate
+```
+
+如果需要执行迁移（开发场景）：
+
+```bash
+npx prisma migrate dev --name init
+```
+
+数据库：项目使用 SQLite（见 `apps/server/prisma/schema.prisma`），迁移会在本地创建 `.db` 文件。
+
+## 3. 启动服务
+
+并行启动 workspace 中所有 dev 脚本（推荐）：
+
+```bash
+pnpm dev
+```
+
+或单独启动 server：
+
+```bash
+cd apps/server
+pnpm dev
+```
+
+服务默认端口：`3001`。如需修改：
+
+```bash
+PORT=4000 pnpm dev
+```
+
+## 4. 常见开发命令
+
+- 运行测试脚本（仓库自带）：
+
+```bash
+cd apps/server
+node test.js
+```
+
+- TypeScript 类型检查（本地可使用 `tsc`）：
+
+```bash
+npx tsc --noEmit
+```
+
+## 5. 环境变量与第三方集成
+
+常见 env：`GITEA_URL`, `GITEA_CLIENT_ID`, `GITEA_REDIRECT_URI`, `PORT`, `NODE_ENV`。
+
+登录采用 Gitea OAuth，未配置时某些 auth 接口会返回 401，需要先登录获取 session。
+
+## 6. 运行与调试要点
+
+- 代码通过装饰器注册路由（见 `apps/server/decorators/route.ts` 与 `apps/server/libs/route-scanner.ts`）。
+- Prisma client 生成路径：`apps/server/generated`。
+- 若变更 Prisma schema，请执行 `prisma generate` 并更新迁移。
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -0,0 +1,79 @@
+---
+title: 快速开始
+summary: 本文档介绍如何在本地启动与运行项目的基础步骤。
+tags: [getting-started]
+owners:
+  - team: backend
+status: stable
+version: 1.0.0
+---
+
+# 快速开始
+
+## 前置条件
+
+- Node.js >= 18
+- pnpm
+- 克隆权限（或访问仓库）
+
+## 克隆与依赖安装
+
+```bash
+git clone <repo-url>
+cd foka-ci
+pnpm install
+```
+
+说明：仓库使用 pnpm workspace，根目录脚本 `pnpm dev` 会并行启动工作区内的 `dev` 脚本。
+
+## 运行服务（开发）
+
+- 从仓库根（并行运行所有 dev 脚本）：
+
+```bash
+pnpm dev
+```
+
+- 单独运行 server：
+
+```bash
+cd apps/server
+pnpm install
+pnpm dev       # 等同于: tsx watch ./app.ts
+```
+
+服务器默认监听端口 `3001`（可通过 `PORT` 环境变量覆盖）。API 前缀为 `/api`。
+
+## Prisma 与数据库
+
+项目使用 SQLite（见 `apps/server/prisma/schema.prisma`）。如果需要生成 Prisma Client 或运行迁移：
+
+```bash
+cd apps/server
+npx prisma generate
+npx prisma migrate dev --name init   # 本地开发使用
+```
+
+生成的 Prisma Client 位于 `apps/server/generated`（由 schema 中的 generator 指定）。
+
+## 环境变量（常用）
+
+- `GITEA_URL`、`GITEA_CLIENT_ID`、`GITEA_REDIRECT_URI`：用于 OAuth 登录（Gitea）。
+- `PORT`：服务监听端口，默认 `3001`。
+- `NODE_ENV`：环境（development/production）。
+
+将敏感值放入 `.env`（不要将 `.env` 提交到仓库）。
+
+## 运行脚本与测试
+
+```bash
+cd apps/server
+node test.js       # 运行仓库自带的简单测试脚本
+```
+
+## 其他说明
+
+- 文档目录位于 `docs/`，设计模板在 `docs/.meta/templates/`。
+- API 路由由装饰器注册，路由前缀为 `/api`，在 `apps/server/middlewares/router.ts` 中可查看。
+
+更多开发细节请参见 `docs/development/setup.md` 与 `docs/api/endpoints.md`。
--- a/docs/index.md
+++ b/docs/index.md
@@ -0,0 +1,22 @@
+---
+title: 项目文档总览
+summary: 项目文档的导航页，指向快速开始、架构、API、运维等部分。
+tags: [overview]
+owners:
+  - team: backend
+status: stable
+version: 1.0.0
+---
+
+# 文档总览
+
+欢迎来到项目文档。下列是常用文档的入口：
+
+- Getting Started: ./getting-started.md
+- Architecture: ./architecture/adr-0001-service-design.md
+- API: ./api/README.md
+- Runbooks: ./runbooks/incident-response.md
+- Onboarding: ./onboarding/new-hire.md
+- Changelog: ./changelogs/CHANGELOG.md
+
+维护说明：请在变更同时更新 `owners` 与 `version`，并通过 PR 提交。
--- a/docs/onboarding/new-hire.md
+++ b/docs/onboarding/new-hire.md
@@ -0,0 +1,13 @@
+---
+title: 新成员入职指南
+owners:
+  - people-team
+status: draft
+---
+
+# 新成员入职快速清单
+
+1. 获取公司邮箱与账号
+2. 克隆仓库并运行 `pnpm install`
+3. 阅读 `docs/getting-started.md` 与 `docs/architecture` 中关键 ADR
+4. 约见导师并完成第一次 code walkthrough
--- a/docs/runbooks/incident-response.md
+++ b/docs/runbooks/incident-response.md
@@ -0,0 +1,28 @@
+---
+title: 事故响应 Runbook
+summary: 处理生产事故的步骤和联系方式。
+owners:
+  - ops-team
+status: stable
+---
+
+# 事故响应（Incident Response）
+
+## 1. 识别与分级
+
+- P0: 系统不可用或数据安全泄露
+- P1: 主要功能严重受损
+
+## 2. 通知
+
+- 联系人：`on-call@company.example`，电话：+86-10-12345678
+
+## 3. 暂时性缓解
+
+- 回滚最近的部署
+- 启用备用服务
+
+## 4. 根因分析与恢复
+
+- 记录时间线
+- 生成 RCA 并在 72 小时内发布