# 工况任务后端契约

`resources/sql/014_operational_tasks.sql` 提供项目隔离的统一工况任务存储。所有接口均位于 `/api/v1`，使用产品 Bearer 身份和 `X-Project-Id`；任务正文不会接受客户端提供的项目 ID。

## 三类任务

- 定时任务：当前产品继续使用前端 mock。`scheduled_flow` 及后端计划接口为已有保留能力，不接当前前端、不由当前 worker 调度或执行。
- `external_work_order`：外围预约、维修等工单的只读任务投影。`source.kind + source.external_id` 在项目内唯一，进度以外部版本反馈为准。

预约任务采用单层结构：一张外围工单对应一条任务，工单快照直接提供状态、位置、负责人、预约时间、回执要求和按发生时间记录的 `activity`。活动仅由工单创建、修改或显式现场反馈产生；不能按当前状态补造派发、执行、复令三个阶段。旧快照中的 `subtasks` 仅在读取时兼容并丢弃，不回写外围工单或历史版本；后续外围修订同步为新结构。
- `event_investigation`：投诉、爆管上报或人工发起的调查。Agent 查询受控数据，发布执行图、证据引用和报告；现场反馈会创建新的执行 generation，让 Agent 重新分析。

调查计划由 Agent 按本次工单或人工请求动态生成。新计划使用 `execution-plan@2`，节点声明执行步骤、条件判断、并行分叉/汇合和审核点；判断节点记录所选路线，审核点引用持久化申请或动作。重新分析追加计划修订和新节点，不使用环形连线。旧 `execution-plan@1` 快照保留原样读取。字段、约束与示例见 [`dynamic-investigation-plan.md`](dynamic-investigation-plan.md)。

数据读取申请通过 `POST /operational-tasks/{task_id}/access-requests` 创建，`POST .../access-requests/{access_request_id}/decision` 由具备项目审核权限及对应数据源读取权限的用户决定。申请、批准范围和审核身份保存在任务库中，批准或拒绝后重新排队分析。调查接口不会将服务身份继承的项目数据读取权限直接授予 Agent；批准的范围也只在该任务的有效执行期可查询。需配置 `OPERATIONAL_DATA_DELEGATION_BEARER` 为具备对应来源读取权限及该项目成员身份的专用产品凭证。未配置时返回 503，不以普通 Agent 会话的工具许可代替任务授权。

工单草稿可通过 `PATCH .../actions/{action_id}/draft` 修改并增加审计版本；`POST .../actions/{action_id}/confirm-dispatch` 使用一次人工操作批准当前版本并幂等提交，结果不明时继续使用回执核对。其他动作类型维持既有审批接口，不在调查页伪装为已支持的工单编辑动作。

创建请求使用 `request_id` 幂等。任务执行使用独立的 `run_id + execution_request_id`：Agent 必须领取当前 run，并通过 run 级心跳维持 60 秒租约。正常结束必须显式 complete；缺少同代最终计划或报告会以 `ARTIFACT_INCOMPLETE` 失败。`POST /operational-tasks/leases/recover` 会处理过期执行，连续三代超时后停止自动重试。

## 主要接口

