# Gitea API 使用指南

## Token 位置

```
~/.config/gitea/token
```

## 仓库与 API 地址

| 仓库 | Git 地址 | API Issue 端点 |
|------|---------|---------------|
| rui-framework | `ssh://git@git.vifo.cc:222/rui/rui-framework.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-framework/issues` |
| rui-cashier | `ssh://git@git.vifo.cc:222/rui/rui-cashier.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-cashier/issues` |
| rui-payment | `ssh://git@git.vifo.cc:222/rui/rui-payment.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-payment/issues` |
| rui-frontend | `ssh://git@git.vifo.cc:222/rui/rui-frontend.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-frontend/issues` |
| rui-docs | `ssh://git@git.vifo.cc:222/rui/rui-docs.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-docs/issues` |

## 工单路由规则

AI 必须根据**问题所属模块**向正确的仓库提交 Issue，禁止向错误仓库提交。

### 按问题类型路由

| 问题类型 | 提交到 | 示例 |
|---------|-------|------|
| 框架能力缺失（公共工具、BaseEntity、安全、Feign 等） | rui-framework | 需要新增分布式锁工具类 |
| 系统管理、用户管理接口 | rui-framework | 用户编辑接口密码字段处理 |
| 收银业务逻辑 | rui-cashier | 收银台需要新增挂单功能 |
| 支付业务逻辑 | rui-payment | 支付回调需要新增渠道 |
| 前端页面、UI 组件 | rui-frontend | 收银页面需要新增弹窗 |
| 文档、规范、技能 | rui-docs | Nacos 配置规范需要补充 |

### 按 API URL 前缀路由

| URL 前缀 | 所属仓库 | 说明 |
|---------|---------|------|
| /system/* | rui-framework | 系统管理、基础框架 |
| /user/* | rui-framework | 用户管理、权限相关 |
| /cashier/* | rui-cashier | 收银系统 |
| /pay/*, /payment/* | rui-payment | 支付系统 |
| 其他 | 按业务模块判断 | 参考项目文档或询问用户 |

### 跨仓库协作原则

1. **当前仓库能解决的问题**：直接处理，不提 Issue
2. **需要其他仓库配合**：向目标仓库提 Issue，并在当前仓库提交中注明 对应工单 {owner}/{repo}#{number}
3. **不确定归属**：先向用户确认，不要盲目提交

## 创建 Issue（工单）

**步骤 1**: 准备 JSON 文件（避免转义问题）

```bash
cat > /tmp/issue.json << 'EOF'
{
  "title": "[API-REQ] 简要描述所需接口",
  "body": "## 接口地址\n\nPUT /xxx/xxx\n\n## 功能描述\n\n描述需要什么功能\n\n## 期望行为\n\n1. ...\n2. ...\n\n## 当前问题\n\n- ...\n\n## 前端使用场景\n\n描述为什么需要这个接口\n\n## 优先级\n\n高/中/低"
}
EOF
```

**步骤 2**: 调用 Gitea API 创建 Issue

```bash
TOKEN=$(cat ~/.config/gitea/token)
curl -s -X POST \
  -H "Authorization: token ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/issue.json \
  "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues"
```

**示例**（提交到 rui-framework 仓库）：

```bash
TOKEN=$(cat ~/.config/gitea/token)
curl -s -X POST \
  -H "Authorization: token ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/issue.json \
  "https://git.vifo.cc/api/v1/repos/rui/rui-framework/issues"
```

**返回示例**：
```json
{
  "id": 7,
  "number": 2,
  "title": "[API-REQ] 用户编辑接口密码字段处理优化",
  "html_url": "https://git.vifo.cc/rui/rui-framework/issues/2",
  "state": "open"
}
```

## 获取 Issue

```bash
TOKEN=$(cat ~/.config/gitea/token)
curl -s -H "Authorization: token ${TOKEN}" \
  "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}"
```

## 列出仓库所有 Issue

```bash
TOKEN=$(cat ~/.config/gitea/token)
curl -s -H "Authorization: token ${TOKEN}" \
  "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues?state=open"
```

## 回复 Issue 评论

```bash
TOKEN=$(cat ~/.config/gitea/token)
curl -s -X POST \
  -H "Authorization: token ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"body": "✅ 已完成\n\n完成内容..."}' \
  "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}/comments"
```

## 关闭 Issue

```bash
TOKEN=$(cat ~/.config/gitea/token)
curl -s -X PATCH \
  -H "Authorization: token ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"state": "closed"}' \
  "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}"
```

## 常用端点

| 操作 | 方法 | 端点 |
|------|------|------|
| 创建 Issue | POST | /api/v1/repos/{owner}/{repo}/issues |
| 获取 Issue | GET | /api/v1/repos/{owner}/{repo}/issues/{id} |
| 列出 Issue | GET | /api/v1/repos/{owner}/{repo}/issues?state=open |
| 创建评论 | POST | /api/v1/repos/{owner}/{repo}/issues/{id}/comments |
| 关闭 Issue | PATCH | /api/v1/repos/{owner}/{repo}/issues/{id} |
| 获取仓库 | GET | /api/v1/repos/{owner}/{repo} |

## Git 推送命令

所有仓库统一使用 `origin` 作为远程名称：

```bash
git push origin main
```

## 注意事项

1. **JSON 内容**: 建议使用文件方式（-d @file.json）避免转义问题
2. **Labels**: 创建 Issue 时 labels 参数需要传入 ID 数组，不是字符串数组
3. **返回字段**: number 是 Issue 编号，id 是内部 ID
4. **owner 统一为 rui**: 所有仓库都在 rui 组织下