# Gitea 集成

对接已有的自建 Gitea 实例，作为所有被管理项目的统一 git 后端。接入包「增配档」的核心。

## 风筝线模型（炼境与 Gitea 的关系）

🪁 **风筝 = Gitea 本体**（git 存储 + CI 执行）：独立部署、独立运行，炼境**不托管其进程、不背运维**。
🧵 **线 = 炼境的掌控**（控制面）：炼境是**唯一持线人**——Gitea 连接/token 统一存炼境，建仓/关联/迁移/配置 lefthook&CI 的操控全经炼境，子项目对 Gitea 的动作都从它手里过。
👀 **关注风筝的动态 = 观测面**（飞轮燃料）：炼境持续感知每个子项目 ↔ Gitea 的连接动态（push 的 commit type/scope、PR、CI 三阶段、review、停滞项目）。

> 「线」≠ 松散 API 对接：炼境是**主动掌控者**而非被动客户端。风筝越多 → 线越多 → 动态越丰富 → 飞轮越强（契合核心愿景）。

## 其他边界

- 替代炼境现有 GitHub 能力：`github-auth` / `github-publish` 已冻结，`cicd.rs` 的 GitHub Actions 生成改造为 Gitea Actions
- 炼境自身仓库也迁 Gitea（发布产物仍走 OSS updater 不变）

## 参考实现

`enterprise-system` 已趟通完整链路，属「照搬」而非「从零探索」：
- Gitea origin（`git.yljt.info`）+ Gitee 镜像（备份）
- lefthook 强制 conventional commit + typecheck（pre-commit）
- Gitea Actions 三阶段 CI：静态检查 → 测试（DeepSeek-V3 自修）→ PR code review（DeepSeek）
- Gitea Actions 语法兼容 GitHub Actions，迁移成本低

> 详见 `E:/code-project/enterprise-system/docs/ai-context/git-workflow.md` 与 `AGENTS.md`。

## 架构设计（2026-06-30 /architect）

### 实现策略

**webhook 接收端**：扩展已有 MCP Server（Axum，端口 27190），添加 `POST /webhook/gitea/:project_id` 路由。零新依赖，复用端口和进程。

**HTTP 客户端**：`ureq`（Cargo.toml 已有，github.rs 已有使用范例），调 Gitea API v1。

**数据表**：新增 `gitea_instances`（实例管理）+ `gitea_repos`（项目-仓库绑定）。

```sql
CREATE TABLE IF NOT EXISTS gitea_instances (
    id           TEXT PRIMARY KEY,
    name         TEXT NOT NULL,
    url          TEXT NOT NULL,           -- https://gitea.myserver.com
    access_token TEXT NOT NULL,
    is_default   INTEGER NOT NULL DEFAULT 0,
    created_at   TEXT DEFAULT (datetime('now'))
);

CREATE TABLE IF NOT EXISTS gitea_repos (
    id              TEXT PRIMARY KEY,
    instance_id     TEXT NOT NULL REFERENCES gitea_instances(id) ON DELETE CASCADE,
    project_id      TEXT NOT NULL,        -- blueprint_buffs.project_id（UUID）
    gitea_owner     TEXT NOT NULL,
    gitea_repo_name TEXT NOT NULL,
    clone_url       TEXT,
    webhook_secret  TEXT,                 -- HMAC-SHA256 secret
    webhook_id      INTEGER,              -- Gitea 返回的 hook ID
    linked_at       TEXT DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX IF NOT EXISTS idx_gitea_repos_project ON gitea_repos(project_id);
```

**webhook 流程**：
```
Gitea push → POST /webhook/gitea/:project_id
  1. 从 gitea_repos 查 webhook_secret
  2. HMAC-SHA256 验签 X-Gitea-Signature-256
  3. 解析 payload.commits[]（sha / message / timestamp）
  4. 批量 record_commit(project_id, sha, message, date)
  5. 返回 200 OK；验签失败记 log_event
```

