pigx/db/migration/20261014_flow_first_batch.md

流程第一批能力升级

范围与入口

• 流程设计器：保存设计草稿、设计草稿箱；保存基本信息、表单和节点树，不部署流程。
• 流程列表：申请草稿箱；动态表单发起抽屉可保存表单值和自选审批人。按用户和租户隔离，版本号防止多窗口覆盖。
• 待办页：流程通知，包含任务分配、发起人催办和超时提醒；点击通知沿用现有任务详情权限检查。历史通知可能对应已完成或已转交任务。
• 我发起的：运行中流程可催办，同一实例十分钟内最多一次；仅发起人可以操作。回调记录可查看状态和手动重试失败事件。
• 审批节点 / 事件通知：配置自然时长分钟数，0 或留空关闭；最多 525600 分钟。计时基于任务创建时间，不因转交重新计时，到期只提醒当时的当前审批人一次。

本批申请草稿适用于流程引擎的动态表单。自定义业务组件自行提交、拥有独立的数据模型，继续由业务页面保存草稿；未擅自修改业务表单合同。申请草稿记录发布 deployment ID，恢复时版本变化会拒绝自动恢复并保留原草稿。普通草稿只在明确保存或设计器点击下一步时持久化，未保存的输入不会自动落库。

升级顺序

1. 备份数据库并停止本次流程写入，确认上一次节点版本隔离迁移已经完成。
2. 在流程与引擎使用的同一 MySQL 数据源执行 20261014_flow_first_batch.sql。新增 flow_draft、flow_notice、flow_callback 三张表，不改动存量业务表；新装脚本 0pigxx_boot.sql、3pigxx_flow.sql 已包含相同建表语句。
3. 部署后端与管理端。不要混用新旧后端：旧版本不会创建持久回调与通知记录。
4. 使用测试租户检查保存和恢复两类草稿、任务分配与转交、催办限频、到期提醒、回调 503 后重试。

新部署的监听器负责此后发生的任务事件；不自动重放过去的任务通知或已完成回调，不自动为已存在且没有再次分配的任务补建超时记录。

已安装五表版本的兼容升级

仅已经执行过旧五表脚本的环境需要此步骤；新装或尚未安装本批能力的用户只执行三表建表脚本。

1. 停止旧后端及其他流程写入，完整备份原五张表。恢复备份前也必须停止新后端，不能混跑两版。
2. 执行三表建表脚本 20261014_flow_first_batch.sql，再执行 20261014_flow_merge_tables.sql（使用支持 DELIMITER 的 MySQL 客户端）。合并脚本只补字段和索引；数据部分使用事务。发生异常时数据部分回滚，已完成的 DDL 保留，排查后可重新执行。
3. 合并脚本保留所有草稿和现有通知的 ID、已读状态；把超时监听关联到已有超时通知，或转换为待触发记录。已提醒的监听不会重新排队；未启用截止时间的旧记录为 DISABLED。旧回调的 ID、状态、次数、租约、地址和载荷保持原值，尝试历史按原 ID 合入 JSON 数组。孤立审计记录会报错并回滚，不会静默丢弃。
4. 核对下面两个查询结果均为 0，并核对备份中的草稿、通知和回调业务字段。合并脚本可重复执行，不会重复追加历史或重置已处理的提醒。
5. 旧 flow_task_watch 和 flow_callback_attempt 默认保留为只读核对来源，新代码不再访问。确认备份可用、迁移完整后可清理这两张旧表。旧监听中的 last_urge_at 仅写不读，原值保存在旧表和备份；催办限频仍以通知记录为准。

-- 未迁移的监听数
SELECT COUNT(*) FROM flow_task_watch w
WHERE NOT EXISTS (
 SELECT 1 FROM flow_notice n WHERE n.tenant_id=w.tenant_id AND n.reminder_key=w.task_id
);
-- 未迁移的回调尝试数
SELECT COUNT(*) FROM flow_callback_attempt a
LEFT JOIN flow_callback c ON c.id=a.callback_id AND c.tenant_id=a.tenant_id
WHERE c.id IS NULL OR JSON_SEARCH(COALESCE(c.history,'[]'),'one',a.id,NULL,'$[*].id') IS NULL;

事务和投递约定

• 通知与回调写入使用 JdbcTemplate，与 Flowable 共用 Spring 事务及数据源；独立监听器 isFailOnException=true，写入失败会回滚任务操作，避免任务完成但回调丢失。
• 新表 SQL 显式指定租户、用户或引擎事件身份；后台跨租户扫描仅取内部记录，HTTP API 不允许指定他人的用户或租户。
• flow_notice 同时保存已生成通知和待触发提醒。status 区分 PENDING、SENT、CANCELLED、DISABLED；通知列表和已读操作只接受 SENT。reminder_key 按租户和任务唯一，到期才确定当前接收人；任务结束取消尚未发送的提醒，已发送记录保留。任务暂停或暂无处理人时保留 PENDING，将 scheduled_at 推迟十秒后再检查，避免占满最早一批扫描记录；恢复后继续发送，不重新计算完整超时时长。
• 后台默认每轮完成后间隔 10 秒扫描，可配置 flow.delivery.scan-delay（毫秒）。回调与提醒使用本模块独立的两线程调度器；每批上限为 20 个回调、100 个提醒，不承诺精确到秒的触发。
• HTTP 回调使用任务完成时固定的目标地址、JSON 载荷和事件 ID。只接受 2xx；重定向、其他状态码、网络错误均进入失败处理。请求超时 10 秒，不携带用户 Bearer token。
• 首次共尝试 5 次，失败后按 30、60、120、240 秒退避。60 秒租约与条件更新允许多实例竞争；进程崩溃后可回收过期租约继续投递，达到尝试上限的未知结果标为失败。
• 请求头 X-Flow-Event-Id 和 Idempotency-Key 使用同一个稳定事件 ID。语义是至少一次投递：接收方必须把事件 ID 去重与自身业务写入放在同一事务中，才能避免“已处理但响应丢失”造成重复副作用。
• 手动重试仅允许实例发起人对失败记录操作，保留事件 ID、目标和载荷，再给予 5 次尝试。累计次数不清零。
• flow_callback.history 以 JSON 数组保存每次尝试和手动重试的审计记录，与主记录状态在同一事务中更新，不截断历史。审计归属由父记录的租户和事件 ID 确定。STARTED 表示尝试已开始但没有确认结果；可能是进程退出或租约失效。页面只展示状态、次数和最近结果，不返回回调载荷和目标 URL。
• 本批可靠投递针对节点“事件通知”HTTP 回调；同步触发器业务调用、Redis 流程状态广播维持原有行为。

验证证据

FlowWorkspaceTests 使用真实 Spring Flowable、共享事务的 H2、生产建表语句（H2 MySQL 兼容模式）和本地 HTTP 服务，覆盖草稿持久化、所有者隔离、乐观锁、分配/转交通知、超时去重、催办限频、503 重试、固定事件 ID，以及回调写入失败后引擎任务回滚。H2 验证不等同于真实 MySQL 或完整应用运行验证。

相关既有节点版本、会签和任务服务测试一并执行。管理端进行指定文件 ESLint、Prettier、Vue SFC 编译，以及已有版本隔离浏览器回归。三表合并额外验证了历史追加、手动重试保留旧历史、已完成任务不再提醒。迁移在本地 OceanBase seekdb 的临时数据库使用带数据样本验证，并检查重复执行和孤立审计回滚；临时库测试后清理。真实账号完整联调尚未执行，不把接口隔离回归当成真实后端验收。