forge_admin/code-copilot/changes/定时任务优化/spec.md

定时任务优化路线图

status: complete created: 2026-07-17 revised: 2026-07-19 complexity: 🔴复杂 decision: 原单体方案停止直接 apply，拆分为独立小版本

1. 背景与结论

现有定时任务模块存在数据库与 Quartz 不一致、任务标识编辑后遗留旧 Job、启动恢复链路未启用、调度异常被吞为 boolean、查询未进入 Mapper XML、日志筛选和脱敏不完整等真实问题，必须先完成可靠性加固。

原方案同时纳入一次性任务、独立时区、并发、重试、Misfire、告警、开放 API、出站安全和 Flowable 编排，Phase 0/1 单次预估达到 28～42 人日，超出一次“定时任务优化”的合理边界。本变更改为总路线图，不再作为直接执行目标；后续只对下列子变更逐个确认和执行。

2. 拆分原则

• 每个版本必须能独立构建、验证、上线和回滚。
• 当前版本只创建自身运行时会读取的字段、字典、权限和接口。
• 可靠性问题优先于产品能力；没有真实场景的功能不提前建设。
• Quartz 表达式保持唯一 Cron 持久化口径，既有状态值保持兼容。
• Open API、出站请求和 Flowable 分别接受安全或流程专项评审。
• 每个子变更进入验证前单独创建并维护 test-spec.md 和 execution-log.md。
• 所有前端版本统一遵循 定时任务 UI 参考，优先让用户理解“执行什么、什么时候执行、现在是否正常”。

3. 版本路线图

版本	子变更	核心目标	依赖	建议优先级
V1	定时任务可靠性加固	修复 DB/Quartz 一致性、启动恢复、校验、日志安全和测试缺口	无	必做
V2	定时任务配置工作台	用户可理解的任务列表、全屏编辑工作台、执行目标选择和 Cron 计划预览	V1	建议
V3	定时任务一次性与时区	ONCE 调度、独立 IANA 时区和已结束状态	V1、V2	按需
V4	定时任务并发重试治理	禁止并发、跳过、有限重试和两类 Misfire	V1；启用 ONCE 时依赖 V3	按需
V5	定时任务运维日志监控	日志详情/导出、留存和轻量监控摘要	V1、V4	按需
V6	定时任务告警权限审计	消息告警、资源权限和写操作审计	V1、V5	按需
V7	定时任务开放API	服务账号 Token、Scope、幂等触发和执行查询	V1、V4	独立安全评审
V8	定时任务出站安全	统一 URL 白名单、SSRF 防护和受控 HTTP 客户端	无；Webhook/流程 API 节点使用前必须完成	独立安全评审
V9	定时任务Flowable编排	定时启动已发布流程并关联真实流程实例	V1、V8	独立流程评审
V10	定时任务扫描问题修复	关闭安全绕过、状态悬挂和并发一致性缺口	V1-V9	必做修复

4. 推荐实施顺序

第一轮只实施 V1。V1 稳定运行后，按实际需求选择：

1. 需要让用户能够看懂和配置任务：实施 V2。
2. 确有单次执行或跨时区任务：实施 V3。
3. 确有重复执行、副作用或 Misfire 问题：实施 V4。
4. 运维规模增长后：实施 V5。
5. 需要失败通知和分权管理：实施 V6。
6. 外部系统需要触发任务：单独评审并实施 V7。
7. 需要 Webhook 或流程 API 节点：先实施 V8。
8. 需要定时启动技术流程：最后实施 V9。
9. V1-V9 完成后执行整体扫描并实施 V10 收尾修复。

5. 统一兼容规则

• 保留 sys_job_config.status 的 0=停止、1=运行语义；V3 才新增 2=已结束。
• 保留 sys_job_log.status 的 0=失败、1=成功语义；V4 才扩展运行中和跳过。
• V1 冻结 (job_name, job_group) 为不可编辑调度身份。
• 所有查询 SQL 写入 Mapper XML 并显式过滤 del_flag=0。
• 普通任务删除继续逻辑删除；日志留存清理可使用专用物理清理 SQL。
• 内置字典和资源 tenant_id 固定为 1，迁移脚本必须具备防重复保护。
• 不修改已执行 Flyway 脚本；各子版本在 apply 时使用当时最大版本号加一。