| 方法和路径 | 作用 |
| --- | --- |
| `POST /operational-tasks` | 幂等创建任务 |
| `GET /operational-tasks` | 按类型、状态分页读取任务 |
| `GET /operational-tasks/{task_id}` | 读取当前计划、报告、证据摘要、审批动作和当前用户权限 |
| `GET /operational-tasks/{task_id}/agent-context` | 读取 Agent 任务上下文及当前身份允许的数据源 |
| `POST /operational-tasks/{task_id}/runs/{run_id}/claim` | 使用当前执行请求号领取 queued run |
| `POST /operational-tasks/{task_id}/runs/{run_id}/heartbeat` | 续期当前 Agent run，不递增任务业务 revision |
| `POST /operational-tasks/{task_id}/runs/{run_id}/complete` | 校验同代最终产物并显式结束 run |
| `POST /operational-tasks/{task_id}/runs/{run_id}/fail` | 使用稳定失败码显式终止 run |
| `POST /operational-tasks/{task_id}/data-query` | 查询固定白名单数据源，同时保存有界原始快照并返回证据 ID |
| `POST /operational-tasks/{task_id}/access-requests` | Agent 创建任务级数据访问申请 |
| `POST .../access-requests/{access_request_id}/decision` | 人工批准部分或全部申请范围，或拒绝申请 |
| `POST /operational-tasks/{task_id}/agent-artifacts` | 追加证据、计划快照和报告修订 |
| `POST /operational-tasks/{task_id}/human-evidence` | 保存用户补充信息并重新排队分析 |
| `POST /operational-tasks/{task_id}/external-feedback` | 幂等同步稳定外部事件流的单调版本 |
| `POST /operational-tasks/{task_id}/actions` | 提议需要人工确认的动作 |
| `POST .../actions/{action_id}/decision` | 有对应审批权限的用户确认或拒绝 |
| `PATCH .../actions/{action_id}/draft` | 人工修改工单草稿并产生新审核版本 |
| `POST .../actions/{action_id}/confirm-dispatch` | 一次确认当前草稿并幂等下发工单 |
| `POST .../actions/{action_id}/execute` | 重新校验执行权限后通过类型化适配器提交 |
| `POST .../actions/{action_id}/reconcile` | 仅使用固定执行请求号查询不确定或已提交动作的回执 |
| `GET /operational-task-notifications` | 返回当前用户可见、按用户区分已读状态的通知 |

报告采用不可变修订，正文只保存当前结论、结论边界、建议、证据引用和待确认事项。详细的 Agent 工具轨迹和模型内部推理不进入报告。系统数据只能通过受控 `data-query` 形成证据，外围反馈和人工补充也有各自入口；Agent 不能自行声明这三类证据。合成演练证据始终标记为 `synthetic`。

## 人工确认与执行真实性

动作分为 `create_work_order` 和 `issue_command`，审批状态与执行状态分别保存。每次状态变化都会写入不可变动作版本；首次提交生成固定 `execution_request_id`，后续回执核对不改变它。

工单审批和执行可授予项目成员。设备命令审批、执行只授予具有系统管理身份且同时能进入项目的人员。普通查看者只能看任务及其 `permissions`，不能从前端角色名称推断或绕过服务端权限。

`approved` 只表示允许提交。`submitted` 需要外部接收回执，`succeeded` 还需要完成时间和完成回执。未配置适配器返回 `unsupported`，响应丢失返回 `unknown`；这两种情况都不会被记录为执行成功。外部适配器及 worker 的部署方式见 `docs/operational-task-workers.md`。

## 数据库部署

数据库变更遵循 [`workbench-database-rollout.md`](workbench-database-rollout.md)。后续默认只在 `tjwater_v2` 应用，验证通过并由维护者明确确认后，再逐库扩展。不要从 Metadata DB 枚举所有活跃项目并批量写入。

应用前确认当前 DSN 指向 `tjwater_v2`：

```bash
test "$(psql "$PROJECT_BIZ_DSN" -XAtc 'select current_database()')" = "tjwater_v2"
```

`008`、`011`、`014`、`015` 和 `017` 属于历史基线；不要在旧工单表退役后重新运行 `011`，否则会重建它。`019` 和 `022` 都带有 `tjwater_v2` 物理数据库名硬门禁，其他 BizDB 尚未应用。完成备份和回滚演练后，仅在已核对的 `tjwater_v2` 执行迁移：

```bash
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/019_operational_task_access_requests.sql
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/021_retire_workbench_work_orders.sql
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/022_operational_notification_lifecycle.sql
```

`017_workbench_schema_comments.sql` 只增加历史基线的数据库可见注释。`018_remove_synthetic_check_task_projections.sql` 只清理错误进入预约任务的旧种子检查投影。`020_prune_non_actionable_notifications.sql` 删除历史任务创建、报告更新和正常完成通知，保留审批与异常通知。`021` 只有在三条演示工单均已迁入外围样板并形成有效工况任务时才删除旧表，不修改外围源及历史修订。`022_operational_notification_lifecycle.sql` 仅限 `tjwater_v2`，为保留通知回填 `active|resolved` 生命周期和业务对象引用，不新增表。通知路由和状态流见 [`operational-notification-routing.md`](operational-notification-routing.md)。SQL 文件包含自己的事务边界，不能把外层 `ROLLBACK` 当作演练；具体要求见数据库变更门禁。