rui-docs/ai-skills/gitea-api.md

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 文件（避免转义问题）

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

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 仓库）：

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"

返回示例：

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

获取 Issue

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

列出仓库所有 Issue

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

回复 Issue 评论

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

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 作为远程名称：

git push origin main

注意事项

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