DM-ROW 接口文档

Appearance

设备部件管理 ​

**本文引用的文件** - [PartMainApi.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/PartMainApi.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) - [accessories.vue](file://app/devicemate-app/modules/equipment/accessories.vue) - [spareParts.vue（设备页）](file://app/devicemate-app/modules/equipment/spareParts.vue) - [spareParts.vue（维修任务）](file://app/devicemate-app/modules/repair/components/spareParts.vue) - [execute.vue（维修任务）](file://app/devicemate-app/modules/repair/execute.vue) - [spareParts.vue（保养任务）](file://app/devicemate-app/modules/maintain/components/spareParts.vue) - [execute.vue（保养任务）](file://app/devicemate-app/modules/maintain/execute.vue) - [apply.vue（维修申请）](file://app/devicemate-app/modules/repair/apply.vue) - [applyPart.vue（维修申请选择部件）](file://app/devicemate-app/modules/repair/applyPart.vue) - [applyPart.vue（保养申请选择部件）](file://app/devicemate-app/modules/maintain/applyPart.vue) - [repair.js（Vuex模块）](file://app/devicemate-app/store/modules/repair.js) - [StoreOutDetailVo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/store/StoreOutDetailVo.java) - [AGENTS.md](file://lemes-cloud/lemes-business-devicemate/AGENTS.md)

目录 ​

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

简介 ​

本技术文档围绕“设备部件管理”主题，系统化梳理设备部件主数据管理、设备与部件的关联关系管理、以及前后端交互的API与界面实现。重点覆盖以下方面：

  • 设备部件主数据：部件的创建、关联、查询、维护等核心能力
  • 数据模型设计：部件编码、名称、规格型号、供应商、单价、计量单位等字段
  • 关联关系管理：部件装配、拆卸、更换等操作机制
  • 完整API接口文档：RESTful设计、参数说明与响应格式
  • 实际代码示例路径：部件CRUD、设备部件关联、批量操作处理
  • 导入导出：Excel模板与数据校验建议
  • 最佳实践与性能优化

项目结构 ​

设备部件管理涉及三层：

  • 前端应用（小程序/UniApp）：负责用户交互、表单输入、调用后端API
  • 网关与业务域服务：设备域提供部件主数据与设备类型查询接口
  • 作业域（可选）：库存出库明细模型用于支撑部件生命周期与成本核算

图表来源

章节来源

核心组件 ​

  • 前端组件
    • 设备页部件列表：展示设备关联的备件与耗材
    • 维修/保养任务部件面板：支持更换、替换、变更数量等操作
    • 维修/保养申请页面：选择部件并提交申请
  • 后端接口
    • 部件主数据查询：不分页列表、按代号/编号查询
    • 设备类型查询：根据关联物料查询设备种类
  • 作业域模型
    • 库存出库明细模型：支撑部件生命周期、成本与库存跟踪

章节来源

架构总览 ​

设备部件管理采用前后端分离架构：

  • 前端通过HTTP请求调用后端提供的REST接口
  • 设备域服务提供部件主数据与设备类型查询
  • 作业域服务提供库存出库明细模型，辅助部件生命周期与成本统计

图表来源

详细组件分析 ​

设备部件主数据接口 ​

  • 接口职责
    • 不分页查询部件主数据
    • 根据部件代号/编号查询部件详情
  • 请求与响应
    • 列表查询：POST /dm-device/device/part-main/list
    • 详情查询（代号）：GET /dm-device/device/part-main/detail/one?partNo=xxx
    • 详情查询（编号）：GET /dm-device/device/part-main/detail/one/code?partCode=xxx
  • 参数与返回
    • 请求体：PartMainQueryVo（查询条件）
    • 返回体：ResultData<List<PartMainVo>>
    • 详情接口返回：ResultData<PartMainVo>

图表来源

章节来源

设备类型查询接口 ​

  • 接口职责
    • 根据关联物料查询设备种类
  • 请求与响应
    • GET /dm-device/device/device-type/getDeviceTypeByPartNo?partNo=xxx
    • 返回：ResultData<DeviceTypeVo>

图表来源

章节来源

设备页部件列表 ​

  • 功能点
    • 展示设备关联的备件与耗材
    • 支持切换“备件/耗材”两个数据源
  • 关键接口
    • POST /dm-device/device/consumable/list（传入deviceNo与dataType）

图表来源

章节来源

设备部件关联与操作（维修/保养） ​

  • 功能点
    • 更换（change）：针对已安装部件进行替换
    • 替换（replace）：从库存中取出部件进行装配
    • 变更数量：更新部件使用数量或出库数量
  • 关键接口
    • 更换/替换保存：POST /dm-device/device/parts/detail/save
    • 更新使用数量：POST /dm-device/device/parts/detail/update
    • 删除部件：POST /dm-device/device/parts/delete
  • 前端交互
    • 通过弹窗输入数量，校验库存/出库上限
    • 成功后刷新页面数据

图表来源

章节来源

设备部件关联查询（设备页） ​

  • 功能点
    • 展示设备的父设备、子设备与关联部件信息
  • 关键接口
    • 设备关联设备列表：POST /dm-device/device/eq/list
    • 设备部件列表：POST /dm-device/device/parts/list

图表来源

章节来源

维修/保养申请（部件选择与提交） ​

  • 功能点
    • 选择部件并填写使用数量、产线、仓库等信息
    • 提交申请，后端生成工单并流转
  • 关键接口
    • 申请提交：POST /dm-device/repairWorkOrders/applyFor
    • 页面初始化：GET /dm-device/device/main/detail/

图表来源

章节来源

数据模型设计 ​

  • 部件主数据（PartMainVo）
    • 字段要点：部件编码、部件名称、规格型号、计量单位、供应商、单价等
    • 用途：作为设备部件的主数据基础
  • 设备类型（DeviceTypeVo）
    • 字段要点：设备种类、设备代码、设备名称等
    • 用途：根据关联物料确定设备类型
  • 库存出库明细（StoreOutDetailVo）
    • 字段要点：出库单号、部件编号/编码、序列号、产品线、库区/储位、数量、单价、寿命、成本核算等
    • 用途：支撑部件生命周期、成本与库存跟踪

图表来源

章节来源

关联关系管理流程 ​

  • 装配：从库存取出部件并装配到设备（替换接口）
  • 拆卸：删除设备上的部件（删除接口）
  • 更换：对已安装部件进行替换（变更数量/替换保存接口）
  • 批量操作：通过申请页面批量提交多个部件的使用需求

图表来源

章节来源

API接口清单与说明 ​

  • 部件主数据
    • POST /dm-device/device/part-main/list
      • 请求体：PartMainQueryVo
      • 响应：ResultData<List<PartMainVo>>
    • GET /dm-device/device/part-main/detail/one?partNo=xxx
      • 响应：ResultData<PartMainVo>
    • GET /dm-device/device/part-main/detail/one/code?partCode=xxx
      • 响应：ResultData<PartMainVo>
  • 设备类型
    • GET /dm-device/device/device-type/getDeviceTypeByPartNo?partNo=xxx
      • 响应：ResultData<DeviceTypeVo>
  • 设备部件关联
    • POST /dm-device/device/consumable/list
      • 请求体：
      • 响应：部件列表
    • POST /dm-device/device/eq/list
      • 请求体：
      • 响应：父子设备列表
    • POST /dm-device/device/parts/list
      • 请求体：
      • 响应：部件列表
  • 维修/保养部件操作
    • POST /dm-device/device/parts/detail/save
      • 请求体：[{deviceNo, partNo, partNumber, usefulLife, serialNumber, ...}]
      • 响应：保存结果
    • POST /dm-device/device/parts/detail/update
      • 请求体：[{deviceNo, partNo, updateNumber, ...}]
      • 响应：更新结果
    • POST /dm-device/device/parts/delete
      • 请求体：[{deviceNo, partNo, partNumber, ...}]
      • 响应：删除结果
  • 申请提交
    • POST /dm-device/repairWorkOrders/applyFor
      • 请求体：[{partNo, partType, productLineNo, storeNo, useCount, workOrderNo}, ...]
      • 响应：提交结果

章节来源

Excel导入导出与模板设计 ​

  • 导入建议
    • 模板字段：部件编码、部件名称、规格型号、计量单位、单价、供应商等
    • 校验规则：必填项校验、唯一性校验（如部件编码）、数值范围校验（单价、数量）、枚举值校验（计量单位）
    • 批量写入：后端提供批量导入接口，逐条校验并回滚失败记录
  • 导出建议
    • 模板字段：设备编号、部件编码、部件名称、规格型号、序列号、装配数量、单价、出库数量、库存数量、装配时间等
    • 过滤与排序：支持按设备、部件、时间维度筛选

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

实际代码示例路径 ​

章节来源

依赖分析 ​

  • 前端模块间依赖
    • 维修/保养任务页依赖部件面板组件，面板组件依赖Vuex中的部件列表状态
    • 设备页依赖设备部件列表与设备关联设备列表接口
  • 后端服务依赖
    • 设备域服务依赖数据库存储部件主数据与设备类型
    • 作业域服务提供库存出库明细模型，支撑部件生命周期与成本统计

图表来源

章节来源

性能考虑 ​

  • 前端
    • 列表懒加载与分页：避免一次性渲染大量部件数据
    • 缓存策略：对常用部件主数据进行本地缓存，减少重复请求
    • 表单校验前置：在提交前完成数量与数值校验，降低无效请求
  • 后端
    • 接口幂等：替换/变更/删除操作需保证幂等性，避免重复装配
    • 批量写入：提供批量导入接口，提升大批量数据处理效率
    • 数据索引：为部件编码、设备编号、序列号建立索引，提升查询性能

（本节提供通用指导，不直接分析具体文件）

故障排查指南 ​

  • 常见问题
    • 数量超限：替换数量超过库存或出库数量时提示错误
    • 非整数数量：使用小数或空值时提示错误
    • 重复提交：同一部件多次提交导致重复装配
  • 建议排查步骤
    • 检查前端校验逻辑与提示信息
    • 查看后端接口返回码与日志
    • 核对数据库中部件装配记录与库存数量
  • 相关实现参考
    • 数量校验与提示：替换数量与出库数量校验
    • 申请数量校验：非空与整数校验
    • Vuex状态管理：部件列表状态清理

章节来源

结论 ​

设备部件管理通过清晰的前后端分工与标准化接口，实现了部件主数据管理、设备部件关联与操作、以及申请流程的完整闭环。结合作业域的库存出库明细模型，可进一步完善部件生命周期与成本管理。建议在后续迭代中强化导入导出能力与批量操作体验，并持续优化查询与装配性能。

附录 ​

  • 开发与运行指引
    • 聚合构建与单模块构建命令
    • 业务域边界与测试注意事项

章节来源