158 lines
7.3 KiB
Markdown
158 lines
7.3 KiB
Markdown
# 业务行生命周期契约（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/任务中心边界 |
|