MES 定时任务管理模块 · 产品需求文档

1. 文档概述与范围

1.1 目的

本文件定义 MES（制造执行系统）中「定时任务」模块的功能范围、业务流程、数据模型与交互规范，作为前端（Vben Admin）、后端调度/流程服务与测试验收的统一依据。原型见随附《MES定时任务模块_交互原型.html》。

1.2 范围

2. 业务背景与问题

MES 中大量运维与业务流程需周期性自动执行。当前任务散落在各微服务、由各团队手工维护 Cron，缺乏统一管控，存在不可视、不可控、无告警、难排查、高风险等问题。此外，两类新诉求凸显：

• 编排诉求：单个定时点往往要串起「采集 → 转换 → 校验 → 推送 ERP」等多步动作，纯单点调用目标难以表达，亟需 FlowNode 把多节点编排为一条可观测的执行流。
• 集成诉求：外部系统（ERP、WMS、低代码平台）希望在业务事件发生时主动触发 MES 任务/流程，并回查执行结果，需提供标准化开放 API 与 Token 鉴权。
• 易用性诉求：一线工艺/设备人员看不懂 6 段 Cron，配置易出错；需提供「说人话」的简单模式与可读化描述。

3. 术语与定义

4. 用户角色与权限

5. 功能需求清单（FR）

6. 关键功能详设

6.1 新建 / 编辑任务（FR-03 / FR-04）

表单在 v1.0 基础上新增「执行方式」：

6.2 Cron 双模式易用配置（FR-21 / FR-08）

触发方式分两类，由 schedule_type 区分：周期型（cron）走下方双模式配置；一次性（once）走独立「仅一次」表单（见 §6.2.4），二者不共用表达式。所有周期型任务后台统一存为 Cron 表达式并冗余一份中文可读描述。

6.2.1 简单模式（默认）= 频率向导 + 常用快捷

① 常用快捷（一键套用）：在向导上方提供高频预设 chips，点击即套用，覆盖一线最高频场景：每 5 分钟、每 30 分钟、每小时整点、每天 08:00、每天 20:00、每周一 09:00、工作日 08:30、每月 1 号 00:00。

② 频率向导（可视化配置）：按「业务语言」选择，全程不接触原生 Cron 语法：

时区说明：上述「每天 / 每周 / 每月」等时刻均以任务 timezone 字段为基准（FR-24，默认 Asia/Shanghai）。跨厂区部署时，各厂区任务以其本地时区解释 Cron，避免统一服务器时区带来的错时问题。

向导与「专家模式」下的 6 段表达式双向互转：编辑已有任务时，系统尝试将存量 Cron 反解析回最接近的向导配置；无法精确对应的复杂表达式（如多个不规则取值、步进组合）自动回退到专家模式，不丢配置。

6.2.2 实时反馈

• 中文可读描述：如「每周一、周三、周五 09:30:00 执行」，随向导选择实时刷新。
• 未来 5 次触发：由向导状态逐分钟精确推算真实日期时间（已验证跨天/跨周/跨月正确），帮助用户确认周期，替代硬编码示意值。

6.2.3 专家模式与校验

• 直接编辑 6 段表达式，适合不规则/复杂周期；实时语法校验（FR-08），非法不可保存。
• 周字段语义与映射规则：本模块向导/存储统一采用 0=周日 … 6=周六（与 JS/标准一致）。若调度内核为 Quartz（1=SUN…7=SAT），在落库/对接时按下方映射做双向转换，该约定须在 API 契约评审时锁定：

6.2.4 一次性任务（schedule_type = once，FR-23）

针对「某年某月某日某时执行一次」场景，不使用 Cron 表达式，而是独立表单选择日期 + 时刻（fire_once_time）。系统到点触发一次后，任务状态流转为「已结束」，不重复调度；到期前可编辑日期时刻或取消。

• 预览：展示唯一一次触发时间；若该时间已过去，提示「时间已过，保存后不会再次触发」。
• 落库：mes_job.schedule_type='once'、fire_once_time=datetime、cron_expression 留空。
• 回填：编辑「仅一次」任务时，回显日期时刻而非 Cron 向导（与周期型互不串）。

6.3 执行日志（FR-10 / FR-11）

• 列表字段：任务名、任务组、触发类型（自动/手动/API）、开始时间、耗时(ms)、状态、操作（详情）。
• 失败行可展开异常栈；流程任务可下钻到「失败节点」。

6.4 MES 任务类型枚举（FR-09）

6.5 FlowNode 流程编排（FR-19 / FR-22）

当任务「执行方式 = 流程」时，绑定一条 Flow。Flow 由节点构成，MVP 支持顺序执行与条件分支（轻量 DAG）。

编排交互：以「节点列表 + 连接线」方式呈现（后续增强为拖拽画布）；支持新增/删除/排序节点、配置节点参数、设置分支条件。每个节点独立记录执行状态与耗时，便于失败定位。

6.5.1 节点重试与整流程失败策略（FR-27）

为提升流程健壮性，每个节点可独立配置重试与超时（FR-27），整流程再统一约定失败处置方式：

6.6 开放 API 接入（FR-20 / FR-25）