**网络说明**：Gitea 服务器需能访问宿主机 `{ip}:27190`（MCP 端口）。UI 显示可复制的 webhook 回调地址，用户自行确认网络可达。

---

## 任务卡（concept，待 /architect）

### 💭 Gitea API 对接（握线基础）
- status: concept
- complexity: L
- acceptance: TBD —— 建仓/关联、推送、读 CI 状态、读 PR review 结果

### 💭 观测面：Gitea webhook 接入（持线人感知动态）
- status: concept
- complexity: L
- files: src-tauri/src/mcp_server.rs（内嵌 HTTP server 加 webhook 端点）, src-tauri/src/commands/blueprint.rs
- acceptance: TBD —— 复用炼境内嵌 HTTP server 新增 Gitea webhook 接收端点；实时接住各子项目 push/PR/CI/review 事件 → 解析 conventional commit（对接 flywheel-intelligence 的 L0 解析层）→ 写飞轮快照 + 刷新连接动态；webhook 不可达时降级为定时轮询 Gitea API

### 💭 Gitea Actions workflow 生成
- status: concept
- complexity: M
- files: src-tauri/src/commands/cicd.rs（改造）
- acceptance: TBD —— 生成 Gitea Actions 三阶段 CI 模板（语法兼容 GitHub Actions）

### 💭 DeepSeek CI review 集成（可选插件）
- status: concept
- complexity: L
- acceptance: TBD —— 静态检查 + 测试自修 + PR review；作为复杂项目可选增配，不进基线档

### 💭 旧项目 GitHub → Gitea 迁移
- status: concept
- complexity: M
- acceptance: TBD —— remote 切换 + 推送，安全增量，不丢历史

---

## 任务卡（可执行，拆自 2026-06-30 /architect）

### ✅ G1. DB schema + Gitea 实例 CRUD
- status: done
- complexity: M
- files: src-tauri/src/db.rs, src-tauri/src/commands/gitea.rs, src-tauri/src/lib.rs, src/lib/commands.ts
- acceptance: gitea_instances + gitea_repos 表建好（migrate）；save/list/delete/test_connection 命令可调；test_connection 调 GET /api/v1/user 返回 Gitea 用户名验证 token 有效性

### 🔵 G2. 仓库创建 / 迁移 / 绑定
- status: in_progress
- complexity: M
- depends: G1
- files: src-tauri/src/commands/gitea.rs, src/lib/commands.ts
- acceptance: gitea_create_repo 调 Gitea API 建仓后写 gitea_repos；gitea_migrate_repo 能从 GitHub/GitLab 迁移仓库到 Gitea；gitea_link_repo 绑定已有仓库；命令失败返回可读错误

### 📋 G3. Webhook 接收端（MCP Server 扩展）
- status: todo
- complexity: M
- depends: G1
- files: src-tauri/src/mcp_server.rs
- acceptance: POST /webhook/gitea/:project_id 路由上线；HMAC-SHA256 验签通过后解析 commits 数组批量写 commit_metrics；验签失败记 log_event；单元测试覆盖 parse_push_payload + hmac_verify

### 🔵 G4. Webhook 注册命令
- status: in_progress
- complexity: M
- depends: G2, G3
- files: src-tauri/src/commands/gitea.rs, src/lib/commands.ts
- acceptance: gitea_setup_webhook 生成随机 secret，调 Gitea API POST /repos/:owner/:repo/hooks 注册（events=push），写 webhook_secret + webhook_id 到 gitea_repos；gitea_unlink_repo 清理绑定

### 📋 G5. Gitea 治理面板 UI
- status: todo
- complexity: M
- depends: G1, G2, G3, G4
- files: src/components/dashboard/GiteaPanel.tsx, src/components/dashboard/BlueprintModal.tsx
- acceptance: 治理面板新增"Gitea"区块；可添加/测试/删除实例；显示已绑定仓库列表（仓库名/webhook 状态）；操作：新建仓库、迁移、绑定已有、设置 webhook；显示可复制的 webhook 回调地址