DM-ROW 接口文档

Appearance

定时任务系统 ​

**本文引用的文件** - [DeviceMateSimpleJob.java](file://lemes-job-devicemate/lemes-job-devicemate-common/src/main/java/com/lenovo/lemes/job/devicemate/common/config/DeviceMateSimpleJob.java) - [DeviceMateMultipleFactoryJob.java](file://lemes-job-devicemate/lemes-job-devicemate-common/src/main/java/com/lenovo/lemes/job/devicemate/common/config/DeviceMateMultipleFactoryJob.java) - [HjSpCreatWotJob.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/handler/HjSpCreatWotJob.java) - [HjSpDelayRemindJob.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/handler/HjSpDelayRemindJob.java) - [JobService.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/service/JobService.java) - [application.yml](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/resources/application.yml) - [bootstrap.yml](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/resources/bootstrap.yml) - [LemesJobDeviceMateServerApplication.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/LemesJobDeviceMateServerApplication.java) - [DeviceEnum.java](file://lemes-job-devicemate/lemes-job-devicemate-common/src/main/java/com/lenovo/lemes/job/devicemate/common/enums/DeviceEnum.java) - [JobConstant.java](file://lemes-job-devicemate/lemes-job-devicemate-common/src/main/java/com/lenovo/lemes/job/devicemate/common/constant/JobConstant.java) - [LenovoLogUtil.java](file://lemes-job-devicemate/lemes-job-devicemate-common/src/main/java/com/lenovo/lemes/job/devicemate/common/util/compliance/LenovoLogUtil.java) - [JobStatus.java](file://lemes-job-devicemate/lemes-job-devicemate-common/src/main/java/com/lenovo/lemes/job/devicemate/common/util/compliance/JobStatus.java)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论
  10. 附录

简介 ​

本技术文档面向DeviceMate定时任务系统，围绕基于ElasticJob（ShardingSphere子项目）的任务调度机制，系统性阐述任务定义、执行策略、配置管理、监控告警与重试机制，并结合设备维护场景（维保计划生成、工单自动创建、超期提醒）给出实现细节、开发指南、性能优化建议与运维排障方法。文档同时提供任务日志分析、执行统计与系统集成方案，帮助运维工程师与系统管理员高效落地与维护。

项目结构 ​

定时任务系统由“公共基础”和“执行器”两部分组成：

  • 公共基础层：提供统一的作业基类、枚举、常量、合规日志等通用能力，供各执行器共享。
  • 执行器层：承载具体业务作业（如环境点检计划生成工单、环境点检工单超期提醒），并负责与业务服务交互。

图表来源

章节来源

核心组件 ​

  • 作业基类体系
    • 无工厂场景：DeviceMateSimpleJob，统一注入traceId、记录任务开始/结束日志。
    • 多工厂场景：DeviceMateMultipleFactoryJob，在基类基础上遍历工厂并设置ThreadContext中的工厂标识，便于跨工厂隔离与审计。
  • 业务作业
    • 环境点检计划生成工单：HjSpCreatWotJob，按计划生成方式（固定周期、上次结束立即生成、首次执行）推进任务与工单创建，并支持邮件通知。
    • 环境点检工单超期提醒：HjSpDelayRemindJob，根据计划到期时间与宽限参数，对未完成且未提醒的工单发送超期提醒邮件。
  • 时间计算与规则
    • JobService接口定义时间推进与判断逻辑，具体实现由业务方提供或复用通用逻辑。
  • 配置与运行
    • application.yml：端口、Tomcat线程池、Kafka、数据源、Redis、MyBatis、ElasticJob注册中心等。
    • bootstrap.yml：Nacos注册与配置中心接入。
    • 应用入口：LemesJobDeviceMateServerApplication。
  • 合规与监控
    • LenovoLogUtil：输出标准格式的定时任务执行日志，包含开始、成功、失败状态与错误信息。
    • JobStatus：任务状态枚举，配合LenovoLogUtil记录。

章节来源

架构总览 ​

系统采用“公共基础 + 执行器”的分层架构，通过ElasticJob进行分布式调度，作业在多工厂维度逐个执行，利用合规日志工具记录任务生命周期，结合Kafka/Redis/数据库等外部组件完成数据流转与持久化。

图表来源

详细组件分析 ​

作业基类与工厂维度执行 ​

  • DeviceMateSimpleJob：为每个作业注入traceId，记录开始/结束日志，屏蔽Sharding上下文差异。
  • DeviceMateMultipleFactoryJob：拉取有效工厂列表，循环执行，将工厂编号写入ThreadContext，确保后续日志与审计可按工厂区分。

图表来源

章节来源

环境点检计划生成工单（HjSpCreatWotJob） ​

  • 功能要点
    • 按计划生成方式分类处理：固定周期、上次结束立即生成、首次执行。
    • 首次执行校验与任务/工单创建，后续周期按上次生成/结束时间推导下次生成时间，并支持提前生成窗口。
    • 创建完成后复制附件与标准文件，必要时发送邮件通知。
  • 关键流程（固定周期）

图表来源

章节来源

环境点检工单超期提醒（HjSpDelayRemindJob） ​

  • 功能要点
    • 查询未完成且未提醒的环境点检工单，按计划开始时间与宽限参数计算超期阈值。
    • 根据业务类型选择不同邮件模板，向责任人发送超期提醒邮件，并更新提醒状态。
  • 关键流程

图表来源

章节来源

任务执行序列（示例：HjSpCreatWotJob） ​

图表来源

依赖分析 ​

  • 内部依赖
    • HjSpCreatWotJob 与 HjSpDelayRemindJob 均继承自 DeviceMateMultipleFactoryJob，统一工厂维度执行与日志规范。
    • 业务服务通过Service接口与领域服务交互，职责清晰。
  • 外部依赖
    • ElasticJob 注册中心（Zookeeper）、运行配置（application.yml）。
    • Nacos 注册与配置中心（bootstrap.yml）。
    • 数据库（Druid+DynamicDatasource）、Redis、Kafka。
  • 日志与合规
    • LenovoLogUtil 输出统一格式的定时任务执行日志，包含开始/成功/失败状态与错误信息，便于集中采集与分析。

图表来源

章节来源

性能考虑 ​

  • 并发与分片
    • 通过ElasticJob的分片策略将任务分布到多个执行器节点，避免单点瓶颈；工厂维度遍历天然具备天然分区特性。
  • 数据访问
    • 使用动态数据源与Druid连接池，合理配置初始/最大连接数、空闲检测与超时参数，降低连接抖动。
  • 线程与IO
    • Tomcat线程池参数适当放大，满足高并发请求；Kafka生产者启用压缩与重试，平衡吞吐与可靠性。
  • 日志与审计
    • 统一使用LenovoLogUtil输出结构化日志，减少解析成本；避免在高频路径打印大对象。
  • 任务时间计算
    • JobService的时间推进逻辑尽量避免复杂计算，必要时缓存关键中间结果，减少重复计算。

故障排除指南 ​

  • 任务未执行/未触发
    • 检查ElasticJob注册中心（Zookeeper）连通性与命名空间配置。
    • 核对application.yml中jobs配置与作业类路径是否正确。
  • 工厂维度执行异常
    • 查看多工厂基类日志，确认工厂列表与ThreadContext中的工厂编号是否正确。
  • 超期提醒未发送
    • 核对超期阈值计算逻辑与业务类型模板映射；检查收件人邮箱与邮件服务配置。
  • 数据库/连接池问题
    • 关注Druid监控页面与慢查询日志；调整连接池参数与超时策略。
  • 合规日志缺失
    • 确认LenovoLogUtil所需CMDB配置已注入；检查日志输出级别与采集链路。

章节来源

结论 ​

DeviceMate定时任务系统以ElasticJob为核心，结合多工厂维度执行与统一合规日志，实现了设备维护场景下的自动化与可观测性。通过明确的作业基类、清晰的服务边界与完善的配置体系，系统具备良好的扩展性与稳定性。建议在生产环境中持续完善监控告警、日志分析与性能压测，确保任务在高负载下的可靠运行。

附录 ​

  • 任务开发指南
    • 新增作业：继承DeviceMateMultipleFactoryJob或DeviceMateSimpleJob，覆盖对应抽象方法。
    • 时间规则：实现JobService接口或复用通用逻辑，确保周期推进与提前生成窗口准确。
    • 合规日志：在关键节点调用LenovoLogUtil记录任务状态与错误信息。
    • 配置管理：在application.yml中新增作业配置，确保分片总数与参数正确。
  • 任务日志分析
    • 使用LenovoLogUtil输出的结构化JSON进行聚合分析，关注状态字段与耗时指标。
  • 系统集成方案
    • 与Nacos集成实现配置热更新；与Zookeeper集成实现分布式调度；与Kafka/Redis/数据库集成实现数据流转与存储。