5.6 KiB
工况任务后端契约
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在项目内唯一，进度以外部版本反馈为准。event_investigation：投诉、爆管上报或人工发起的调查。Agent 查询受控数据，发布执行图、证据引用和报告；现场反馈会创建新的执行 generation，让 Agent 重新分析。
创建请求使用 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}/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 |
有对应审批权限的用户确认或拒绝 |
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。后续默认只在 tjwater_v2 应用，验证通过并由维护者明确确认后，再逐库扩展。不要从 Metadata DB 枚举所有活跃项目并批量写入。
应用前确认当前 DSN 指向 tjwater_v2：
test "$(psql "$PROJECT_BIZ_DSN" -XAtc 'select current_database()')" = "tjwater_v2"
完成备份和回滚演练后，再按依赖顺序应用。017 是工作台范围的注释迁移，要求告警、工单、任务和 Run 表均已存在：
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/008_workbench_alert_events.sql
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/011_workbench_work_orders.sql
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/014_operational_tasks.sql
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/015_workbench_events_and_task_runs.sql
psql "$PROJECT_BIZ_DSN" -v ON_ERROR_STOP=1 -f resources/sql/017_workbench_schema_comments.sql
017_workbench_schema_comments.sql 只增加数据库可见的表、列和 schema 注释，不改变数据、约束或索引。迁移不会创建或修改外围系统的业务表，也不授予 PUBLIC 权限。生产运行前需按部署身份显式授予新表权限。SQL 文件包含自己的事务边界，不能把外层 ROLLBACK 当作演练；具体要求见数据库变更门禁。