Workflow HTTP 根路径为 /api/workflow，全部路由来自 Platform Application 命令与查询上的 [GenerateEndpoint] 声明，按 Tag 分组：Workflow-Runtime / Workflow-Tasks / Workflow-History / Workflow-Definitions / Workflow-Management / Workflow-Metadata / Workflow-Reports。写命令统一 RateLimitPolicy="userPolicy" 与 RequestTimeoutPolicy="WorkflowCommand"/"StandardCommand"；生成器以 RequireService=IWorkflowEngine（任务中心场景为 IWorkflowTaskCenterStore）做条件注册——未组合持久化适配器的 Host 上这些端点根本不会出现。最终请求/响应 Schema 应以当前构建 OpenAPI 为准。

1. 通用管线

所有生成路由要求认证并经 IAuthorizedRequest 进入模块/资源/动作统一授权；RateLimit 与 RequestTimeout 策略由各命令特性声明，运行时复杂写使用更长的 WorkflowCommand 超时。没有”手写入口绕过管线”的路径——新增能力只能声明新命令/查询，而不是另起 Endpoint 文件。

2. Definitions

Method	Route	用途
POST	/api/workflow/definitions/	部署定义快照
POST	/api/workflow/definitions/validate	静态校验
POST	/api/workflow/definitions/simulate	内存模拟
GET	/api/workflow/definitions/schema	设计器 Schema
GET	`/api/workflow/definitions/{key}/versions`	版本列表
GET	`/api/workflow/definitions/versions/{definitionId}`	指定版本
GET	`/api/workflow/definitions/{key}/active`	当前绑定版本
GET	`/api/workflow/definitions/{key}/deployments`	部署绑定
POST	`/api/workflow/definitions/{key}/deployments`	发布
POST	`/api/workflow/definitions/{key}/deployments/grayscale`	切换新 Active 并保留 Previous
POST	`/api/workflow/definitions/{key}/deployments/complete-grayscale`	仅完成状态标记
POST	`/api/workflow/definitions/{key}/deployments/rollback`	回到 Previous
GET	`/api/workflow/definitions/designer-schema`	设计器元数据（节点 ConfigFields/Resolver/Handler 目录）
GET	`/api/workflow/definitions/{key}/draft`	读取草稿修订
PUT	`/api/workflow/definitions/{key}/draft`	保存草稿（乐观 Revision 并发）
DELETE	`/api/workflow/definitions/{key}/draft`	删除草稿
POST	`/api/workflow/definitions/{key}/draft/validate`	校验已保存草稿
POST	`/api/workflow/definitions/{key}/draft/simulate`	模拟草稿路径
POST	`/api/workflow/definitions/{key}/draft/publish`	权威校验后发布不可变版本并更新绑定

Grayscale 路由不是百分比流量 API；draft/publish 才是设计器的完整校验闭环，遗留的 POST /api/workflow/definitions/ 仅要求 JSON 可编译。

3. Runtime

Method	Route	用途
POST	/api/workflow/runtime/instances	发起
POST	/api/workflow/runtime/instances/start-at-node	指定节点发起
GET	`/api/workflow/runtime/instances/{instanceId}/progress`	进度图
POST	`/api/workflow/runtime/tasks/{taskId}/complete`	审批通过
POST	`/api/workflow/runtime/tasks/{taskId}/reject`	驳回
POST	`/api/workflow/runtime/tasks/{taskId}/transfer`	转办
POST	`/api/workflow/runtime/tasks/{taskId}/delegate`	委派
POST	`/api/workflow/runtime/tasks/{taskId}/add-participant`	加签
POST	/api/workflow/runtime/tasks/batch-complete	管理代批，不推进流程
POST	`/api/workflow/runtime/instances/{id}/withdraw`	撤回
POST	`/api/workflow/runtime/instances/{id}/resubmit`	重提
POST	`/api/workflow/runtime/instances/{id}/terminate`	终止
POST	`/api/workflow/runtime/instances/{id}/cancel`	取消
POST	`/api/workflow/runtime/instances/{id}/reset`	重置节点
POST	`/api/workflow/runtime/instances/{id}/suspend`	挂起
POST	`/api/workflow/runtime/instances/{id}/resume`	恢复
POST	`/api/workflow/runtime/instances/{id}/remind`	催办
POST	`/api/workflow/runtime/instances/{id}/priority`	优先级
POST	`/api/workflow/runtime/instances/{id}/transfer-applicant`	申请人转交

