# Gitea 工单处理规则（Issue Handling）

## 为什么有这份文档

本团队所有工单（feature / ops / infra / bug / follow-up / epic / 任何类型）都跑在 Gitea issue 上。无论谁去 Gitea 上"动"一个工单——领取、放回、改状态、关闭——都遵循同一套**操作语法**。

这份文档**不关心工单的业务流程**（feature 的 PRD/契约/开发链路在 [`14-feature-request-workflow.md`](./14-feature-request-workflow.md)；ops/infra 工单走对应 skill）。只规定：**操作工单时，事实源是什么、最小动作是什么**。

---

## 核心规则

### 1. 接单：`assignee` 是唯一事实源

> **判定一张工单是否被接：`assignee` 字段是否为空。**
>
> - `assignee == 空` ⇒ **未接**，任何人可以 claim。
> - `assignee != 空` ⇒ **已接**，归属于 assignee 本人。
>
> 任何 label（`Status/*`、`Owner/*`、`Status/待领取`）都**不能代替 assignee 作为接单凭证**。当 label 与 assignee 不一致时，**以 assignee 为准**。

claim 工单的**唯一必做动作**：

```
设 assignee = 自己
```

不补 label、不发评论、不改 Status，**也算接走了**。label / Owner / Status 是辅助看板视图，按需补贴（详见 §3）。

```bash
# 用 gitea CLI
# (尚未支持 issue assign 子命令时，用 curl)
curl -X POST -H "Authorization: token $GITEA_API_TOKEN" \
  -H "Content-Type: application/json" \
  http://43.130.59.228/api/v1/repos/FFAIWorkspace/workspace/issues/<N> \
  -d '{"assignees":["chentao.jia"]}'
```

### 2. 释放：清空 `assignee`

中途放弃 / 转手 / 误接的工单，**必须清空 assignee**——这样其他人才能看到它"未接"。

```
设 assignee = 空（[]）
```

可选：评论一句释放原因（不强制格式）。如果工单已经贴了 `Status/PRD 中` 等推进态，按工单类型决定要不要切回 `Status/需求待澄清` / `Status/Abandoned`。

### 3. label / Owner / Status 是辅助，不是必要

接单时**可选**贴：

- `Owner/<Name>`：方便按 label 做看板分组（"宏伟的活" / "立健的活"）
- `Status/<阶段>`：方便看工单当前在生命周期哪一步

**这些是看板优化，不是接单的必要条件**。漏贴不会让"接单"动作无效，只是工单在某些 filter 视图里看不到。

---

## 状态推进：按工单类型分流

接单之后怎么推进状态，按工单类型走对应流程，不在本文档重复：

| 工单类型 | 信号 | 推进流程 |
|---|---|---|
| **feature**（新功能 / 新模块 / 业务规则变更）| `Kind/Feature` label / 跑 `plan-feature` skill | 走 [`14-feature-request-workflow.md`](./14-feature-request-workflow.md) 的状态机：需求待澄清 → PRD 中 → 契约设计中 → 开发中 → 待验收 → 关闭 |
| **ops / infra**（运维 / CI / 工具）| `[ops]` 标题前缀 / `[infra]` 标题前缀 | 直接进对应 skill（`deploy-ops` / `infra-check` / `troubleshoot` 等），不强制 PRD，PR 合并即可关 |
| **bug fix** | `Kind/Bug` label / 标题含 fix | 走 hotfix 分支，PR 合并即可关 |
| **follow-up / epic / 文档 / 重构**| 标题前缀 `[follow-up]` / `[epic]` / `[arch]` / `[design]` | 轻量推进：接单 → 起分支 → PR → 关。**不强制 Status label** |

**所有类型共享 §1–§3 的接单 / 释放语法**。状态机的差异不影响"接单事实源是 assignee"这条铁律。

---

## 看板视图（建议在 Gitea 上保存的 filter）

| 视图 | filter |
|---|---|
| **未接的工单**（最关键）| `is:open no:assignee` |
| 我的工单 | `is:open assignee:@me` |
| 某人的活 | `is:open assignee:<login>` |
| 进行中的 feature | `is:open label:"Status/开发中"`（仅 feature 类） |
| 等我验收的 feature | `is:open label:"Status/待验收"`（仅 feature 类） |

> "未接的工单" 这条以前依赖 `label:"Status/待领取"`，但 ops/bug/follow-up 类工单普遍不贴该 label，会漏。改用 `no:assignee` 后任何类型的未接工单都能扫到。

---

## 常用 CLI 操作

接单 / 释放目前没有专门子命令，先用 `curl` + Gitea API；高频用上后再补到 `scripts/ops/gitea` CLI。

```bash
# 接单
ISSUE=334
USER=chentao.jia
curl -sS -X POST -H "Authorization: token $GITEA_API_TOKEN" \
  -H "Content-Type: application/json" \
  http://43.130.59.228/api/v1/repos/FFAIWorkspace/workspace/issues/$ISSUE \
  -d "{\"assignees\":[\"$USER\"]}" | python3 -m json.tool

# 释放
curl -sS -X POST -H "Authorization: token $GITEA_API_TOKEN" \
  -H "Content-Type: application/json" \
  http://43.130.59.228/api/v1/repos/FFAIWorkspace/workspace/issues/$ISSUE \
  -d '{"assignees":[]}' | python3 -m json.tool

# 评论
scripts/ops/gitea issue comment $ISSUE --body "..."

# 加/去 label
scripts/ops/gitea label add $ISSUE "Owner/Chentao"
scripts/ops/gitea label remove $ISSUE "Status/待领取"
```

---

## 反模式（别这样做）

| 反模式 | 为什么不行 |
|---|---|
| 用 `Status/待领取` label 判断"未接" | 大量 ops/bug/follow-up 工单没贴该 label，但事实上未接——会漏。事实源永远是 assignee |
| 接单只贴 `Owner/*` label，不设 assignee | label 不进入 Gitea 内置的"我的工单"视图，本人在工作台看不到；其他人也无法用 `no:assignee` 准确扫"未接" |
| 一张工单 ≥ 2 个 assignee | 所有权稀释。需要协作的拆子工单，每张独立负责人。详见 [`14-feature-request-workflow.md`](./14-feature-request-workflow.md) §「派活原则」 |
| 不做了不清 assignee 直接走人 | 工单挂在你名下"假装在做"，别人不敢接，事实上烂尾 |
| 历史漂移：assignee 已填但 `Status/待领取` label 还在 | 接单时漏清 label。看板视图会矛盾。**接单后顺手清掉 `Status/待领取`**（如果当时贴过） |

---

## 与现有文档的关系

| 文档 | 关心什么 | 与本文档的关系 |
|---|---|---|
| [`14-feature-request-workflow.md`](./14-feature-request-workflow.md) | feature 类工单的业务流程（PRD/契约/开发链路）| 业务流程；本文档是操作语法，二者正交 |
| [`15-cli-design-spec.md`](./15-cli-design-spec.md) | `scripts/ops/gitea` CLI 设计 | CLI 是操作的载体；本文档定义"该做什么"，CLI 提供"怎么做" |
| [`16-gitea-actions-platform-semantics.md`](./16-gitea-actions-platform-semantics.md) | Gitea Actions / PR / branch protection 语义 | 同属 Gitea 平台规则，但聚焦 CI/CD 与 PR；本文档聚焦 issue |