fix: 重新生成 docs

docs/README.md

@@ -0,0 +1,22 @@
+# MiniCI 文档中心
+
+欢迎查阅 MiniCI 开发者文档。本项目是一个轻量级的自研 CI 系统。
+
+## 目录索引
+
+- [系统架构](./architecture.md) - 核心设计与模块划分
+- [决策记录 (ADR)](./decisions/0001-tech-stack.md) - 技术选型背后的逻辑
+- [约束与禁区](./constraints.md) - 开发中不可触碰的红线
+- [编码规范](./conventions.md) - 风格与最佳实践
+- [踩坑指南](./pitfalls.md) - 已解决的问题与易错点
+- [当前进度](./status.md) - 项目现状与待办
+- [AI 助手说明](./ai.md) - 专门为 coding agent 准备的作业指南
+
+## 快速上手
+
+```bash
+pnpm install
+pnpm dev
+```
+
+项目访问：前端 `localhost:3000` (Rsbuild)，后端 `localhost:3001` (Koa)。

docs/ai.md

@@ -0,0 +1,22 @@
+# AI 助手作业指南 (ai.md)
+
+你好，Agent！在处理 MiniCI 项目时，请遵循以下原则：
+
+## 1. 增加新 API 的步骤
+
+1. 在 `controllers/` 对应模块下创建/修改 `dto.ts` 定义输入。
+2. 在 `index.ts` 中编写类，使用 `@Controller` 和 `@Post/Get` 等装饰器。
+3. 如果涉及数据库，修改 `schema.prisma` 并运行 `npx prisma db push`。
+4. 在前端 `pages/` 对应的 `service.ts` 中添加调用方法。
+
+## 2. 核心逻辑位置
+
+- 如果要修改 **流水线如何运行**，请看 `apps/server/runners/pipeline-runner.ts`。
+- 如果要修改 **任务调度**，请看 `apps/server/libs/execution-queue.ts`。
+- 如果要修改 **路由扫描**，请看 `apps/server/libs/route-scanner.ts`。
+
+## 3. 交互规范
+
+- 前端请求请使用 `@shared` 别名导入 `net` 实例。
+- 始终保持代码简洁，优先使用现有的 `libs` 工具类。
+- 修改代码后，务必确认 `pnpm dev` 是否能正常编译通过。

docs/architecture.md

@@ -0,0 +1,29 @@
+# 系统架构
+
+## 1. 概览
+
+MiniCI 采用典型的 **Monorepo** 架构，前端 React 配合后端 Koa，数据持久化使用 SQLite。
+
+## 2. 核心模块
+
+### 2.1 后端 (apps/server)
+
+- **Route System**: 基于 TC39 装饰器的自动扫描路由。
+- **Execution Queue**: 单例模式的执行队列，控制并发并支持任务持久化恢复。
+- **Pipeline Runner**: 核心执行逻辑，利用 `zx` 在独立的工作目录下运行 Shell 脚本。
+- **Data Access**: Prisma ORM 提供类型安全的数据访问。
+
+### 2.2 前端 (apps/web)
+
+- **Build Tool**: Rsbuild (基于 Rspack)，提供极速的开发体验。
+- **UI Framework**: React 19 + Arco Design。
+- **State Management**: Zustand 实现轻量级全局状态。
+
+## 3. 部署流 (Pipeline Flow)
+
+1. 用户触发部署 -> 创建 `Deployment` 记录 (Status: pending)。
+2. `ExecutionQueue` 捕获新任务 -> 实例化 `PipelineRunner`。
+3. `GitManager` 准备工作目录 (`git clone` 或 `git pull`)。
+4. `PipelineRunner` 逐个执行 `Step` 脚本。
+5. 执行过程中实时更新 `Deployment.buildLog`。
+6. 完成后更新状态为 `success` 或 `failed`。

docs/constraints.md

@@ -0,0 +1,20 @@
+# 约束与禁区
+
+## 1. 路由规范
+
+- **禁止** 在 `app.ts` 中手动编写 `router.get/post`。
+- **必须** 使用 `@Controller` 和 `@Get/Post` 装饰器，并放在 `controllers/` 目录下。
+
+## 2. 数据库安全
+
+- **禁止** 绕过 Prisma 直接操作数据库文件。
+- **禁止** 在生产环境中手动修改 `dev.db`。
+
+## 3. 环境变量
+
+- **禁区**: 严禁将敏感 Token 或密钥直接硬编码在代码或 `schema.prisma` 中。
+- 请使用 `.env` 文件配合 `dotenv` 加载。
+
+## 4. 依赖管理
+
+- **禁止** 混合使用 npm/yarn，必须统一使用 `pnpm`。

docs/conventions.md

