DM-ROW 接口文档

Appearance

设备台账管理 ​

**本文引用的文件** - [设备主数据API接口(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) - [设备类型API接口(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) - [设备台账导入实体(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) - [设备台账导出实体(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) - [设备台账逻辑导出实体(DeviceMainLogicExcel.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/DeviceMainLogicExcel.java) - [设备表DDL(device.sql)](file://docs/ddl/device.sql) - [前端设备新增页(add.vue)](file://dm/lemes-web/src/views/devicemate/equipment/add.vue) - [前端设备基本信息组件(basicInfo.vue)](file://dm/lemes-web/src/views/devicemate/equipment/components/add/basicInfo.vue) - [前端设备管理信息组件(manageInfo.vue)](file://dm/lemes-web/src/views/devicemate/equipment/components/add/manageInfo.vue)

目录 ​

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

简介 ​

本技术文档围绕“设备台账管理”功能，系统化阐述设备主数据的CRUD能力、数据模型设计、导入导出机制、API接口规范、前端交互与后端实现映射，并给出设备生命周期管理流程、性能优化建议与最佳实践。读者可据此快速理解并扩展设备台账模块。

项目结构 ​

设备台账管理由三层组成：

  • 前端页面与组件：负责表单渲染、校验、文件上传、联动查询与提交。
  • 后端服务接口：提供设备主数据的查询、保存、导入导出等能力。
  • 数据层：基于PostgreSQL的设备相关表结构，支撑设备主数据与关联信息。

图表来源

章节来源

核心组件 ​

  • 设备主数据API：提供设备批量查询、库房序列件新增、IoT计量查询等接口。
  • 设备类型API：按关联物料查询设备种类。
  • 导入导出实体：定义Excel导入/导出字段映射与字典转换。
  • 前端设备新增页与组件：完成设备基本信息、管理信息、关联设备、资产、备件耗材、仪表读数、规格参数、文档上传等表单的收集与提交。
  • 数据层：设备主数据表及相关维度表（产品线、机型、线体、厂商等）。

章节来源

架构总览 ​

设备台账管理采用前后端分离架构：

  • 前端通过组件化表单收集设备主数据、关联信息、文档等，统一提交至后端。
  • 后端提供REST接口，进行数据校验、落库、导入导出处理。
  • 数据层通过DDL定义设备主数据与相关维度表，确保数据一致性与可扩展性。

图表来源

详细组件分析 ​

设备主数据API ​

  • 接口职责
    • 批量查询设备信息（IoT场景）
    • 库房序列件新增设备台账
    • IoT计量查询
  • 请求/响应要点
    • 使用Spring MVC注解声明REST接口
    • 统一返回ResultData封装结构
    • 参数校验使用@Validated与@NotNull

图表来源

章节来源

设备类型API ​

  • 接口职责
    • 根据关联物料(partNo)查询设备种类
  • 请求/响应要点
    • GET接口，参数校验使用@NotNull
    • 返回ResultData封装的设备类型VO

图表来源

章节来源

设备导入导出实体 ​

  • 导入实体(DeviceMainImport)
    • 字段映射Excel列，支持字典转换与行号、错误信息承载
    • 实现IExcelModel/IExcelDataModel接口，便于EasyPoi解析与校验
  • 导出实体(DeviceMainExcel/DeviceMainLogicExcel)
    • 定义导出字段与字典映射，支持日期格式化

图表来源

章节来源

前端设备新增页与组件 ​

  • 设备新增页(add.vue)
    • 组合基本信息、管理信息、关联设备、资产、备件耗材、仪表读数、规格参数、文档上传等组件
    • 收集并校验各组件表单，拼装参数后调用后端接口
  • 基本信息组件(basicInfo.vue)
    • 设备分类、设备种类、设备型号、序列号、厂商、生产日期、是否重要、是否计量、RFID、图片上传等
    • 与设备类型联动，按设备分类筛选设备种类
  • 管理信息组件(manageInfo.vue)
    • 管理部门、责任人、物理位置、产品线、线体、机型、使用状态、设备状态、启用时间、维护触发数、工位、备注等

图表来源

章节来源

设备数据模型设计 ​

  • 设备主数据表(device.sql中相关表)
    • 设备基本信息：设备编码、名称、序列号、分类、是否重要、是否计量、RFID、生产日期、厂商、型号、规格、产地、图片等
    • 管理信息：管理部门、责任人、使用状态、设备状态、启用时间、维护触发数、工位、备注、产品线、线体、机型等
    • 位置信息：物理位置描述、库区/库位等（通过关联表体现）
    • 状态管理：使用状态、设备状态等字典值
  • 关联维度表
    • 产品线、机型、线体、厂商等维度表，支撑设备的归属与配置

图表来源

章节来源

设备生命周期管理流程 ​

  • 创建：填写设备基本信息与管理信息，完成新增提交
  • 启用：设置启用时间、使用状态为“在用”
  • 运行：日常巡检、维护、计量读数更新
  • 停用/报废：变更使用状态/设备状态，完成处置流程
  • 报废：通过相关单据流程，标记设备状态为“报废”

[本图为概念流程示意，不直接对应具体源码文件]

依赖关系分析 ​

  • 前端组件依赖
    • add.vue依赖basicInfo.vue、manageInfo.vue以及各类API调用
    • basicInfo.vue依赖设备类型、厂商、字典等数据源
    • manageInfo.vue依赖部门树、用户列表、产品线/线体/机型等数据源
  • 后端接口依赖
    • DeviceMainApi依赖导入/导出实体进行Excel处理
    • DeviceTypeApi依赖设备类型查询能力
    • 数据访问依赖DDL定义的设备相关表

图表来源

章节来源

性能考虑 ​

  • 前端
    • 表单分步校验，避免全量提交失败导致的重渲染
    • 图片上传采用分片/压缩策略，减少带宽占用
    • 下拉选项懒加载与本地缓存，降低请求频次
  • 后端
    • 导入批处理：分批读取Excel，逐条校验并批量写入，结合事务控制
    • 查询接口：对高频字段建立索引，合理使用分页与过滤条件
    • 缓存：字典值、厂商、产品线等静态数据缓存，降低数据库压力
  • 数据层
    • 对常用查询字段建立索引，如设备编码、序列号、部门、产品线等
    • 关联表使用外键约束，保证数据一致性

[本节为通用性能建议，不直接分析具体源码文件]

故障排查指南 ​

  • 前端
    • 表单校验失败：检查各组件的rules配置与字段必填提示
    • 图片上传失败：确认文件类型与大小限制，检查上传接口返回
    • 下拉数据为空：确认字典、厂商、部门、产品线等接口是否正确调用
  • 后端
    • 导入失败：检查导入实体字段映射与字典转换，查看行号与错误信息
    • 接口返回异常：检查参数校验、事务回滚与异常捕获
  • 数据层
    • 字段缺失或类型不匹配：核对DDL与导入/导出实体字段定义
    • 关联数据异常：检查外键约束与关联表数据

章节来源

结论 ​

设备台账管理通过清晰的前后端分工、完善的导入导出机制与稳健的数据模型，实现了设备主数据的全生命周期管理。依托REST接口与组件化前端，系统具备良好的可扩展性与可维护性。建议在后续迭代中持续完善导入校验规则、优化查询性能与增强异常处理能力。

附录 ​

API接口规范与示例路径 ​

章节来源

导入导出字段映射与校验 ​

  • 导入字段映射
    • 设备编码、设备名称、资产编号、序列号、设备类型名称、设备分类、是否重要、是否计量、设备状态、使用状态、责任人、厂商、型号、部门、产品线、位置描述、工位、线体、机型、生产日期、产地、启用时间等
    • 字段映射与字典转换参考：设备台账导入实体(DeviceMainImport.java):43-120
  • 导出字段映射
  • 校验规则
    • 必填字段：设备类型名称、设备分类、设备型号、部门、产品线等
    • 字典值：使用状态、设备状态、是否重要、是否计量等
    • 日期格式：生产日期、启用时间等
    • 行号与错误信息：通过IExcelDataModel承载，便于定位问题行

章节来源

设备CRUD操作与批量导入导出流程 ​

  • CRUD操作
    • 新增：前端收集表单数据，调用库房序列件新增接口，后端落库并返回结果
    • 查询：批量查询接口支持IoT场景下的设备信息检索
    • 更新：通过管理信息组件更新使用状态、设备状态、启用时间等
    • 删除：通过逻辑删除标识与状态变更实现
  • 批量导入导出
    • 导入：前端Excel上传，后端解析并校验，逐条写入，错误行通过行号与错误信息反馈
    • 导出：按需导出全部字段或运营关注字段，支持日期格式化与字典转换

图表来源