对外暴露 REST 接口，供 ERP / WMS / 低代码等外部系统触发与查询；采用 Bearer Token 鉴权，Token 带作用域与有效期。

Token 管理：列表展示名称、作用域（任务组/流程）、有效期、状态；可创建/吊销；密钥仅创建时明文展示一次。

6.6.1 触发幂等（FR-25）

外网调用方常因网络抖动重试 POST 触发请求，若不幂等会导致同一业务事件被重复执行。约定如下：

• 调用方在触发请求头携带 Idempotency-Key: <唯一串>（建议 UUID 或「业务单号+动作」）；也可由网关按 Token + jobId/flowId + Body 指纹 自动生成。
• 服务端以 key 为键缓存执行记录，TTL 默认 24h：TTL 内重复 key 直接返回首次执行的结果（执行 ID / 状态 / 日志），不二次触发；TTL 外视为新请求重新执行。
• 幂等键与执行记录落 mes_job_log.idempotency_key，便于审计与排查。

6.7 失败告警与 Webhook 出站白名单（FR-12 / FR-26）

失败告警支持站内 / 邮件 / Webhook 三渠道（FR-12）。其中 Webhook 是最易引入 SSRF 风险的入口：恶意或误配的回调地址可能指向内网元数据服务（如 169.254.169.254）或内部系统，造成信息泄露或服务被打。规范如下（FR-26）：

• 出站白名单：所有 Webhook 目标 URL 的域名/网段/IP 须命中 mes_outbound_whitelist 表，未命中拒绝保存与发送。
• 内网保留段硬拦截：即使命中白名单，仍禁止解析到内网保留地址（10/8、172.16/12、192.168/16、127/8、169.254/16、::1 等），且禁用非 http/https 协议（如 file://、gopher://）。
• 发送安全：出站请求设短超时与大小上限；发送失败按固定上限重试（默认 3 次）后判失败，避免风暴；不回显响应体到任务日志。
• 白名单治理：白名单由管理员维护，支持域名 / CIDR / 精确 IP 三类，可启用/停用。

7. 数据模型

7.1 任务实体（mes_job）

7.2 执行日志实体（mes_job_log）

7.3 流程与节点实体

7.4 API Token 实体（mes_api_token）

8. 非功能需求

• 性能：任务列表首屏 < 800ms；日志按时间分区，单任务日志保留 ≥ 90 天。
• 可用性：调度引擎单点故障不影响已注册任务恢复；服务重启后按 Misfire 策略补偿。
• 安全：调用目标仅允许白名单 Bean / 内网 URL；开放 API 强制 Bearer Token 鉴权，按作用域最小授权，越权返回 403；Token 密文存储；触发接口支持 Idempotency-Key 幂等（TTL 去重，FR-25）；Webhook 告警地址须命中出站白名单并硬拦截内网保留段（防 SSRF，FR-26）。
• 流程引擎：节点失败支持重试（次数/间隔/退避/超时）+ 整流程失败策略（中止 / 跳过 / 告警后继续，FR-27）；单流程节点数 MVP ≤ 20，单节点超时可控。
• 审计：所有写操作与 API 触发均落审计日志，含前后值与调用方 Token。
• 兼容性：前端适配 Chrome/Edge 最新版；响应式支持 1280px 以上。

9. 交互与业务流程

10. 验收标准

• P0 功能（FR-01~08、10、21）全部可用。
• Cron 双模式：频率向导生成的 5 类表达式与专家模式一致；中文描述与实际调度一致（偏差 < 1 周期）；「未来 5 次触发」推算值与实际首次触发完全一致；存量 Cron 可正确反解析回向导或安全回退专家模式。
• 一次性任务（FR-23）：schedule_type=once 任务不写 Cron 表达式，仅存 fire_once_time；到点触发一次后状态流转为「已结束」且不再触发；编辑回显日期时刻而非 Cron；过期时间提示准确。
• 任务时区（FR-24）：同一 Cron 在不同 timezone 下展示/触发时刻正确；周字段在存储值与 Quartz 间按 §6.2.3 映射表双向一致。
• 流程编排：绑定流程的任务按节点顺序/分支正确执行；节点失败可在日志定位到 fail_node。
• 开放 API：合法 Token 在作用域内可触发并查询；无 Token / 越权 / 过期 Token 返回 401/403。
• API 触发幂等（FR-25）：同一 Idempotency-Key 在 TTL 内重复触发仅执行一次并返回首次结果；越 TTL 重新执行；幂等键落日志可查。
• Webhook 出站白名单（FR-26）：非白名单域名、内网保留段、非 http(s) 协议的 Webhook 地址均被拒绝；白名单内地址正常送达且失败重试有上限。
• 流程节点重试（FR-27）：节点按 retry_count/interval/backoff/timeout 重试；整流程按 on_node_failure 处置（中止/跳过/告警后继续）生效。
• 禁止绑定草稿流程（FR-28）：任务绑定流程保存时校验 status=PUBLISHED；草稿态流程被拒；流程「另存为草稿」不影响已发布版本。
• 暂停任务周期内确不触发；失败任务开启告警时 1 分钟内送达。

11. 里程碑与迭代计划