工作流定义与运行管理
# 工作流定义与运行管理
# 目的
使用真实Vben页面发布不可变流程版本、单独启停新发起准入，并按明确实例处理取消、任务补分配或外部动作恢复。 平台管理员另有全局运行目录，完成当前构建登记、关闭准入、查看引用、退役和重开。成功以服务端命令确认及刷新后的状态为准。
# 前置条件
业务库先备份并显式迁移至schema v48，启动与数据库构建相符的API。工作流默认关闭；平台目录可独立开启， 发布/启用和发起还要求兼容的实际API及worker池。配置、启动与首次登记见工作流API。 浏览器配置精确Origin，继续使用统一认证及明文JSON或生产JWE，不手动拼接租户身份。
# 外层仓库根目录，先通过当前环境YAML/环境变量配置数据库；不在命令或日志中写连接凭据。
bash scripts/fago.sh migrate
# 成功后迁移元数据1–48连续且dirty均为false，再启动当前构建。
bash scripts/fago.sh api
菜单与按钮权限分开。普通角色须在角色授权页显式勾选菜单，同时拥有相应权限及套餐能力；迁移不会自动开通套餐或普通角色菜单。
平台运行目录权限只属于平台，不能据此读取租户流程。租户页面属于workflow.execution能力。
| 页面路径 | 菜单读取/进入权限 | 额外操作权限 |
|---|---|---|
/workflow/definitions | workflow:definition:read | 发布需workflow:definition:publish，启停需workflow:definition:manage |
/workflow/instances | workflow:instance:read | 取消及外部恢复需workflow:instance:manage |
/workflow/task-management | workflow:task:manage | 补分配仍由当前管理权限及目标资格共同裁决 |
/workflow/external-actions | workflow:instance:manage | 只能读取明确实例/激活并排队原操作 |
/platform/workflow/runtimes | platform:workflow-runtime:read | 目录命令需platform:workflow-runtime:write |
实例、任务和外部动作三个入口共用管理组件，按当前权限展示区域；只有任务管理权限时不会请求实例详情。 菜单显示不能替代服务端逐请求验证。身份、授权版本或页面范围改变会清空正文、目标和待重试载荷。
# 步骤与规则
# 登记与维护运行目录
平台进入“工作流部署→工作流运行目录”。首次目录为空时，从“当前实际构建版本”选择代码声明的精确版本， 点击“登记当前构建版本”，核对确认窗口中的版本与目录version=0，再确认。不能输入任意处理器、指纹、URL或凭据。 当前构建只表示API进程认识该版本，不等于已有兼容worker。
目录每页最多50项，使用“下一页/上一页”。列表只读安全元数据；点击一行“查看引用阻塞”才读取七类布尔快照， 包括可发起定义、活动实例、受理命令、命令工作、定时器、自动续跑和外部动作，不返回租户或实例标识。
enabled可“关闭新准入”进入draining；旧实例仍按原版本执行。关闭相关定义的新发起准入并排空全部引用后，
由“退役”在同一事务重新验证，成功变为retired。引用快照可能变化，不能当作删除或退役许可。
retired可“恢复退役版本”，兼容运行面仍须满足；恢复目录不会自动启用旧定义。重复登记也不会恢复draining。
# 发布和启停流程定义
租户进入“流程审批→流程定义与准入”。“版本与准入”读取明确key的版本元数据及所选版本规范JSON， “更早版本”按每批50条向前读取，也可输入精确发布版；列表不会逐行读取模型。
有发布权限时点击“发布新定义”，填写运行版本和完整规范JSON。新key的“当前最新发布版本”为0。 已有定义可从任意历史版“以此版创建新发布”，预期版本仍使用目录中最新发布版，不能用旧版号覆盖后续发布。 发布默认不启用；勾选“发布后允许新发起”仍需后台检查资源绑定和兼容池。
以下JSON填入“完整流程JSON”。先按表单API发布simple-request表单第1版，
将审批用户占位符替换为当前租户的有效用户ID；选择运行版本fago-form-approval-v2，首次最新发布版填0。
{
"schemaVersion": "fago-workflow-v1",
"key": "simple-approval",
"name": "简单审批",
"engineVersion": "fago-form-approval-v2",
"variables": [{"name":"amount","type":"integer","required":true}],
"resources": [{"type":"form-instance","contractVersion":"scalar-form-v1","formKey":"simple-request","formVersion":1}],
"nodes": [
{"id":"start","kind":"start","name":"开始","next":"approval"},
{"id":"approval","kind":"approve","name":"审核","mode":"single","next":"done","rejected":"reject","candidates":[{"kind":"users","ids":["<当前租户审批用户ID>"]}],"readFields":["amount"],"outputs":["amount"]},
{"id":"done","kind":"end","name":"通过","outcome":"approved"},
{"id":"reject","kind":"end","name":"拒绝","outcome":"rejected"}
]
}
成功显示“发布命令已确认”和返回的key/版号，刷新目录可核对准入。发布保留历史版；不会修改正在运行的旧实例。 “停用此版新发起/启用此版新发起”使用准入自己的version，和定义发布version独立。确认窗口明确列出两者。 停用只阻止新的发起，不取消已存在实例。
# 取消与任务补分配
进入任一实例管理入口，输入规范流程编号，点击“读取管理状态”。只按明确ID读取，没有全租户实例扫描。 取消使用屏幕读取的实例version，在“申请取消实例”后再次确认；有未结算外部效果时服务端拒绝，不能强行清理。
任务管理按items/next分页，“后续任务”可找到首批之后的任务；只读取任务元数据，不显示资源正文、意见或候选名单。
对可管理的任务点“补分配”，填一个规范正整数账号ID及原因，核对后提交。目标账号保留字符串，最大为9223372036854775807，
不转换为浮点。补分配使用任务version，发送空变量值，不能借此修改业务正文或绕过目标当前资格。
# 外部动作恢复
输入明确实例并读取，再输入外部动作激活编号；循环重入必须使用对应激活，不能只凭节点名猜测。 “读取外部动作”返回job安全状态和job版本，不返回原输入、响应、目标地址或凭据。
只有dead状态显示“重新排队原操作”；只有dead、原操作为execute且可能已有外部效果时才显示“申请补偿原效果”。
两者使用job版本，仅由服务端重新排队，后台执行器继续使用原输入和业务幂等键；补偿失败后的重试仍重试补偿。
切换实例/激活立即清掉旧job及晚到响应，不能把旧状态用于新激活。
# 参数
| 参数 | 规则 |
|---|---|
| 完整规范JSON/表单schema | UTF-8最多256KiB、最多64层；拒绝重复键、尾随JSON和未配对Unicode |
| 浏览器整数 | 必须是规范安全整数；拒绝01、-0、小数、指数和超出±9007199254740991的数值；后台int64合同未缩小 |
| 精确发布版、准入/任务/实例/job版本 | 浏览器要求安全整数；新发布允许0，其他CAS必须正数；各对象版本不能混用 |
| 目标账号ID | 一个规范正整数十进制字符串，最长到int64正上限；不支持多个目标或隐式默认账号 |
| 激活编号 | 规范正整数，浏览器还须能精确表示；超出安全范围拒绝而非舍入 |
| 运行目录游标/任务游标 | 使用服务端返回值；目录为nextCursor，实例任务为next，不手工生成或跨范围复用 |
| 大正文传输 | 只有已登记的定义/表单/草稿/发起及精确任务decision/return POST可用512KiB；普通接口仍16KiB、文件上传仍8MiB |
JSON在JSON.parse前检查，防止重复字段和大整数被浏览器静默改写。未知字段保留给后台严格拒绝；页面不代替语义编译器。
复制服务端模型时发现不能精确表示的整数会拒绝编辑，应使用保留完整int64的客户端；不会把舍入后的模型重新发布。
# 失败
页面只显示公开中文提示。400001是报文格式拒绝，400002是非法参数，403001是当前权限不足，403004是Origin/来源拒绝， 404001不区分不存在与不可见。409001是版本或同命令不同载荷冲突，关闭并刷新后再决定新动作；不要用新命令号盲重放。 409003表示准入、兼容池、引用或外部未知效果阻止当前操作，须处理原因。503001表示依赖或运行面暂不可用。
网络未知结果时使用“重试原发布/准入/目录变更/管理命令”，保留原commandId、版本和完整载荷。 关闭窗口只清本地状态，不撤销已发送事务。不能因输入框变化就用原命令发送另一份载荷。
{"code":409001,"data":null,"message":"记录已变更，请重试","requestId":"<服务器生成>"}
# 边界
本页是已接入真实接口的管理页面。表单与流程原稿、受控 BPMN 画布在独立设计页保存和发布，不在本页绘制。 本页不提供任意流程脚本、节点跳转、强制完成、外部原输入替换或历史实例迁移。外部补偿要求服务端已配置明确模板和接收方合同，浏览器不能添加目标。
组件测试使用真实Vue/Router/Ant，业务I/O替换；实库三协议测试是另一层证据。Work设置禁用浏览器时， 不把组件和构建通过表述为真实浏览器布局、完整端到端或生产认证。正式OpenAPI、其他accepted命令、 其他资源及完整滚动/容量组合验收继续，R3.1未结项。