forge_admin/code-copilot/changes/定时任务可靠性加固/spec.md

定时任务可靠性加固

status: complete created: 2026-07-19 complexity: 🟡中等 parent: code-copilot/changes/定时任务优化/spec.md version: V1 ui-baseline: code-copilot/changes/定时任务优化/ui-reference.md

1. 背景与目标

本版本只修复现有 Cron 调度中心的正确性和安全缺陷，不增加一次性任务、独立时区、并发策略、告警、开放 API 或流程编排。

完成后应满足：

• 管理端保存成功时，数据库期望状态和 Quartz 运行态差异可见、可手动重试。
• 服务启动时可以按数据库恢复缺失的 Quartz 任务，不删除非 Forge 管理任务。
• job_name/job_group 创建后不可编辑，避免遗留旧 JobKey。
• Cron、JSON 参数和 BEAN/HANDLER/RPC 执行目标由后端权威校验。
• 任务和日志查询进入 Mapper XML，日志时间筛选真实生效。
• 日志参数、结果和异常受控脱敏、限长，调度失败不再静默返回 false。
• job 模块建立可重复运行的单元测试基线。

2. 代码现状

• SysJobConfigServiceImpl.addJob 先写数据库再注册 Quartz，且事务注解被注释。
• SysJobConfigServiceImpl.updateJob 使用请求中的新 JobKey 更新 Quartz，改名可能遗留旧任务。
• JobScheduler 捕获所有异常并返回 boolean，事务和上层无法区分失败原因。
• JobConfigLoader 的 Component 注解被注释，数据库任务启动恢复未启用。
• JobAutoRegistrar 只在数据库没有记录时注册，不恢复缺失 Quartz 任务，也不按 job_group 精确匹配。
• 任务和日志分页仍在 Service 使用 LambdaQueryWrapper。
• QuartzJobExecutor 和 JobMonitor 会记录任务参数与结果，缺少结构化脱敏。

3. 功能范围

• 引入 JobConfigQuery、JobConfigSaveRequest、JobConfigVO，Controller 不再直接接收或返回 Entity。
• 增加 Cron、JSON 参数、执行目标和不可编辑 JobKey 校验。
• 将任务分页、任务详情、启动恢复候选和日志分页迁移到 Mapper XML。
• JobScheduler 改为抛出明确业务异常，不再用 false 表达调度异常。
• sys_job_config 仅增加 sync_status、sync_error、sync_time、version。
• 数据库作为期望状态；管理命令提交后同步 Quartz，失败标记 FAILED 并提供手动重试。
• 启动时执行一次幂等对账，只恢复或更新 Forge 管理的数据库任务。
• 注解任务只登记数据库期望配置，再复用统一同步入口。
• sys_job_log 增加 job_config_id、trigger_type，区分 UNKNOWN、SCHEDULED、MANUAL。
• 日志查询支持真实时间范围，参数、结果和异常脱敏限长。
• 补齐配置校验、同步、恢复、日志查询和脱敏测试。

4. 明确不做

• 不增加 60 秒周期对账；启动恢复和手动同步足够覆盖本版本。
• 不引入 Redisson 调度写锁；使用乐观版本和幂等同步控制管理端低频写入。
• 不改变现有超级管理员管理边界，不建设细粒度角色模板。
• 不增加一次性任务、任务时区、Cron 向导、重试、并发、Misfire 或告警。
• 不创建任务类型、流程调用方式等占位字段。

5. 数据变更

表	字段/索引	说明
sys_job_config	sync_status、sync_error、sync_time、version	最小同步可见性和乐观锁
sys_job_config	idx_job_sync_status_del	同步失败查询
sys_job_log	job_config_id、trigger_type	稳定关联任务并区分计划/手动
sys_job_log	idx_job_log_config_trigger	任务日志查询

迁移必须保持既有 0/1 状态语义，并使用 information_schema 或 NOT EXISTS 防重复。

6. 接口变更

接口	变更
GET /job/config/page	使用 Query/VO，返回同步状态
GET /job/config/:id	返回 VO
POST/PUT /job/config	使用 SaveRequest 和服务端校验
POST /job/config/:id/sync	手动重试数据库到 Quartz 同步
GET /job/log/page	支持任务、状态和时间范围筛选

7. 风险与验证

• Quartz 与业务表无法共享本地事务，本版本通过期望状态、失败可见和幂等重试收敛。
• 启动对账必须只处理带 Forge 管理标记或数据库匹配的 JobKey，禁止清理 Quartz 框架或其它模块任务。
• 验证覆盖新增、编辑、启停、删除、手动触发、Quartz 故障、重启恢复和日志脱敏。

8. 确认门禁

• 确认本版本保持平台超级管理员控制面。
• 确认不增加 owner_org_id 和普通租户自助任务。
• 确认 V1 只做 Cron 可靠性，不包含一次性任务和独立时区。

9. 执行日志

Task	状态	实际改动文件	备注
Proposal	complete	spec.md、tasks.md	从原单体方案拆出
Implementation	complete	Task 1-7 已完成	V1 代码、静态检查、模块测试和聚合构建完成
Task 1 最小数据库迁移	complete	V1.0.40 迁移、迁移契约测试、测试依赖	契约测试 7/7 通过，占位符扫描与 diff 检查通过
Task 2 协议、校验和 XML 查询	complete	DTO/VO、校验器、实体字段、Mapper/XML、分页接口	job 模块测试 16/16 通过，XML 与格式检查通过
Task 3 Quartz 异常和幂等同步	complete	JobScheduler、JobScheduleCoordinator、Service/Controller 写链路	job 模块测试 21/21 通过，调度失败状态可见且可重试
Task 4 启动恢复和注解登记	complete	JobAutoRegistrar、JobStartupReconciler、删除旧 JobConfigLoader、恢复契约测试	job 模块测试 26/26 通过，缺失任务可恢复且不清理非 Forge Job
Task 5 日志筛选和安全裁剪	complete	JobLogSanitizer、JobMonitor、QuartzJobExecutor、日志读取清洗、时间筛选格式	job 模块测试 33/33 通过，前端定向 ESLint、XML 和格式检查通过
Task 6 Controller 和前端同步状态	complete	同步重试接口、保存失败提示、任务列表信息架构和同步操作入口	job 模块测试 35/35、前端定向 ESLint 和生产构建通过；真实数据 UI 联调留待开发环境
Task 7 回归验证	complete	手动触发同步门禁、最终模块/聚合/前端回归、文档收尾	job 测试 37/37、Admin 42/42、前端构建通过；浏览器联调受沙箱端口权限阻断

10. 确认记录

• 确认时间：2026-07-19
• 确认内容：按路线图从 V1 开始；保持平台超级管理员控制面；不增加 owner_org_id、普通租户自助任务、一次性任务或独立时区。