操作者来自 ICurrentUser，不应在请求体提供。当前写请求没有 HTTP Idempotency-Key 契约。

4. Tasks

Method	Route	用途
GET	/api/workflow/tasks/todo	待办列表
GET	/api/workflow/tasks/todo/count	待办角标
GET	/api/workflow/tasks/done	已办
GET	`/api/workflow/tasks/{taskId}`	详情
POST	`/api/workflow/tasks/{taskId}/mark-read`	标记已读

详情端点当前受 TaskService 空 userId 缺陷影响；待办列表默认 ApplyDataScope=true，会走全量内存兼容路径。角标不应用 DataScope，可能大于列表。

5. History

Method	Route	用途
GET	`/api/workflow/history/instances/{id}/timeline`	实例 Timeline
GET	`/api/workflow/history/instances/{id}`	实例历史
GET	`/api/workflow/history/instances/{id}/trail`	审批轨迹
POST	`/api/workflow/history/instances/{id}/archive`	归档
GET	`/api/workflow/history/business/{businessKey}/timeline`	业务 Timeline
GET	`/api/workflow/history/business/{businessKey}/status`	业务状态汇总

BusinessKey 路由没有 tenant 参数；可信租户必须由当前上下文与 Store filter 强制。

6. Reports

/api/workflow/reports 下包括 instances、task-duration、approvers、bottlenecks、rejects、trends 与 deployments，代码生成器以 QUERY 暴露这些报表，并提供 /_query POST fallback。趋势路由是 QUERY /api/workflow/reports/trends：From 与 To 都必须提供，且 From≤To；缺失或逆序返回 Workflow.Report.PeriodInvalid。TenantId 只从 CurrentUser 取得，DefinitionKey 可选；Granularity 解析失败时当前回落为 Daily。

无 IWorkflowQueryStore 时可能返回成功空结果；趋势平均时长当前为零，不能当真实 KPI。

7. Management

Method	Route	用途
POST	/api/workflow/management/import	导入单条旧实例
GET	/api/workflow/management/statistics	引擎统计
DELETE	`/api/workflow/management/definitions/{definitionId}`	删除定义
DELETE	`/api/workflow/management/instances/{instanceId}`	删除终态实例
POST	`/api/workflow/management/tasks/{taskId}/refresh-candidates`	刷新任务候选
POST	`/api/workflow/management/roles/{roleId}/refresh-candidates`	按角色刷新

删除定义当前不检查活跃实例或部署引用；导入 TenantId 来自 Body，且非事务、非幂等。管理端点应限制到高权限运营角色并增加审计。

8. 调用示例

POST /api/workflow/runtime/tasks/task-123/complete
Authorization: Bearer {token}
Content-Type: application/json

{
  "comment": "同意",
  "variables": {
    "financeApproved": true
  }
}

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "title": "Conflict",
  "detail": "Workflow runtime concurrency conflict"
}

ProblemDetails 的精确 type/title/status 由 WorkflowResultExtensions 与 ProblemDetailsMapper 决定，客户端应按稳定错误 code/type 处理，不解析中文 detail。

9. 安全检查

所有 ID 路由做资源级授权，防 IDOR。
Tenant/Office 不从普通请求体信任。
PageSize、时间范围、变量大小和 Comment 长度有限制。
Definition JSON 与 Import Body 有请求体上限。
管理删除、重置、StartAtNode、导入和转交有增强审计。
限流与超时覆盖生成端点，不只手写 Group。

workflow.runtime Feature 现已被 WorkflowRuntimeLicenseGuard 在每次工作流写入和后台作业前强制执行；此项已交付。

10. 生成 OpenAPI

# 对照源代码列出路由。
rg -n "GenerateEndpoint|Map(Get|Post|Delete)" src/Platform/Workflow src/Hosts/BitzOrcas.Api/Endpoints/Workflow -g '*.cs'

# 运行 Host 后从 OpenAPI 生成客户端，禁止手写猜 DTO。
dotnet run --project src/Hosts/BitzOrcas.Api

下一篇：独立嵌入