DM-ROW 接口文档

Appearance

设备管理服务 ​

**本文引用的文件** - [README.md](file://lemes-cloud/lemes-business-devicemate/README.md) - [AGENTS.md](file://lemes-cloud/lemes-business-devicemate/AGENTS.md) - [DeviceMainApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-common/src/main/java/com/lenovo/lemes/service/dm/device/api/DeviceMainApi.java) - [DeviceTypeApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-common/src/main/java/com/lenovo/lemes/service/dm/device/api/DeviceTypeApi.java) - [DeviceMainApi.java（公共客户端）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/api/DeviceMainApi.java) - [DeviceMainExcel.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-common/src/main/java/com/lenovo/lemes/service/dm/device/client/entity/excel/DeviceMainExcel.java) - [DeviceMainImport.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-common/src/main/java/com/lenovo/lemes/service/dm/device/client/entity/excel/DeviceMainImport.java) - [device.sql](file://docs/ddl/device.sql) - [MaintenanceWorkOrdersServiceImpl.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/service/device/impl/MaintenanceWorkOrdersServiceImpl.java) - [MaintenanceWorkOrdersService.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/service/device/MaintenanceWorkOrdersService.java) - [MaintenanceWorkOrdersDo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/device/MaintenanceWorkOrdersDo.java) - [LpCreatWotJob.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/handler/LpCreatWotJob.java) - [SpCreatWotJob.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/handler/SpCreatWotJob.java) - [inspectTasks.vue](file://app/devicemate-app/modules/inspectTasks/inspectTasks.vue)

目录 ​

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

引言 ​

本文件面向设备管理服务（DeviceMate）的技术文档，聚焦于设备台账管理、设备类型管理、设备部件管理、设备生命周期管理、维护计划与工单、点检/巡检管理、API 接口设计、数据模型与数据库表结构、以及前端交互与作业调度联动。文档以仓库中的真实代码与DDL为依据，提供可追溯的“章节来源”和“图表来源”，帮助读者快速理解系统设计与实现。

项目结构 ​

DeviceMate 采用多模块聚合工程，按领域拆分为 dm-common、dm-device、dm-store、dm-workflow 四个业务服务，每个服务包含公共模块与服务端模块。设备域主要集中在 dm-device 与 dm-common 的公共接口中，并通过作业调度模块（lemes-job-devicemate）驱动维护计划与工单生成。

图表来源

章节来源

核心组件 ​

  • 设备台账接口：提供设备批量查询、库房序列件新增、IoT计量台账查询等能力。
  • 设备类型接口：根据关联物料查询设备种类。
  • 设备导入导出：提供Excel导入/导出示例，包含字段映射与校验。
  • 工单与计划：通过作业调度生成维护/点检/巡检工单，支持超期提醒与状态更新。
  • 前端交互：点检任务页面与设备API对接，支持分页、筛选与跳转。

章节来源

架构总览 ​

设备域由“接口层（API）—服务层（Service）—数据层（DO/Excel/DDL）—前端（App）—作业调度（Job）”构成，形成闭环的设备生命周期管理与工单驱动体系。

图表来源

详细组件分析 ​

设备台账管理（主数据） ​

  • 接口职责
    • 批量查询设备信息（用于IoT场景）
    • 库房序列件新增设备台账
    • IoT计量台账查询
  • 数据模型与导入导出
    • 导出模型：包含设备编码、名称、资产号、序列号、类型、分类、重要性、计量标志、状态、使用状态、责任人、制造商、型号、部门、产线、位置、工位、产线/机型、生产日期等字段。
    • 导入模型：包含设备编码、名称、资产号、类型名称、分类、是否重要、是否计量、设备状态、使用状态、责任人、制造商、机型、部门、产线、位置、工位、产线/机型、生产日期、来源、激活时间等字段，并实现 EasyPoi 的 IExcelModel/IExcelDataModel 接口以支持校验与错误收集。
  • 生命周期要点
    • 设备创建：导入/新增后进入“启用前”或“启用”状态，绑定部门、产线、工位、计量属性等。
    • 设备启用：激活时间生效，参与点检/巡检/维修计划。
    • 设备停用/报废：通过流程或作业调度触发状态变更与清理。

图表来源

章节来源

设备类型管理 ​

  • 接口职责：根据关联物料（partNo）查询设备种类，支撑设备主数据与计划/工单的分类与派发。
  • 使用场景：导入/新增设备时，通过物料反查设备类型，确保类型一致性与后续计划/工单的正确性。

章节来源

设备部件管理（物料/备件） ​

  • 关联关系：设备与物料（备件）存在强关联，设备主数据中包含制造商、型号、计量属性等，备件主数据（part_main）提供物料编码、规格、控制类型、价格、有效期、寿命等属性。
  • 作用：为设备维护计划、维修工单、库存管理提供基础数据支撑。

章节来源

设备生命周期管理流程 ​

  • 创建：导入/新增设备，设置基础属性（类型、分类、计量、状态、使用状态、责任人、部门、产线、工位、位置、机型、生产日期等）。
  • 启用：设置激活时间，设备进入可运行状态，纳入点检/巡检/维修计划。
  • 运行：设备参与各类计划与工单，记录运行状态与指标。
  • 停用/报废：通过流程或作业调度触发状态变更，清理关联任务与库存。

（此图为概念流程，不对应具体源码文件）

维护计划与工单流程 ​

  • 计划生成：作业调度根据计划（如点检/巡检）生成任务与工单，支持首次执行时间、周期策略与设备列表。
  • 工单创建：为每个设备生成对应工单，设置负责人、产线、提醒/预警字段等。
  • 状态更新：支持超期提醒状态更新与历史记录。

图表来源

章节来源

点检/巡检管理（前端交互） ​

  • 页面职责：支持分页加载、筛选、字典项加载、跳转到详情/执行页面。
  • 与后端交互：通过 POST 请求调用设备服务接口，加载点检任务列表。

章节来源

依赖分析 ​

  • 设备API依赖公共客户端接口，实现跨服务调用与降级容错。
  • 作业调度依赖工单服务接口与实现，通过数据源切换与事务注解保障一致性。
  • 前端依赖设备API，实现点检任务的查询与跳转。

图表来源

性能考虑 ​

  • 分页与缓存：前端分页加载，后端接口支持分页参数；可结合Redis缓存热点字典与常用查询结果。
  • 批量导入：导入模型实现 IExcelDataModel/IExcelModel，便于批量校验与错误收集，减少单条写入开销。
  • 作业调度：按计划周期生成工单，避免实时高频写入；对超期工单进行定时提醒，降低人工干预成本。
  • 数据库索引：DDL中包含多处索引定义，建议结合查询模式持续优化索引策略。

（本节为通用建议，不直接分析具体文件）

故障排查指南 ​

  • 设备导入失败：检查导入模型字段映射与校验提示，定位行号与错误信息。
  • 工单未生成：确认计划是否到达首次执行时间、设备列表是否为空、作业调度是否正常运行。
  • 状态异常：核对工单DO中的超期/提醒字段是否正确更新，检查作业调度日志。

章节来源

结论 ​

设备管理服务围绕“设备主数据—设备类型—设备部件—维护计划—工单—点检/巡检—前端交互—作业调度”的全链路展开，通过清晰的接口与数据模型、完善的导入导出与校验机制、以及基于计划的自动化工单生成，实现了设备生命周期的闭环管理。建议在生产环境中进一步完善监控、缓存与索引策略，持续优化导入/导出与工单生成的性能与稳定性。

附录 ​

API 接口文档（RESTful 设计要点） ​

  • 设备批量查询（IoT）
    • 方法：POST
    • 路径：/dm-device/deviceMain/query/list
    • 请求体：设备编码数组
    • 返回：设备信息列表
  • 库房序列件新增设备台账
    • 方法：POST
    • 路径：/dm-device/deviceMain/store/add
    • 请求体：设备台账（库房序列件）列表
    • 返回：操作结果
  • IoT计量台账查询
    • 方法：POST
    • 路径：/dm-device/deviceMain/for/iot/list
    • 请求体：查询参数Map
    • 返回：计量台账列表
  • 根据物料查询设备类型
    • 方法：GET
    • 路径：/dm-device/deviceType/getDeviceTypeByPartNo
    • 参数：partNo（非空）
    • 返回：设备类型信息

章节来源

数据模型与数据库表结构 ​

  • 设备主数据（设备台账）
    • 关键字段：设备编码、名称、资产号、序列号、类型、分类、重要性、计量标志、状态、使用状态、责任人、制造商、型号、部门、产线、位置、工位、机型、生产日期等。
    • 对应DDL：device.sql 中的设备相关表定义。
  • 物料主数据（备件）
    • 关键字段：物料编码、名称、规格、单位、控制类型、价格、有效期、寿命、使用机型、ABC分类等。
    • 对应DDL：device.sql 中的 part_main 表定义。

章节来源