feat: 完善工单路由规则和 Gitea API 指南

- gitea-api.md: 补全 5 个仓库地址、工单路由表、URL 前缀映射、remote 名称、关闭 Issue API - issue-workflow.md: 增加工单归属判断、跨仓库提工单流程、列出/关闭工单 API
2026-06-08 13:00:13 +08:00
parent a7f3ee3565
commit c7244b3b87
2 changed files with 152 additions and 21 deletions
@@ -6,6 +6,47 @@
 ~/.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 文件（避免转义问题）
@@ -60,6 +101,14 @@ 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
@@ -71,28 +120,50 @@ curl -s -X POST \
  "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}` |
-| 创建评论 | POST | `/api/v1/repos/{owner}/{repo}/issues/{id}/comments` |
-| 获取仓库 | GET | `/api/v1/repos/{owner}/{repo}` |
+| 创建 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 远程地址
+## Git 推送命令

-```
-gitea	ssh://git@git.dev.vifo.cc:222/rui/{repo}.git
+各仓库 remote 名称不统一，推送前先确认：
+
+```bash
+# 查看 remote 名称
+git remote -v
+
+# 推送到远程（替换 {remote} 为实际的 remote 名称）
+git push {remote} main
 ```

-**推送命令**: `git push gitea main`（注意不是 origin）
+| 仓库 | 推荐 remote 名称 |
+|------|----------------|
+| rui-framework | origin |
+| rui-cashier | origin |
+| rui-payment | gitea |
+| rui-frontend | origin |

 ## 注意事项

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

 ## 标准流程

-### 1. 获取工单详情
+### 1. 读取工单

 使用 Gitea API 获取 Issue 内容：
 ```bash
-curl -s -H "Authorization: token $(cat ~/.config/gitea/token)" \
+TOKEN=$(cat ~/.config/gitea/token)
+curl -s -H "Authorization: token ${TOKEN}" \
  "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}"
 ```

+也可以列出当前仓库所有未关闭的工单：
+```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"
+```
+
 ### 2. 分析需求

 - 阅读工单标题和描述
- 确认需求范围
+- 确认需求范围是否属于当前仓库
 - 检查相关配置文件和代码
 - 必要时向用户澄清

-### 3. 实施修改
+### 3. 判断工单归属
+
+如果工单内容不属于当前仓库，需要路由到正确的仓库：
+
+| 问题类型 | 正确仓库 |
+|---------|---------|
+| 框架能力、公共工具、安全、Feign | rui-framework |
+| 系统管理、用户管理接口 | rui-framework |
+| 收银业务逻辑 | rui-cashier |
+| 支付业务逻辑 | rui-payment |
+| 前端页面、UI 组件 | rui-frontend |
+| 文档、规范、技能 | rui-docs |
+
+**路由方式**：在当前仓库回复工单说明需转交，然后向目标仓库创建新 Issue。
+
+### 4. 实施修改

 按 Superpowers 工作流处理：
 - 简单任务：直接实施
 - 复杂任务：设计 -> 计划 -> 实施

-### 4. 回复工单状态
+### 5. 回复工单

 完成后必须回复工单：
 ```bash
+TOKEN=$(cat ~/.config/gitea/token)
 curl -s -X POST \
-  -H "Authorization: token $(cat ~/.config/gitea/token)" \
+  -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"
 ```

+### 6. 关闭工单
+
+```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}"
+```
+
+## 跨仓库提工单
+
+当当前仓库开发中需要其他仓库配合时：
+
+1. 确认问题属于目标仓库
+2. 通过 Gitea API 向目标仓库创建 Issue
+3. 在当前仓库的 git commit 中注明关联工单
+
+```bash
+# 示例：payment 需要框架新增能力，向 rui-framework 提交
+cat > /tmp/issue.json << 'EOF'
+{
+  "title": "[API-REQ] 需要新增支付回调重试工具",
+  "body": "## 来源\n\nrui-payment 模块请求\n\n## 功能描述\n\n...\n\n## 优先级\n\n高"
+}
+EOF
+
+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"
+```
+
 ## 提交规范

- 提交信息需关联工单编号：`对应工单 #2`
- 使用语义化提交前缀：`feat:`, `fix:`, `docs:`, `chore:`
+- 提交信息需关联工单编号：对应工单 #2
+- 使用语义化提交前缀：feat:, fix:, docs:, chore:

 ## 优先级处理