[待开发]Workflow 运行与发布契约 ADR

[JAVA-LW]

Issue 元数据

• 标题：[待开发]Workflow 运行与发布契约 ADR
• 层级：L1 Decision Issue / ADR
• 分级：G3 Cross-Domain Decision
• 标签：type:design area:workflow area:api area:runtime level:l1 grade:g3 priority:p1 risk:high size:m phase:ready needs-adr contract parent-issue child-issue
• 父 issue：[待开发]Workflow 产品形态一期闭环 #1186
• 子 issue：[待开发]Workflow 后端 contract 与运行入口 #1188、[待开发]Workflow 前端应用页与编辑体验 #1189

已确认事实

• Parent issue: [待开发]Workflow 产品形态一期闭环 #1186
• 用户确认 Workflow 采用 balanced 方向：作为 ApplicationType::Workflow 的正式产品形态，复用现有 orchestration runtime / logs / monitoring，不新建平行顶层资源。
• 用户确认 workflow 起止节点必须是专属节点类型，例如 workflow_start、workflow_end；后续 workflow 专属节点也按应用类型命名空间区分。
• Workflow 目标支持定时触发、API 触发、自定义 /api/ex/{slug}、同步 / 异步运行和同步自定义返回值。
• 用户确认 workflow 没有独立 API 页；扩展接口必须注册到全局 OpenAPI。

ADR 草案

Context

AgentFlow 已稳定，但 Workflow 的定位是系统工作流内置工作补充，不应继续暴露 AgentFlow 的聊天 / Agent API 语义。仓库已有 Application、flow、orchestration runtime、public API docs、logs、monitoring 和 TaskQueue 基础能力。

Decision

• Workflow 作为 Application 的一个正式类型，不新建顶层资源。
• Workflow 使用专属节点 contract：workflow_start 定义输入参数和同步超时时间，workflow_end 定义返回字段。
• Workflow 创建 / 配置前选择触发器；触发器至少包含扩展接口触发器和定时触发器。
• 扩展接口触发器使用全系统唯一的 /api/ex/{slug}；保存时验证 slug、方法、路径参数、query 参数、form 参数、body 参数，冲突或无效则失败。
• 扩展接口触发器支持全部 HTTP 方法；参数来源覆盖 URL/path、query、form、body，参数抽取方式参考 settings/mcp-management 的 interface 参数处理模式。
• 扩展接口认证方式和当前扩展接口保持一致，不为 workflow 另造认证模式。
• /api/ex/{slug} 由稳定 dispatcher 进入后端发布配置；具体路径、方法、参数和响应 schema 注册到全局 OpenAPI。
• 同步模式返回 workflow_end 投影，成功时直接返回字段对象；异步模式返回 run_id/status；同步等待或超过 workflow_start 超时时间返回 202 + run_id/status。
• 定时任务第一版创建异步 run；失败即记录 failed，不做复杂重试、死信或补偿。

不可协商不变量

• 不使用 start / answer 作为 workflow 专属起止节点类型名。
• API 字段名保持后端 DTO / 领域语义，不为 UI 展示造别名。
• Workflow 专属复杂度归属到 workflow schema、compiler / runtime adapter、publish contract 和 workflow 页面内部，不扩散到 AgentFlow 调用点。
• /api/ex/{slug} 不开放给 runtime plugin 任意注册 host route。

待验证假设

• 现有 compiled plan 和 output projection 能支持 workflow_end 返回字段投影。
• 现有 OpenAPI 构建链可以扩展为读取已发布 workflow 扩展接口并注册全局动态路径。
• TaskQueue 能支撑异步运行入口和定时触发第一版，不需要在本阶段引入完整调度平台。

不采用方案

• Conservative：仅启用 workflow 类型并复用 AgentFlow 编辑器和 /api/agent/v1/runs。
• Aggressive：新建 workflow domain、独立运行时、独立 run 表、独立 OpenAPI 注册系统。
• 不限制第一版只支持 POST 或 body-only 参数。
• 不把具体 /api/ex/{slug} 只放到应用内 API docs。

验收证据

• ADR 里的节点命名、触发器、API path、sync / async 响应、全局 OpenAPI 归属能被 L2/L3 issue 追溯。
• 子 issue 实现未越过本 ADR 约束。

执行边界

• 主要模块：domain application/flow schema、orchestration runtime compiler/projection、application public API/docs、frontend workflow page.
• 验证：每个 L2/L3 使用本 ADR 作为 contract source of truth。
• 停止 / 升级条件：如实现需要破坏 Application 现有 section contract、引入独立 runtime、开放插件任意注册路由或引入完整 HA scheduler，回到本 ADR 重新决策。

生命周期

• 当前阶段：ready
• 关闭条件：直接子 issue 完成并且 ADR 决策没有被实现期新事实推翻。