DM-ROW 接口文档

Appearance

设备类型管理 ​

**本文引用的文件** - [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) - [DeviceTypeController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-server/src/main/java/com/lenovo/lemes/service/dm/device/controller/DeviceTypeController.java) - [DeviceTypeService.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-server/src/main/java/com/lenovo/lemes/service/dm/device/service/DeviceTypeService.java) - [DeviceTypeServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-server/src/main/java/com/lenovo/lemes/service/dm/device/service/impl/DeviceTypeServiceImpl.java) - [DeviceTypeMapper.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-server/src/main/java/com/lenovo/lemes/service/dm/device/mapper/DeviceTypeMapper.java) - [DeviceTypeDo.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/inner/DeviceTypeDo.java) - [DeviceTypeVo.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/outer/DeviceTypeVo.java) - [DeviceTypeTreeVo.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/outer/DeviceTypeTreeVo.java) - [DeviceTypeQueryVo.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/query/DeviceTypeQueryVo.java) - [DeviceTypeImport.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/DeviceTypeImport.java) - [DeviceTypeImportVo.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/DeviceTypeImportVo.java) - [DeviceMainDo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/device/DeviceMainDo.java) - [MaintenanceStandardsDo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/device/MaintenanceStandardsDo.java) - [basicInfo.vue](file://app/devicemate-app/modules/equipment/basicInfo.vue) - [equipment.js](file://app/devicemate-app/store/modules/equipment.js)

目录 ​

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

简介 ​

本技术文档围绕“设备类型管理”功能进行系统化梳理，覆盖设备分类体系的实现机制、数据模型设计、与设备主数据的关联关系、类型选择与校验机制、完整的RESTful API接口、树形结构查询、批量操作、导入导出流程、最佳实践与性能优化建议。文档以代码为依据，结合前后端交互与作业任务侧的设备主数据模型，帮助开发者与运维人员快速理解并高效使用该能力。

项目结构 ​

设备类型管理位于“设备域（dm-device）”业务模块中，采用典型的分层架构：API接口定义、控制器、服务层、持久层与数据模型。前端通过统一网关调用后端接口，同时设备主数据在作业任务侧也有相应DO映射，用于下游统计与维护场景。

图示来源

章节来源

核心组件 ​

  • 接口定义层：对外暴露设备类型相关API，如按物料查询设备类型等。
  • 控制器层：接收请求、参数校验、调用服务层、返回统一结果封装。
  • 服务层：实现业务逻辑，包括CRUD、树形查询、导入导出、附件上传、与物料主数据同步等。
  • 持久层：MyBatis-Plus Mapper，提供分页与列表查询。
  • 数据模型：DO（数据库实体）、VO（对外传输对象、树形结构、查询条件）、Excel导入模型。
  • 前端集成：设备详情页调用后端接口，Vuex存储设备标识，支撑设备创建与关联。

章节来源

架构总览 ​

设备类型管理遵循“接口-控制器-服务-持久层”的分层设计，配合统一返回封装与Feign客户端调用，实现与文件中心、字典、物料主数据、仓库主数据等系统的解耦协作。

图示来源

详细组件分析 ​

数据模型设计 ​

  • 设备类型实体（DO）
    • 字段：设备种类代号、设备种类名称、设备分类、设备名称、设备型号、设备产地、设备厂商、说明、序列号生成规范、是否同步物料主数据等。
    • 用途：持久化存储与数据库表映射。
  • 设备类型视图（VO）
    • 字段：设备类型基础信息 + 附件/文件列表 + 仪表配置、安全提示、规格参数、备品备件/耗材列表 + 树节点扩展字段。
    • 用途：对外传输与前端渲染。
  • 树形结构（TreeVo）
    • 字段：设备分类字典 + 设备类型列表。
    • 用途：按分类聚合的树形展示。
  • 查询条件（QueryVo）
    • 字段：设备种类名称、设备分类、设备名称、设备型号、查询类型、物料编码、设备编号、部门名称、产品线集合、物料号、部门号集合等。
    • 用途：支持多维筛选与去重查询。
  • Excel导入模型
    • DeviceTypeImport：导入模板字段（设备种类、设备分类、设备型号）。
    • DeviceTypeImportVo：导入模板字段（物料编码、仓库名称等），并扩展行号与错误信息。

图示来源

章节来源

设备类型与设备主数据的关联关系 ​

  • 设备主数据（DeviceMainDo）包含设备种类代号（deviceTypeNo），用于在设备创建时与设备类型建立关联。
  • 维保标准（MaintenanceStandardsDo）包含设备分类与设备种类代号，体现设备类型在维护维度的约束。
  • 设备类型VO中包含仪表、安全提示、规格参数、备品备件/耗材等子项，这些信息在设备创建时可作为参考或默认值。

图示来源

章节来源

设备类型CRUD与树形查询 ​

  • CRUD：提供新增、更新、删除、批量删除、分页查询、列表查询、按设备类型代号查询等接口。
  • 树形查询：支持按条件获取设备类型树与纯列表树，便于前端选择器渲染。
  • 类型选择与验证：保存时对设备类型名称格式、唯一性、分类字典有效性进行校验；更新时避免重复组合；删除前进行依赖检查。

图示来源

章节来源

设备类型导入导出 ​

  • 导入接口：支持Excel导入设备类型与关联物料信息，解析后进行校验与入库。
  • 模板设计：DeviceTypeImport对应设备类型基础字段；DeviceTypeImportVo对应物料与仓库信息字段。
  • 数据验证：字段长度限制、字典映射、重复性检查、错误信息回传。
  • 导出：当前代码未提供专用导出接口，可通过分页查询+前端导出实现。

图示来源

章节来源

设备类型与设备创建时的选择与验证 ​

  • 前端设备详情页通过接口获取设备类型树与列表，供用户选择设备类型。
  • 设备主数据包含设备类型代号字段，确保设备与类型强关联。
  • 设备类型保存时对名称格式、唯一性、分类字典进行严格校验，防止脏数据进入系统。

图示来源

章节来源

依赖分析 ​

  • 控制器依赖服务接口，服务实现依赖Mapper、Feign客户端（文件中心、字典、物料主数据、仓库主数据）、Redis序列号生成器。
  • 前端通过统一网关调用控制器接口，Vuex模块管理设备标识，支撑设备详情与创建流程。
  • 作业任务侧的设备主数据与维保标准均依赖设备类型代号，形成从“类型—设备—标准”的完整链路。

图示来源

章节来源

性能考虑 ​

  • 分页查询：使用MyBatis-Plus Page与Mapper分页接口，避免一次性加载大量数据。
  • 批量操作：批量删除限制数量上限，避免超大事务导致锁竞争与延迟。
  • 缓存与序列号：通过Redis生成编号与序列号，减少数据库压力。
  • 子数据联动：保存/更新时对仪表、安全提示、规格参数、备品备件/耗材进行批量处理，注意控制单次批量大小。
  • 文件上传：上传完成后及时更新目标ID，避免悬挂文件占用存储。

故障排查指南 ​

  • 常见异常码与定位
    • 参数缺失/非法：如必填字段为空、格式不合法、字典值无效等，抛出自定义异常并返回对应错误码。
    • 重复冲突：设备类型名称+分类+型号组合重复，或名称格式不符合规则。
    • 删除依赖：删除前需检查是否存在设备/计划等依赖，否则拒绝删除。
    • 文件上传失败：检查文件中心返回码与业务键配置。
  • 排查步骤
    • 查看控制器日志与统一返回封装中的错误码。
    • 核对服务层校验逻辑与Feign调用返回状态。
    • 检查Redis序列号生成与字典缓存是否正常。
    • 对批量操作进行限流与分批处理，避免超时与锁冲突。

章节来源

结论 ​

设备类型管理以清晰的分层架构与完善的校验机制为基础，结合树形查询、批量操作与导入导出能力，满足设备主数据治理与设备创建的类型选择需求。通过与文件中心、字典、物料主数据、仓库主数据的协同，形成从类型到设备再到维护标准的完整闭环。建议在生产环境中强化批量操作的并发控制与监控告警，并持续完善导入模板与校验规则，提升数据质量与用户体验。

附录 ​

API接口清单（RESTful） ​

  • 分页查询设备类型
    • 方法：POST
    • 路径：/deviceType/page
    • 请求体：DeviceTypeQueryVo
    • 响应体：分页结果（IPage<DeviceTypeVo>）
  • 根据ID获取设备类型
    • 方法：GET
    • 路径：/deviceType/
    • 响应体：DeviceTypeVo
  • 获取设备类型列表
    • 方法：POST
    • 路径：/deviceType/findDeviceTypeList
    • 请求体：DeviceTypeQueryVo
    • 响应体：列表（List<DeviceTypeVo>）
  • 根据设备类型代号获取设备类型
    • 方法：GET
    • 路径：/deviceType/findDeviceTypeByDeviceTypeNo
    • 查询参数：deviceTypeNo
    • 响应体：DeviceTypeVo
  • 根据关联物料查询设备种类
    • 方法：GET
    • 路径：/deviceType/getDeviceTypeByPartNo
    • 查询参数：partNo
    • 响应体：DeviceTypeVo
  • 新增设备类型
    • 方法：POST
    • 路径：/deviceType/add
    • 请求体：DeviceTypeVo
    • 响应体：通用结果封装
  • 更新设备类型
    • 方法：POST
    • 路径：/deviceType/update
    • 请求体：DeviceTypeVo
    • 响应体：通用结果封装
  • 删除设备类型
    • 方法：POST
    • 路径：/deviceType/
    • 路径参数：id
    • 响应体：通用结果封装
  • 批量删除设备类型
    • 方法：POST
    • 路径：/deviceType/batchDelete
    • 请求体：Long[]
    • 响应体：通用结果封装
  • 获取可用物料主数据列表
    • 方法：GET
    • 路径：/deviceType/queryPartMainList
    • 响应体：List<PartMainVo>
  • 获取可用仓库信息列表
    • 方法：GET
    • 路径：/deviceType/queryStoreMainList
    • 响应体：List<StoreMainVo>
  • 导入设备类型Excel
    • 方法：POST
    • 路径：/deviceType/importDeviceTypeExcel
    • 请求参数：file（MultipartFile）
    • 响应体：导入结果（ImportResultInfo）
  • 上传设备图片
    • 方法：POST
    • 路径：/deviceType/upload/img
    • 请求参数：multipartFile
    • 响应体：LsscAttachmentVo
  • 上传设备附件
    • 方法：POST
    • 路径：/deviceType/upload/file
    • 请求参数：multipartFile
    • 响应体：LsscAttachmentVo
  • 删除设备图片
    • 方法：GET
    • 路径：/deviceType/del/img/
    • 路径参数：id
    • 响应体：通用结果封装
  • 删除设备附件
    • 方法：GET
    • 路径：/deviceType/del/file/
    • 路径参数：id
    • 响应体：通用结果封装
  • 上传安全提示图片
    • 方法：POST
    • 路径：/deviceType/upload/safetyTipsImg
    • 请求参数：multipartFile
    • 响应体：LsscAttachmentVo
  • 删除安全提示图片
    • 方法：GET
    • 路径：/deviceType/del/safetyTipsImg/
    • 路径参数：id
    • 响应体：通用结果封装
  • 根据条件获取设备类型树
    • 方法：POST
    • 路径：/deviceType/tree
    • 请求体：DeviceTypeQueryVo
    • 响应体：List<DeviceTypeTreeVo>
  • 获取设备类型树列表
    • 方法：POST
    • 路径：/deviceType/treeList
    • 响应体：List<DeviceTypeVo>

章节来源