# 业务行生命周期契约（Work Item Lifecycle）

> **状态：正式契约 v1.0。**  
> **目标：** 冻结「对某一行做有副作用处理」时的**状态角色与操作权**规则，使队列型技能（生成、触达、私信、发布等）行为一致、可验收。  
> **非目标：** 规定某一技能的具体状态码或状态个数；强制所有表都有 status；替代任务中心 / 运行日志；规定 Data Policy 授权。  
> **适用范围：** 有「处理业务行」类 Action 的技能。纯配置表、目录表、只读展示表标 N/A。

相关正交轴：[`ACTIONS.md`](ACTIONS.md)（入口与 sync/async）、[`SCHEMA.md`](SCHEMA.md)（表与展示）、[`POLICY.md`](POLICY.md)（谁能点）、任务中心（宿主 Job）。

---

## 0. 为什么需要本契约

若「处理这一行」的按钮对**任意状态**都可点，会出现：

- 已成功的行被重复执行（重复发信、重复生成、覆盖产物）
- 失败行被默认批量静默重试，运营无法区分「未做」与「做过但失败」
- 任务中心显示成功，业务表仍停在初始态（结果未回写）

本契约要求：**默认可自动操作的只有「可操作」角色；其它角色须人工改回可操作后再处理。**

---

## 1. 状态角色（通用，不绑死枚举）

技能自己定义业务状态字符串与中文标签；契约只认**角色**。一个角色可对应**一个或多个**业务状态。

| 角色 | 含义 | 默认可被处理 Action 捞起？ |
|------|------|---------------------------|
| **operable（可操作）** | 尚未成功处理、允许自动或行操作启动处理 | **是（默认唯一）** |
| **in_progress（进行中）** | 已抢占，正在处理 | **否**（防双跑） |
| **terminal_success（成功类终态）** | 已按业务定义完成 | **否** |
| **terminal_failure（失败类终态）** | 已尝试且失败；通常带失败原因 | **否** |
| **terminal_skipped（跳过类终态）** | 人工放弃或不处理 | **否** |

### 1.1 举例（仅对照，不是规范枚举）

| 角色 | 技能 A（内容队列）可能叫 | 技能 B（线索触达）可能叫 |
|------|--------------------------|--------------------------|
| operable | 待生成、新建 | 新建、私信未发 |
| in_progress | 生成中 | 触达中 |
| terminal_success | 已生成 | 已私信 |
| terminal_failure | 失败 | 触达失败 |
| terminal_skipped | 已跳过 | 已忽略 |

技能可以有更多业务状态（审核中、待确认、部分成功等）：须在需求里写明各自映射到哪一角色，或声明「不属于处理队列、本契约 N/A」。

### 1.2 技能必须声明映射

复制模板后，在 `development/REQUIREMENTS.md`（或等价需求）中写清：

```text
处理队列表：<table>
状态字段：<column>
可操作：<status1>, <status2>, …
进行中：<status…>
成功类终态：…
失败类终态：…（失败原因字段：…）
跳过类终态：…
```

未声明映射的「处理队列」技能，交活 Checklist 不得标 PASS。

---

## 2. 硬规则（技能实现必须遵守）

1. **默认只认 operable**  
   行操作 / 批量 / 定时 / Agent 触发的「处理」类 Action，pick 与 claim **默认**只包含可操作状态。  
   不得把成功、失败、跳过、进行中混进默认捞取集合（除非另做**显式命名**的「重试失败」类 Action，且确认文案写清范围——仍推荐不如人工改回可操作简单）。

2. **开始即原子抢占 → in_progress**  
   在真正产生副作用前，用「仅当当前为 operable 时 UPDATE 为进行中」的方式抢占。抢占失败 → 跳过或返回明确错误（如「当前不是可操作状态」），**禁止**继续副作用。

3. **结束必须回写业务表**  
   - 成功 → 对应成功类终态，并写入产物路径/摘要等业务字段（若有）  
   - 失败 → 对应失败类终态，并写入**失败原因**（用户可读；勿塞密钥）  
   - 禁止「任务中心成功、业务行仍停在可操作/进行中」而不回写

4. **重做靠人工改回 operable**  
   成功 / 失败 / 跳过 / 卡住的进行中，默认不能再点处理。运营在数据管理把状态改回可操作后，方可再次处理。

5. **任务中心 ≠ 业务状态**  
   Job「进行中 / 成功 / 失败」是宿主任务态。业务「进行中」必须写在业务表。进度 `emit` 不替代状态回写。

6. **过程与结果分工**（延续既有约定）  
   过程 → 运行日志 / 任务中心 Activity；业务结果 → 业务表。**不要**靠新建 `task_logs` 一类审计表充当状态机。

---

## 3. Action 与文案约定

- 处理类 Action 的 `description` / `confirmation.message` 应写明：**仅处理「可操作」状态**（用本技能用户能懂的词，如「仅待生成」「仅新建」）。
- 对非可操作行触发时：返回明确失败码与中文说明，提示「请先改回 xxx」。
- 长任务（`async`）：除任务中心进度外，业务行应尽快进入进行中，避免界面长时间仍显示可操作导致连点。

正交提醒：

| 轴 | 管什么 | 不管什么 |
|----|--------|----------|
| 本契约 | 什么**状态**能处理 | 谁有权点按钮 |
| Data Policy | 谁有权 | 状态机 |
| executionProfile | sync/async 通道 | 业务终态 |

---

## 4. 数据管理展示建议

- 状态列：`options_json` 枚举完整业务状态（含进行中与各类终态）。
- 失败原因列：失败类终态可见；成功后宜清空或保留末次原因（技能自定，须一致）。
- 终态与进行中的状态字段建议 **可编辑**（或提供「改回可操作」Action），以便人工重做；**不要**只能靠删行重建。
- `grid_help` 可一句话写清：「仅某某状态可处理；其它状态请改回后再操作。」

详见 [`SCHEMA.md`](SCHEMA.md)。

---

## 5. 可观测性（与 ACTIONS / 日志约定对齐）

推荐阶段（名称可自定，须能对应到开始 / 关键节点 / 结束）：

1. 已抢占（业务 → 进行中）  
2. 处理中关键步骤（可 `emit`）  
3. 回写成功或失败  

故意失败一条时：业务表应为失败类终态 + 原因；任务中心为失败；日志含 `task_failed` / `error_code=`。

---

## 6. 非目标与常见误区

| 误区 | 正确做法 |
|------|----------|
| 把「新建/成功/失败/跳过」写成全平台唯一枚举 | 只用角色；各技能自定状态名 |
| 默认批量包含失败「方便自动重试」 | 默认不含；重试改回可操作或单独显式 Action |
| 只有任务成功、不改业务状态 | 必须回写业务表 |
| 用进行中替代任务中心 | 两者都要：业务防双跑，任务轨看进度 |
| 所有表都套本契约 | 无「处理行」副作用的表标 N/A |

---

## 7. 验收摘要（完整条目见 CHECKLIST）

有处理队列时至少验证：

1. 成功类终态再点处理 → 拒绝或跳过，不产生重复副作用  
2. 可操作行处理中 → 先见进行中，结束后见成功或失败+原因  
3. 失败行改回可操作后 → 可以再次处理  
4. 任务中心有过程（长任务）且业务表状态与结果一致  

---

## 8. 版本

| 版本 | 说明 |
|------|------|
| v1.0 | 首版：角色模型 + 硬规则 + 需求映射 + 与 Action/SCHEMA/任务中心边界 |