ee2a4d9e22
基于 skill-template 脚手架开发，包含： - 5 张业务表（教职工、请假政策、考勤日历、请假记录、假期余额） - 请假核算引擎（扣薪计算、审批层级判定、年假抵扣） - CLI 入口（import-employees / calculate-leave / render-html） - HTML 审批与扣薪报告生成 - 示例数据与完整测试套件（295 tests passed）
7.3 KiB
业务行生命周期契约（Work Item Lifecycle）
状态：正式契约 v1.0。
目标： 冻结「对某一行做有副作用处理」时的状态角色与操作权规则，使队列型技能（生成、触达、私信、发布等）行为一致、可验收。
非目标： 规定某一技能的具体状态码或状态个数；强制所有表都有 status；替代任务中心 / 运行日志；规定 Data Policy 授权。
适用范围： 有「处理业务行」类 Action 的技能。纯配置表、目录表、只读展示表标 N/A。
相关正交轴：ACTIONS.md（入口与 sync/async）、SCHEMA.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（或等价需求）中写清：
处理队列表：<table>
状态字段：<column>
可操作：<status1>, <status2>, …
进行中：<status…>
成功类终态：…
失败类终态：…（失败原因字段：…）
跳过类终态：…
未声明映射的「处理队列」技能，交活 Checklist 不得标 PASS。
2. 硬规则（技能实现必须遵守）
-
默认只认 operable
行操作 / 批量 / 定时 / Agent 触发的「处理」类 Action，pick 与 claim 默认只包含可操作状态。
不得把成功、失败、跳过、进行中混进默认捞取集合（除非另做显式命名的「重试失败」类 Action，且确认文案写清范围——仍推荐不如人工改回可操作简单）。 -
开始即原子抢占 → in_progress
在真正产生副作用前，用「仅当当前为 operable 时 UPDATE 为进行中」的方式抢占。抢占失败 → 跳过或返回明确错误（如「当前不是可操作状态」），禁止继续副作用。 -
结束必须回写业务表
- 成功 → 对应成功类终态，并写入产物路径/摘要等业务字段（若有）
- 失败 → 对应失败类终态，并写入失败原因（用户可读；勿塞密钥）
- 禁止「任务中心成功、业务行仍停在可操作/进行中」而不回写
-
重做靠人工改回 operable
成功 / 失败 / 跳过 / 卡住的进行中，默认不能再点处理。运营在数据管理把状态改回可操作后，方可再次处理。 -
任务中心 ≠ 业务状态
Job「进行中 / 成功 / 失败」是宿主任务态。业务「进行中」必须写在业务表。进度emit不替代状态回写。 -
过程与结果分工（延续既有约定）
过程 → 运行日志 / 任务中心 Activity；业务结果 → 业务表。不要靠新建task_logs一类审计表充当状态机。
3. Action 与文案约定
- 处理类 Action 的
description/confirmation.message应写明：仅处理「可操作」状态（用本技能用户能懂的词，如「仅待生成」「仅新建」）。 - 对非可操作行触发时：返回明确失败码与中文说明，提示「请先改回 xxx」。
- 长任务（
async）：除任务中心进度外，业务行应尽快进入进行中，避免界面长时间仍显示可操作导致连点。
正交提醒：
| 轴 | 管什么 | 不管什么 |
|---|---|---|
| 本契约 | 什么状态能处理 | 谁有权点按钮 |
| Data Policy | 谁有权 | 状态机 |
| executionProfile | sync/async 通道 | 业务终态 |
4. 数据管理展示建议
- 状态列：
options_json枚举完整业务状态（含进行中与各类终态）。 - 失败原因列：失败类终态可见；成功后宜清空或保留末次原因（技能自定，须一致）。
- 终态与进行中的状态字段建议 可编辑（或提供「改回可操作」Action），以便人工重做；不要只能靠删行重建。
grid_help可一句话写清：「仅某某状态可处理；其它状态请改回后再操作。」
详见 SCHEMA.md。
5. 可观测性（与 ACTIONS / 日志约定对齐）
推荐阶段（名称可自定，须能对应到开始 / 关键节点 / 结束）：
- 已抢占（业务 → 进行中）
- 处理中关键步骤（可
emit） - 回写成功或失败
故意失败一条时：业务表应为失败类终态 + 原因；任务中心为失败；日志含 task_failed / error_code=。
6. 非目标与常见误区
| 误区 | 正确做法 |
|---|---|
| 把「新建/成功/失败/跳过」写成全平台唯一枚举 | 只用角色；各技能自定状态名 |
| 默认批量包含失败「方便自动重试」 | 默认不含；重试改回可操作或单独显式 Action |
| 只有任务成功、不改业务状态 | 必须回写业务表 |
| 用进行中替代任务中心 | 两者都要：业务防双跑，任务轨看进度 |
| 所有表都套本契约 | 无「处理行」副作用的表标 N/A |
7. 验收摘要（完整条目见 CHECKLIST）
有处理队列时至少验证：
- 成功类终态再点处理 → 拒绝或跳过，不产生重复副作用
- 可操作行处理中 → 先见进行中，结束后见成功或失败+原因
- 失败行改回可操作后 → 可以再次处理
- 任务中心有过程（长任务）且业务表状态与结果一致
8. 版本
| 版本 | 说明 |
|---|---|
| v1.0 | 首版：角色模型 + 硬规则 + 需求映射 + 与 Action/SCHEMA/任务中心边界 |