vifo
c7244b3b87
- gitea-api.md: 补全 5 个仓库地址、工单路由表、URL 前缀映射、remote 名称、关闭 Issue API - issue-workflow.md: 增加工单归属判断、跨仓库提工单流程、列出/关闭工单 API
170 lines
5.4 KiB
Markdown
170 lines
5.4 KiB
Markdown
# Gitea API 使用指南
|
||
|
||
## Token 位置
|
||
|
||
```
|
||
~/.config/gitea/token
|
||
```
|
||
|
||
## 仓库与 API 地址
|
||
|
||
| 仓库 | Git 地址 | API Issue 端点 |
|
||
|------|---------|---------------|
|
||
| rui-framework | `ssh://git@git.dev.vifo.cc:222/rui/rui-framework.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-framework/issues` |
|
||
| rui-cashier | `ssh://git@git.dev.vifo.cc:222/rui/rui-cashier.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-cashier/issues` |
|
||
| rui-payment | `ssh://git@git.dev.vifo.cc:222/rui/rui-payment.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-payment/issues` |
|
||
| rui-frontend | `ssh://git@git.dev.vifo.cc:222/rui/rui-frontend.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-frontend/issues` |
|
||
| rui-docs | `ssh://git@git.dev.vifo.cc:222/rui/rui-docs.git` | `https://git.dev.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.dev.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.dev.vifo.cc/api/v1/repos/rui/rui-framework/issues"
|
||
```
|
||
|
||
**返回示例**：
|
||
```json
|
||
{
|
||
"id": 7,
|
||
"number": 2,
|
||
"title": "[API-REQ] 用户编辑接口密码字段处理优化",
|
||
"html_url": "https://git.dev.vifo.cc/rui/rui-framework/issues/2",
|
||
"state": "open"
|
||
}
|
||
```
|
||
|
||
## 获取 Issue
|
||
|
||
```bash
|
||
TOKEN=$(cat ~/.config/gitea/token)
|
||
curl -s -H "Authorization: token ${TOKEN}" \
|
||
"https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}"
|
||
```
|
||
|
||
## 列出仓库所有 Issue
|
||
|
||
```bash
|
||
TOKEN=$(cat ~/.config/gitea/token)
|
||
curl -s -H "Authorization: token ${TOKEN}" \
|
||
"https://git.dev.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.dev.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.dev.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 推送命令
|
||
|
||
各仓库 remote 名称不统一，推送前先确认：
|
||
|
||
```bash
|
||
# 查看 remote 名称
|
||
git remote -v
|
||
|
||
# 推送到远程（替换 {remote} 为实际的 remote 名称）
|
||
git push {remote} main
|
||
```
|
||
|
||
| 仓库 | 推荐 remote 名称 |
|
||
|------|----------------|
|
||
| rui-framework | origin |
|
||
| rui-cashier | origin |
|
||
| rui-payment | gitea |
|
||
| rui-frontend | origin |
|
||
|
||
## 注意事项
|
||
|
||
1. **JSON 内容**: 建议使用文件方式（-d @file.json）避免转义问题
|
||
2. **Labels**: 创建 Issue 时 labels 参数需要传入 ID 数组，不是字符串数组
|
||
3. **返回字段**: number 是 Issue 编号，id 是内部 ID
|
||
4. **owner 统一为 rui**: 所有仓库都在 rui 组织下
|