@@ -0,0 +1,49 @@
+# 编码规范
+
+## 1. 命名习惯
+
+- **前端组件**: PascalCase (如 `ProjectCard.tsx`)。
+- **后端文件**: kebab-case (如 `route-scanner.ts`)。
+- **DTO**: 文件名为 `dto.ts`，类名为 `XxxDTO`。
+
+## 2. 代码组织
+
+web 项目代码组织如下：
+
+```yaml
+├── web/
+│   ├── pages/
+│   │   ├── components/        # 页面组件
+│   │   ├── index.tsx          # 页面入口组件
+│   │   ├── service.ts         # 当前页面使用到的 api 请求方法和纯函数
+│   │   ├── types.ts           # 当前页面使用到的类型定义
+│   │   └── ...
+│   └── hooks/                 # 通用 hooks （不止一个组件引用）
+│   └── stores/                # 全局状态
+│   └── utils/                 # 通用工具类
+│   └── styles/                # 全局样式
+│   └── assets/                # 静态资源
+│   └── components/            # 通用组件
+│   └── types/                 # 全局类型定义
+│   └── ...
+```
+
+## 3. 响应格式
+
+- 后端统一返回 `APIResponse<T>` 结构：
+
+  ```json
+  { "code": 0, "data": {}, "message": "success", "timestamp": 12345678 }
+  ```
+
+- 由 `RouteScanner` 中的 `wrapControllerMethod` 自动封装。
+
+## 3. 异步处理
+
+- 统一使用 `async/await`。
+- 后端错误通过抛出异常由 `exception.ts` 中间件统一捕获。
+
+## 4. 格式化
+
+- 使用 Biome 进行 Lint 和 Format。
+- 提交代码前建议运行 `pnpm --filter web format`。

docs/decisions/0001-tech-stack.md

@@ -0,0 +1,14 @@
+# ADR 0001: 技术选型
+
+## 背景
+需要构建一个轻量级、易扩展且易于本地部署的 CI 系统。
+
+## 决策
+- **语言**: 全栈 TypeScript，确保模型定义在前后端的一致性。
+- **后端框架**: Koa。相比 Express 更加轻量，利用 async/await 处理异步中间件更优雅。
+- **数据库**: SQLite。CI 系统通常是单机或小规模使用，SQLite 无需独立服务，运维成本极低。
+- **执行工具**: `zx`。相比原生的 `child_process`，`zx` 处理 Shell 交互更加直观和安全。
+
+## 后果
+- 优势：开发效率极高，部署简单。
+- 挑战：SQLite 在极高并发写入（如数百个任务同时输出日志）时可能存在性能瓶颈。

docs/decisions/0002-state.md

@@ -0,0 +1,15 @@
+# ADR 0002: 状态管理
+
+## 背景
+需要在前端管理用户信息、全局配置以及各页面的复杂 UI 状态。
+
+## 决策
+- **全局状态**: 使用 Zustand。
+- **理由**: 
+    - 相比 Redux 模板代码极少。
+    - 相比 Context API 性能更好且不引起全量重绘。
+    - 符合 React 19 的 Concurrent 模式。
+- **持久化**: 对关键状态（如 Token）使用 Zustand 的 persist 中间件。
+
+## 后果
+状态管理逻辑高度内聚在 `apps/web/src/stores` 中。

docs/decisions/0003-pipeline-execution.md

@@ -0,0 +1,12 @@
+# ADR 0003: 流水线执行策略
+
+## 背景
+如何确保流水线执行的隔离性与可靠性。
+
+## 决策
+- **工作目录**: 每个项目在服务器上拥有独立的 `projectDir`。
+- **执行器**: 采用线性执行。目前不支持多步骤并行，以确保日志顺序的确定性。
+- **队列**: 使用内存队列 + 数据库扫描实现。系统重启后能通过数据库中的 `pending` 状态恢复任务。
+
+## 后果
+目前的隔离级别为目录级。未来可能需要引入 Docker 容器化执行以增强安全性。

docs/pitfalls.md

@@ -0,0 +1,21 @@
+# 踩坑指南 (Pitfalls)
+
+## 1. Prisma 客户端生成
+
+- **现象**: 修改 `schema.prisma` 后代码报错找不到类型。
+- **解决**: 需要在 `apps/server` 下运行 `pnpm prisma generate`。本项目将生成的代码放在了 `generated/` 目录而非 node_modules，请注意引用路径。
+
+## 2. zx 环境变量继承
+
+- **现象**: 在流水线脚本中找不到 `node` 或 `git` 命令。
+- **解决**: `PipelineRunner` 在调用 `zx` 时必须手动扩展 `env: { ...process.env, ...userEnv }`，否则会丢失系统 PATH。
+
+## 3. Koa BodyParser 顺序
+
+- **现象**: 获取不到 `ctx.request.body`。
+- **解决**: `koa-bodyparser` 中间件必须在 `router` 中间件之前注册。
+
+## 4. SQLite 并发写入
+
+- **现象**: 部署日志极快输出时偶发 `SQLITE_BUSY`。
+- **解决**: 适当增加 `better-sqlite3` 的 busy timeout。

docs/status.md

@@ -0,0 +1,19 @@
+# 当前进度 (Status)
+
+## 已完成 ✅
+
+- 基础 Monorepo 框架搭设
+- TC39 装饰器路由系统
+- 项目管理 (CRUD)
+- 基础流水线执行流程 (Git Clone -> zx Run -> Log Update)
+- 前端项目列表与详情页预览
+
+## 进行中 🚧
+
+- 部署记录的分页查询优化
+
+## 待办 📅
+
+- [ ] Gitea Webhook 自动触发
+- [ ] 用户权限管理 (RBAC)
+- [ ] 日志实时 Websocket 推送