6. 明确排除

• 不建立 mes_job、mes_job_log 或第二套流程设计器。
• 不开放任意 Java、Shell、SQL、Script 或不受控 SpEL。
• 不把内部 /job/executor/execute 作为开放 API。
• 不在缺少容量证据时修改 MySQL 分区。
• 不把 MES 模板写入 required seed。

7. 执行日志

Task	状态	实际改动文件	备注
单体方案评估	complete	原 spec.md、tasks.md、现有 job 源码	确认原 Phase 0/1 范围过大
小版本拆分	complete	本路线图及 9 个子变更目录	原单体方案停止直接 apply
V1 Implementation	complete	定时任务可靠性加固	7/7 Task 完成，验证记录见子变更 execution-log.md
V2 Implementation	functional-complete	定时任务配置工作台	功能、单测、Lint 和构建完成；UI 由用户自行验收
V3 Implementation	complete	定时任务一次性与时区	Job 63/63、前端 10/10、前后端构建和静态检查通过；UI 由用户自行验收
V4 Implementation	complete	定时任务并发重试治理	Job 84/84、前端 13/13、前后端构建和静态检查通过；真实 Redis/Flyway 留待环境验收
V5 Implementation	complete	定时任务运维日志监控	Job 94/94、前端 16/16、Admin Reactor 42/42 和生产构建通过；真实数据库/API 留待环境验收
V6 Implementation	complete	定时任务告警权限审计	Job 106/106、前端 18/18、Admin Reactor 42/42、生产构建和静态检查通过；真实消息/权限/审计留待环境验收
V7 Implementation	complete	定时任务开放 API	Job 137/137、前端 463/463、Admin Reactor 42/42、生产构建和静态检查通过；真实 Flyway/Bearer/Redis/Quartz 留待环境验收
V8 Implementation	complete	定时任务出站安全	Starter 47/47、Flow 12/12、Flow Reactor 32/32、Admin Reactor 43/43 和静态安全门禁通过；真实 Flyway/DNS/Webhook E2E 留待环境验收
V9 Implementation	complete	定时任务 Flowable 编排	Job 48/48、Flow 7/7、Remote Client 6/6、Flow API 权限 1/1、前端 25/25、Flow/Admin 聚合构建和静态门禁通过；真实流程 E2E 留待环境验收
V10 Implementation	complete	定时任务扫描问题修复	Job 178/178、Outbound 48/48、Remote Client 9/9、前端 29/29、Flow/Admin 聚合构建和静态门禁通过；真实集群、RPC、登录态 UI 和 Flow E2E 留待环境验收

8. 确认记录

• 用户于 2026-07-19 要求将定时任务改造拆分为独立小版本。
• 用户于 2026-07-19 确认继续优化，V2 按拆分路线进入 /apply。
• 用户于 2026-07-19 要求继续 V3，但不执行 UI 自动化验收，由用户自行验证界面。
• 用户于 2026-07-20 要求执行下一步任务，V4 完成实现和自动化验收。
• 用户于 2026-07-20 要求继续下个阶段，V5 完成实现和自动化验收；下一候选阶段为 V6 定时任务告警权限审计，尚未进入 apply。
• 用户于 2026-07-20 要求继续后续阶段，V6 完成实现和自动化验收；下一候选阶段为 V7 定时任务开放 API，尚未进入独立安全评审和 apply。
• 用户于 2026-07-20 授权继续并要求进入下阶段，V7 完成实现、安全审查和自动化验收；下一候选阶段为 V8 定时任务出站安全，尚未进入独立安全评审和 apply。
• 用户于 2026-07-21 要求继续，V8 完成实现、安全复核和自动化验收；下一候选阶段为 V9 定时任务 Flowable 编排，尚未进入独立流程评审和 apply。
• 用户于 2026-07-21 确认开始开发，V9 完成固定定义编排、独立 Flow 安全适配、权限复核和自动化验收；真实 Flyway、技术身份、FLOW_API 白名单、Token 和流程 E2E 由用户侧验收。
• 用户于 2026-07-21 要求整体扫描并开始修复，V10 完成执行器认证、RPC 受控出站、日志恢复、调度收敛、Flow 恢复和前端契约修复；真实环境项由用户侧验收。