# task-orch **Repository Path**: top_area/task-orch ## Basic Information - **Project Name**: task-orch - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-13 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 任务调度框架 (Task Orchestration Framework) 一个把若干**任务类型**组合成**业务任务**、并按步骤图自动接续执行的调度框架(支持并行分支)。 Spring Boot 3.x / JDK 21 / PostgreSQL,单模块 Maven 工程,数据库迁移用 Flyway。 ## 文档 - 业务使用手册:`docs/user-guide.md` - 代码主流程图(类 / 方法 / 调用顺序):`docs/diagrams/code-main-flow.drawio` - 术语表:`CONTEXT.md` - Spec:`docs/spec/task-orchestration-framework.md` - 决策记录:`docs/adr/` - 实施 ticket:`.scratch/task-orchestration-framework/issues/` ## 环境要求 - JDK 21 - Maven 3.9+ - PostgreSQL(本地实例) ## 初始化数据库 项目需要两个库:开发库 `task_orchestration` 与测试库 `task_orchestration_test`, 以及一个拥有它们的角色 `taskorch`。用一个能建角色 / 建库的超级用户跑一次: ```bash ./scripts/setup-db.sh ``` 脚本是幂等的,重复跑安全。表结构不用手工建——应用启动时由 Flyway 迁移创建。 若你的超级用户不是本机 `postgres` 角色,用环境变量覆盖,例如: ```bash PSQL_SUPER="psql -U myadmin -h db.internal" ./scripts/setup-db.sh ``` ## 运行 ```bash mvn spring-boot:run ``` 或打包后直接跑: ```bash mvn -DskipTests package java -jar target/task-orchestration-0.1.0-SNAPSHOT.jar ``` 启动后 Swagger 页面在 ,OpenAPI 文档在 。 连接信息可用 Spring Boot 的标准环境变量覆盖:`SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、 `SPRING_DATASOURCE_PASSWORD`、`SERVER_PORT`。 ## 测试 测试跑在**专用测试库**(`task_orchestration_test`)上——状态落库与重启恢复是核心行为, 内存库测不到。先跑一次 `./scripts/setup-db.sh`,然后: ```bash mvn test ``` 覆盖连接也可用环境变量覆盖:`TEST_DB_URL`、`TEST_DB_USERNAME`、`TEST_DB_PASSWORD`。 ## 接口一览 业务任务定义(`/api/business-task-defs`): | 方法 | 路径 | 说明 | | -------- | ----------------------------- | ------------------------------------- | | `POST` | `/api/business-task-defs` | 创建定义(含步骤图),不允许零步骤 | | `GET` | `/api/business-task-defs` | 分页查询定义列表(`name` 搜索 + `page`/`size`) | | `GET` | `/api/business-task-defs/{id}` | 查询定义详情 | | `PUT` | `/api/business-task-defs/{id}` | 修改定义(整体替换步骤清单) | | `DELETE` | `/api/business-task-defs/{id}` | 软删除定义 | | `GET` | `/api/business-task-defs/export` | 按 `ids` 批量导出定义(1–200 条),返回 JSON 信封 | | `POST` | `/api/business-task-defs/import` | 逐条导入定义,只新增不覆盖,逐条返回成败 | 定义列表与实例列表都返回统一分页信封 `{"items": [...], "total": number, "page": number, "size": number}`: `page` 从 1 开始,`size` 默认 20、最大 100,按 `id` 倒序。定义列表额外支持 `name` 关键字(大小写不敏感的 子串匹配,空值表示不过滤)。实例列表支持 `defId` / `state` 过滤;每行除 `defId` 外还带 `defName` 与 `defDeleted`,定义被软删除后仍能展示名称并标注「已删除」。 导入/导出使用同一份 JSON 信封(ADR-0015):`{"formatVersion": 1, "exportedAt": ..., "sourceApp": ..., "definitions": [...]}`,其中每条定义就是创建请求的形状(`name`、`cron`、`exclusive`、`completionCallback`、 `steps`,步骤用 `stepOrder`),不含 `id`、时间戳与 `nextFireAt`。导出按 `ids` 顺序返回、1–200 条,任一 id 不存在或已软删则整体 `404`。导入**只新增、不覆盖**:HTTP `200` 表示请求已被处理,响应 `{"total", "succeeded": [{"index", "name", "id"}], "failed": [{"index", "name", "message", "details"}]}` 逐条给出成败;单条失败不影响其它条。只有信封级错误(`formatVersion` 缺失/不支持、`definitions` 为空或超 200 条)才返回 `400`。名称没有唯一约束,重名不会拒绝。 一个定义由若干**步骤**组成一张显式 DAG:每个步骤用 `stepOrder` 显式声明身份(正整数、定义内唯一、 允许跳号,入口固定为 `1`),用 `nextStepOrders` 显式声明后继(必填,空数组表示终点)。支持扇出与汇聚: 除入口外的每一步至少有一个前驱,所有步骤都从入口可达;一个步骤有多个前置时,**全部前置都执行成功** 它才会被触发。每个步骤绑定一个**任务类型 code** 并携带自己的 `config`(JSONB 原样保存,框架对其格式零知识;保存时会校验 `triggerUrl` 等已知键)。 步骤还可带可空的展示字段 `stepName`(名称)与 `remark`(备注),不参与执行或模板寻址;空白值按 `null` 保存。 步骤报文模板里的占位符:`{{taskId}}`(本次执行的身份)、实例输入的顶层字段(如 `{{param1}}`)、 上游步骤输出 `{{step..output.}}`(保存时校验它只能引用本步的祖先步骤)。 创建示例: ```bash curl -X POST http://localhost:21302/api/business-task-defs \ -H 'Content-Type: application/json' \ -d '{ "name": "模型任务", "cron": null, "exclusive": true, "completionCallback": { "url": "http://localhost:21302/mock/task/complete", "headers": null, "body": { "name": "jason", "resourceId": "{{step.1.output.resourceId}}" } }, "steps": [ { "taskTypeCode": "MODEL", "stepOrder": 1, "stepName": "查询 IMEI", "remark": "调用模型查询设备信息", "nextStepOrders": [], "config": { "triggerUrl": "http://localhost:21302/mock/model", "headers": null, "body": { "modelUrl": "http://localhost:21302/mock/model", "callBackMethod": "admin_outer-xxx", "name": "IMEI扩线查询", "callType": "1", "responseType": "1", "serviceId": "Action_Service_xxx", "taskId": "{{taskId}}", "inputParam": [ { "dyntimeDate": "", "fieldType": "ResOutPut", "hint": "" } ] }, "pollUrl": null, "pollIntervalSeconds": 30, "deadlineSeconds": 1800 } } ] }' ``` ## 触发实例与结束感知 触发一份定义即产生一份**业务任务实例**,并把当时的步骤清单**冻结**进实例(此后改定义不影响在跑的实例)。 框架自动触发第 1 步:生成随机不可猜的 `taskId`、替换步骤报文模板里的 `{{taskId}}`、带上步骤配置的 `headers`,经出站 HTTP 端口 POST 给任务类型指定的 `triggerUrl`。触发请求体可选 `{"input": {...}}`:`input` 的顶层字段作为占位符(如 `{{param1}}`)参与本实例各步骤的模板渲染, 定时触发时输入为空。 | 方法 | 路径 | 说明 | | ------ | ------------------------------------------- | ------------------------------------------ | | `POST` | `/api/business-task-defs/{id}/instances` | 触发定义,产生实例并自动触发第 1 步,返回 `instanceId` 与实例状态 | | `POST` | `/task-callback` | 外部任务完成后的回调(固定路径,非 `/api` 前缀);按 JSON 报文体里的 `taskId` 路由 | 回调地址由定义作者自行写进触发报文(通常是 `{框架对外可达地址}/task-callback`),框架**不生成、不注入**; 回调接口**从 JSON 报文体读取 `taskId`**(URL 的 query 参数不参与路由),外部服务回调时要把 `taskId` 放进报文。 回调型(如内置 `MODEL`)由框架按 `taskId` 路由到对应的**任务执行**;只有执行处于「等回调」时才处理, 重复 / 迟到回调一律忽略。 ### 独占实例 定义可配 `exclusive: true`,表示**同一时刻只允许该定义存在一份运行中的实例**: - **重复触发被拒**:该定义已有**运行中**(`RUNNING`)的实例时,`POST .../instances` 返回 **409**、 **不排队**,也不发出站触发。 - **已结束的实例不占用**:`SUCCEEDED` 与 `FAILED` 都算**已结束**,不再占用独占——失败挂起的实例 仍可人工推进 / 人工重跑,也不妨碍再次触发该定义。判据是「存在运行中的实例」。 - **定时到点撞上独占**:跳过本次并记日志(定时触发没有调用方可以接收 409),见「定时触发」一节。 - 非独占定义不受此限,同一份定义的多份实例可并发(v1 不设并发上限)。 内置任务类型 `MODEL`(回调型)的步骤配置约定:`triggerUrl`(必填)、`headers`(可选对象)、 `body`(可选报文模板,字符串或 JSON 对象/数组;`{{taskId}}` 会被替换)。回调地址由定义作者 自行写进 `body` 的任意字段(通常为 `{框架对外可达地址}/task-callback`),框架不生成、不注入。 新增任务类型 = 新增一个实现 `TaskType` 的 Spring Bean,启动时自动登记,框架代码零改动。 回调解析交给各任务类型实现(`TaskType.onCallback`);接口默认把回调视为成功。内置 `MODEL` 目前是 **占位实现**:报文体必须是合法 JSON,`success` 显式为 `false` 时判失败,否则成功并把整份报文作为 该步输出。接入真实模型服务时按外部系统定死的报文格式覆写。 ### 结束回调(实例成功通知) 定义可配 `completionCallback`(`url` 必填、`headers` 可选对象、`body` 可选报文模板)。实例判**成功** (含人工推进导致的成功;失败不发)后,框架在事务提交之后**异步** POST 一份渲染后的报文;失败 / 超时 / 非 2xx 只记日志,不重试、不改实例状态。报文模板可引用上游步骤输出 `{{step..output.}}`、实例输入顶层字段,以及框架键 `{{instanceId}}` / `{{defId}}` / `{{finishedAt}}`(不提供 `{{taskId}}`)。发送使用专用线程池 `taskorch.completion-callback.thread-pool-size`(默认 2),不复用扫描线程池。 编排相关配置(前缀 `taskorch`,可用环境变量覆盖;下表是 `application.yml` 中的实际取值): | 配置 | 默认 | 说明 | | ----------------------------------------- | ------------------------ | -------------------------------------------- | | `taskorch.trigger-timeout-seconds` | `30` | 出站请求(触发 / 状态查询)的默认读超时(秒);同步型步骤可用 `triggerTimeoutSeconds` 单独覆盖 | | `taskorch.scan.enabled` | `true` | 是否开启定时调度扫描 | | `taskorch.scan.interval-ms` | `30000` | 两轮扫描之间的固定间隔(毫秒) | | `taskorch.scan.thread-pool-size` | `5` | 扫描线程池大小(一批实例并行推进) | | `taskorch.completion-callback.thread-pool-size` | `2` | 结束回调专用线程池大小 | | `taskorch.cron-zone` | `Asia/Shanghai` | cron 表达式按哪个时区解释;未配置时取服务器时区 | ## 步骤图推进与调度扫描 步骤构成一张显式 DAG(见「接口一览」):某步执行**成功**(系统判成功或人工确认成功)时,它的 `nextStepOrders` 被并入实例的 `ready_orders`(就绪队列,升序去重),与实例此刻是运行中还是失败无关。 第 1 步在实例创建时触发;**其后每一步由调度扫描推进**——回调 / 轮询只负责把本步执行判成成功 / 失败, 「哪些后继该触发」交给扫描决定。扫描按固定间隔做五件事: 1. **恢复**:把崩溃留下的「已发起」执行按任务类型恢复成「等回调」/「轮询中」(见「重启恢复」一节)。 2. **判截止**:把等回调 / 轮询中、已过**截止时间**的执行判该步失败(见「截止时间」一节)。 3. **驱动轮询**:把到期的轮询型执行发一轮状态查询(见「轮询型结束感知」一节)。 4. **推进**:扫出**运行中且 `ready_orders` 非空**的实例,锁住实例行、为队列里每个就绪步骤各建一条 执行记录并清空队列(先落库),再把这一批执行**平铺**提交线程池并行触发。同一实例的多个后继 在同一轮里一起触发;一批实例并行推进,一个慢触发不阻塞其余实例。 5. **定时触发**:把到点的 cron 定义各自启动一份实例(见「定时触发」一节)。 实例状态由**所有步骤各自最新一次执行**聚合:任一最新执行为失败 → 实例失败;全部为成功 / 人工确认成功 → 实例成功;否则保持运行中。因此「最后一步成功」只有在所有分支都成功时才会把实例判成功。 任一步失败(触发失败、回调报失败、轮询报失败、截止超时)即实例失败(fail-fast),**不再为它触发新步骤**; 但已在飞的兄弟分支不会被中断,它们跑完后执行结果照常落库,后继也照常记入 `ready_orders`,只是实例处于 失败态、扫描不消费就绪队列——要等失败的步骤被人工推进 / 重跑、实例回到运行中后才继续。实例的 `finishedAt` 记录第一次进入终态的时刻,兄弟分支随后成功不会覆盖它。同一任务类型在定义里重复出现时 按 `stepOrder` 各自推进。 就绪步骤的执行**先落库再发出站请求**,且队列在同一事务里清空,所以同一批就绪步骤在一轮里只会被推进一次; 崩在「某步已成功」与「后继执行落库」之间时,下一轮扫描会把它补上;崩在「后继执行已落库(已发起)」与 「记下感知状态」之间时,重启后的扫描按「已发起」恢复(见「重启恢复」一节)。 ## 轮询型结束感知(脚本 / 数据同步任务) 回调型靠外部回调;**轮询型**(内置 `SCRIPT` 与 `DATA_SYNC`)不回调,由框架按固定间隔发**出站 GET** 查状态接口。 触发与回调型一样经 HTTP POST;触发成功后该步进入「轮询中」,由调度扫描按间隔驱动: - 轮询型步骤的框架级配置:`pollUrl`(**必填**,状态查询地址)、`pollIntervalSeconds`(可选,默认 10 秒)。 - 框架**原样使用** `pollUrl`,不会自动追加查询参数。查询身份(如本次执行的 `taskId`)需要在触发报文 里按外部系统的约定传下去;`onPoll` 可从 `PollContext.taskId()` 取到本次执行的标识,自行与状态报文匹配 (内置 `SCRIPT` 按触发参数 `taskExecutionId` 匹配,见 `ScriptTaskType#onPoll`)。 - 框架对状态报文格式**零知识**:把原始响应 `(httpStatus, headers, body)` 交给该任务类型的 **轮询解析器** `TaskType.onPoll(PollContext)`,解析器返回 `运行中 / 成功 / 失败` (收敛的两态可带 message / output)。 - **单飞**:同一次执行同一时刻只有一个查询在飞——慢 GET 未返回时本轮跳过,不再发第二个。 - **容错**:GET 失败(连接失败 / 超时)或解析抛异常都只算「这次没查到」,记日志、下个周期继续, **不判失败**(一次抖动不毁掉整个实例)。 - 一批到期的轮询**并行**处理,一个慢 GET 不阻塞其余实例;扫描**先查后推**,某步这一轮刚被查到成功, 下一步就能在同一轮里被推起来。 收敛为「成功」时把它的后继记入就绪队列、由扫描继续推进;「失败」即实例失败、不再触发新步骤。 轮询查不到本身不判失败,等待超过**截止时间**才会(见下节)。 解析器由各轮询型任务类型自己实现。内置 `SCRIPT` / `DATA_SYNC` 目前是**占位解析器**: 响应能解析成 JSON 即判**成功**、整份报文作为该步输出;不是合法 JSON 则抛异常,被框架视为「这次没查到」、 下个周期继续(不判失败)。它们**不会**返回「运行中」,所以接入真实状态接口前必须覆写 `onPoll`, 否则任何合法 JSON 响应都会被当作任务成功。新增一种轮询型任务类型 = 新增一个实现 `TaskType` (`completionMode()` 返回 `POLL`)的 Spring Bean,框架代码零改动。 ## 同步型结束感知(自定义任务 CUSTOM) **同步型**(`CompletionMode.SYNC`,内置 `CUSTOM`)不等回调、也不轮询:触发请求的**同步响应本身就是终态依据**。 框架收到 2xx 后把响应交给任务类型的 `TaskType.onTriggerResponse(TriggerResponseContext)`,解析结果直接收敛本次执行。 框架本身仍对报文格式零知识;**非 2xx / 传输异常一律判失败**,不再检查响应体里的任何字段 (ADR-0012:原先对所有类型生效的 `status != "0"` 全局检查已删除)。 `CUSTOM` 的步骤配置: - `triggerUrl` / `headers` / `body`:与回调型相同。 - `successPath`(**必填**):响应 JSON 的点号路径,如 `code`、`data.status`、`items.0.state`。 - `successValues`(**必填**):非空标量数组;路径取到的值**转成字符串后与任一元素严格相等**即成功 (区分大小写、不 trim;`0` 与 `"0"` 匹配,`0` 与 `0.0` 不匹配)。 - `triggerTimeoutSeconds`(可选):本次同步请求的超时(秒),缺省取全局 `taskorch.trigger-timeout-seconds`。 - **不得配置** `pollUrl` / `pollIntervalSeconds` / `deadlineSeconds`:同步型没有等待阶段,保存时直接 400。 路径取不到、取到对象 / 数组 / `null`、值未命中、响应不是合法 JSON,都判失败,`message` 点名原因; 失败时 `output` 为 `null`。成功时**整份响应 JSON 即步骤输出**。 若进程死在「POST 已发出、响应未落库」之间,结果是永久未知的:重启后这条「已发起」执行**直接判失败** (`message = "同步任务触发后未收到响应(进程重启),结果未知"`),**绝不自动重发**(会造成外部任务重复执行), 靠人工重跑补救。 ## 截止时间(回调 / 轮询共用) 回调与轮询这两种结束感知都只是「等」:回调型等外部回调、轮询型等状态查询报结束。等过了**截止时间**就没有别的结果—— 扫描把该步判失败、实例失败、不再触发新步骤(fail-fast;已在飞的兄弟分支照常收敛)。同步型没有等待阶段, 不受本机制约束。 - 框架默认截止 **30 分钟**;步骤配置 `deadlineSeconds`(秒,可选)可覆盖,轮询型与回调型共用这一个键。 - 截止时间是**执行**的属性(`task_execution.deadline_at`):创建该次执行时按当时的步骤配置算好。 - 过期之后不会被「抢救」:截止之后才到的**回调**一律忽略,并按截止把该步判失败; 截止之前发出、截止之后才回来的**状态查询**结果同样不采用。 - 扫描**先判截止、再驱动轮询**:到点该失败的步骤不会因为还排着一次状态查询而多查一轮。 ## 定时触发(cron) 定义上可配 **cron**(Spring 六字段表达式,可空)。保存 / 修改定义时用 Spring `CronExpression` 校验, 非法表达式返回 **400**。为空时该定义**不自动触发**,只能由外部 REST 触发; 有值时**到点自动启动一份实例**——输入为空,第 1 步照常自动触发、每次执行照常生成随机 `taskId`。 - **下次触发时刻落库**(`business_task_def.next_fire_at`)以扛重启:调度扫描每个周期扫「到点(或尚未排期)」 的定义,触发一次后按 cron 把**下一个时刻**写回。cron 新配或改配为不同值时该时刻置空,由下一次扫描 重新排出第一个未来时刻(本轮只排期、不触发)。 - **重启不补触发**:只在「触发时刻落在**本次进程启动之后**」时才触发;落在启动之前即停机期间错过的时刻, 直接跳过并重排到下一个未来时刻。业务任务的定时常是「到点跑一遍」而非「补课式补跑」。 - **cron 按 `taskorch.cron-zone` 解释**:`application.yml` 默认配的是 `Asia/Shanghai`;未配置时取服务器时区 (见「编排相关配置」表)。 - **到点撞上独占**:定义是**独占实例**且已有**运行中**(`RUNNING`)的实例时, **跳过本次并记日志**、不排队(定时触发没有调用方可以接收 409);成功 / 失败都属于已结束,不占用。 - 一批到点的定义**并行**触发,一个慢触发不阻塞其余。 - 测试:用可控时钟推进到 cron 时刻,断言产生实例与跳过行为——见 `CronScheduledTriggerTest`。 ## 重启恢复 实例与执行的中间状态全部**落库**、不用内存定时器来「记住」待办(ADR-0001),所以进程重启后 扫描照样「去库里捞活」,**不会把等待中的任务丢掉**,也**绝不「重启即判失败」**: - **「等回调」/「轮询中」**的执行:重启后**继续等待 / 查询**,按原规则收敛,直到**截止时间**才判失败。 - **「已发起」**(`STARTED`)的执行:执行已落库、感知状态还没记下,即「触发请求发出与否未知」(ADR-0001)。 扫描按任务类型恢复成等待,**不重新触发**(重发就成了自动重试,v1 没有这个概念,ADR-0004): - **回调型 → 「等回调」**:继续等到截止时间,因为除了等没有别的办法。 - **轮询型 → 「轮询中」**:接着按轮询间隔查——停机期间外部任务可能已经跑完,「能查」就是它的恢复手段。 - 停机的等待照常收敛:恢复出来的执行若在停机期间已越过截止,同一轮扫描就按**截止规则**判失败, 而不是当成刚发起再等一轮。 - 恢复**不抢跑**:进程活着时每次触发也会在「已发起」上停一下(先落库再发出站请求), 扫描撞上这个窗口时同样只把它转入等待,不会在触发落定之前抢发一次状态查询。 - 恢复不救「触发响应丢失」:崩在请求发出与记下状态之间时无从判断对方到底启没启,所以**不重新触发**; 回调型只能等到截止时间判失败,轮询型则靠后续查询结果收敛,最终仍可能靠人工推进 / 人工重跑补救 (spec 的已知缺口)。同步型没有「恢复等待」一说——响应永久丢失即判失败,由人工重跑补救。 - 同步型的恢复只针对**本进程启动之前**落下的「已发起」:启动之后创建的仍可能在飞(请求已提交、响应未回), 这时判失败会把一次正常执行的响应丢掉。 - 测试做法:在同一测试库上**重建引擎实例**(新建一个 `Orchestrator`,内存态清空)模拟重启, 断言续跑——见 `RestartRecoveryTest`。 ## 人工介入(人工推进 / 人工重跑 / 人工停止) 系统误判(回调超时 / 轮询判失败 / 触发失败 / 回调报失败)或人工停止留下的都是同一个「该步最新执行已失败、 实例已失败」。并行分支下可能同时有多个失败步,补救动作都按(实例,步骤 `order`)寻址、逐个处理: | 方法 | 路径 | 说明 | | ------ | ------------------------------------------- | -------------------------------------------------- | | `POST` | `/api/instances/{id}/steps/{order}/advance` | 人工推进:确认该失败步已完成,实例越过它继续往后 | | `POST` | `/api/instances/{id}/steps/{order}/rerun` | 人工重跑:把该失败步再执行一次(新建一条任务执行) | | `POST` | `/api/instances/{id}/steps/{order}/stop` | 人工停止:把该步运行中的执行就地判失败 | - **人工停止**:把该步**最新一次、尚未终态**的执行判失败(`message = "人工停止"`),实例按聚合规则变失败。 只停本地,**不通知、不取消外部任务**——外部任务可能仍在执行;之后到达的回调 / 轮询 / 触发结果一律忽略 (先落定者赢)。可停范围是 `STARTED` / `WAITING_CALLBACK` / `POLLING`,不要求实例处于运行中; 不级联,其它并行分支继续跑完。停后仍可人工重跑或人工推进。不可停(未执行 / 已终态 / 重复停止)返回 **409**。 - **人工推进**:把指定步骤的最新执行置「人工确认成功」(`MANUALLY_SUCCEEDED`,与系统判成功区分开), 把它的后继并入 `ready_orders`,再按**所有步骤的最新执行**重算实例状态:还有别的失败步则仍为失败 (就绪步骤先记着,等失败分支处理完后由扫描推进),否则回「运行中」;此时若全部步骤都已成功 (包括确认的是最后一个步骤)则实例直接判成功。后继照例由调度扫描触发(见上文),不在此处分叉出 第二条推进路径。请求体可选 `{"output": ...}`,给了就存进该次执行,供下游 `{{step..output.}}` 引用。 - **人工重跑**:为**指定步骤**新建一条任务执行(`attempt_no + 1`)并**立即重新触发**,旧执行记录**保留**; 不限次数。重算后若没有别的失败步,实例回「运行中」,该步由这次新执行重新等待 / 轮询;若还有别的 失败分支,实例保持失败。每次执行有**独立的随机 taskId**,所以旧执行(旧 taskId)的**迟到回调** 命中的是那条已判定的旧执行、被忽略,不会误触发新执行。 - 人工推进与人工重跑都只能作用于「实例处于失败态、且**指定步骤自己的最新执行**已判定失败」,否则返回 **409** (不静默忽略,免得人工误以为已生效);实例不存在返回 **404**。 ## 运维查询(实例 / 任务类型) 没有前端时,Swagger 页面就是临时的操作面板;下面这组只读接口用来**看进度、捞出待处理的实例**: | 方法 | 路径 | 说明 | | ------ | --------------------------- | ----------------------------------------------------------- | | `GET` | `/api/instances` | 实例列表,按定义(`defId`)与状态(`state`)过滤,两者都可省略 | | `GET` | `/api/instances/{id}` | 实例详情:每个步骤、以及该步**每次任务执行**的状态与时间戳 | | `GET` | `/api/task-types` | 列出已注册的任务类型 code 及其触发 / 结束感知方式 | - **捞出失败待处理的实例**:`GET /api/instances?state=FAILED` 返回所有失败实例(含失败挂起、 尚未人工处理的),每行给出 `id`、`defId`、`state` 与时间戳(没有单一的 `currentOrder`)。再查 `GET /api/instances/{id}`,从 `steps` 里 `state` 为 `FAILED` 的步骤取 `order`,即可调用人工推进 / 人工重跑;并行分支下这样的步骤可能有多个,逐个处理。 - **实例详情**列出的步骤取自实例**冻结的快照**(ADR-0003),与在跑的实例一致、与定义后来是否被改无关; 未开始的步骤也会列出、其执行清单为空。每一步带 `stepName`、`remark`、`nextStepOrders` 与 `config`,其 `state` 是该步**最新一次任务执行**的状态(尚未执行则为 `null`)。 - 并行下没有唯一的「当前步骤」:详情顶层的 `currentStepOrders` 是推导值——最新执行尚未终态的步骤, 加上 `ready_orders` 里已就绪但尚未建执行的步骤——可能有多个,按步骤号升序。 - 详情里每一步的 `executions` 按发生顺序列出**该步的每次任务执行**(重跑留下的多条都在), 每条含 `attemptNo`、`taskId`、`state`、`message` / `output` 与 `startedAt` / `deadlineAt` / `nextPollAt` / `pollCount` / `finishedAt` 等字段。 ## 进度 已实现 ticket `01 — 工程骨架与业务任务定义 CRUD`、`02 — 触发实例 → 触发首步 → 回调完成 → 实例成功`、 `03 — 线性串联:成功推进 / 失败即停`、`04 — 轮询型结束感知`、`05 — 截止时间(轮询 / 回调共用)`、 `06 — 重启恢复`、`07 — 人工推进`、`08 — 人工重跑`、`09 — 实例与任务类型查询接口`、 `10 — cron 定时触发`、`11 — 独占实例`、`12 — 步骤间数据流转` 与 `13 — 人工推进补填输出`。 此外,步骤图与并行分支(ADR-0009 / ADR-0014)、业务任务结束回调(ADR-0007 / ADR-0008)、 定义导入/导出(ADR-0015)也已落地。