设备管理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) - [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) - [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) - [DeviceMainController.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/DeviceMainController.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) - [DeviceMainService.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/DeviceMainService.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) - [DeviceMainVo.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/DeviceMainVo.java)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能与扩展性
8. 故障排查指南
9. 结论
10. 附录：接口清单与示例

简介

本文件面向前端开发者与第三方系统集成方，提供设备管理相关API的权威接口文档。覆盖设备主数据管理（DeviceMainApi）、设备类型管理（DeviceTypeApi）、设备配件管理（PartMainApi）等核心能力，包括：

• 基础CRUD：创建、查询、更新、删除
• 高级能力：批量查询、导入导出、图片/附件上传、设备编号生成、打印指令拼装
• 设备分类与状态：设备类型树、设备类型与物料关联查询
• 参数校验与业务约束：基于注解的参数校验、业务规则说明

项目结构

设备管理API位于“设备业务服务”模块中，采用“接口定义 + 控制器 + 服务层”的分层架构：

• 接口层：在公共模块定义对外API契约（DeviceMainApi、DeviceTypeApi、PartMainApi）
• 控制器层：在设备服务模块实现具体HTTP接口（DeviceMainController、DeviceTypeController）
• 服务层：抽象业务逻辑（DeviceMainService、DeviceTypeService）

图表来源

• DeviceMainApi.java:20-45
• DeviceTypeApi.java:16-22
• PartMainApi.java:20-44
• DeviceMainController.java:35-218
• DeviceTypeController.java:34-199

章节来源

• DeviceMainApi.java:1-46
• DeviceTypeApi.java:1-23
• PartMainApi.java:1-45
• DeviceMainController.java:1-219
• DeviceTypeController.java:1-200

核心组件

• 设备主数据API（DeviceMainApi）：提供设备台账的查询、保存、导入导出、图片/附件上传、批量查询、打印指令拼装等能力。
• 设备类型API（DeviceTypeApi）：提供设备类型的分页查询、详情查询、新增/更新/删除、树形结构查询、与物料关联查询等能力。
• 物料主数据API（PartMainApi）：提供物料主数据的查询、按代号/编号查询详情等能力。

章节来源

• DeviceMainApi.java:15-45
• DeviceTypeApi.java:11-22
• PartMainApi.java:15-44

架构总览

下图展示从客户端到控制器、再到服务层的调用链路与职责分工：

图表来源

• DeviceMainController.java:44-86
• DeviceTypeController.java:42-94
• DeviceMainService.java:36-72
• DeviceTypeService.java:24-52

详细组件分析

设备主数据API（DeviceMainApi）

• 职责：定义设备台账相关对外接口，包括不分页查询、分页查询、详情查询、保存、删除、导入导出、图片/附件上传、批量查询、打印指令拼装等。

• 关键接口：

  • 不分页查询：POST /device/main/list
  • 分页查询：POST /device/main/page
  • 详情查询：GET /device/main/detail/
  • 保存详情：POST /device/main/detail/save
  • 更新详情：POST /device/main/detail/update
  • 删除：POST /device/main/del
  • 导入导出：POST /device/main/import、POST /device/main/export
  • 图片/附件上传：POST /device/main/upload/img、POST /device/main/upload/file
  • IOT批量查询：POST /device/main/api/query/list
  • 库房序列件新增：POST /device/main/store/add
  • 打印指令拼装：POST /device/main/printDeviceInfo

• 参数与响应要点：

  • 查询类接口使用请求体或路径变量传递参数；部分接口支持分页参数（pageNum、pageSize）。
  • 保存/更新接口接收设备详情VO，返回成功状态。
  • 删除接口接收ID数组。
  • 导入导出接口接收文件，返回导入结果信息。
  • 图片/附件上传接口接收multipart文件，返回附件信息。
  • IOT批量查询接收设备编码列表，返回设备信息列表。
  • 库房序列件新增接收设备台账列表，返回成功状态。
  • 打印指令拼装接收设备编码列表，返回拼装后的打印指令字符串。

• 参数校验与业务规则：

  • 控制器层通过注解进行参数校验（如@Validated），确保请求体与路径参数符合要求。
  • 设备主数据VO包含图片数量限制等字段约束。

• 错误码约定：

  • 统一使用ResultData包装响应，错误时返回错误码与消息；具体错误码由服务层抛出并在网关/统一异常处理中转换。

章节来源

• DeviceMainApi.java:23-45
• DeviceMainController.java:44-216
• DeviceMainService.java:36-165
• DeviceMainVo.java:10-26

设备类型API（DeviceTypeApi）

• 职责：提供设备类型的CRUD、树形结构查询、与物料主数据的关联查询等能力。

• 关键接口：

  • 分页查询：POST /deviceType/page
  • 列表查询：POST /deviceType/findDeviceTypeList
  • 详情查询：GET /deviceType/
  • 新增：POST /deviceType/add
  • 更新：POST /deviceType/update
  • 删除：POST /deviceType/
  • 批量删除：POST /deviceType/batchDelete
  • 树形查询：POST /deviceType/tree、POST /deviceType/treeList
  • 与物料关联查询：GET /deviceType/getDeviceTypeByPartNo
  • 可用物料列表：GET /deviceType/queryPartMainList
  • 可用仓库列表：GET /deviceType/queryStoreMainList
  • 图片/附件上传与删除：多组上传/删除接口
  • 导入：POST /deviceType/importExcel、POST /deviceType/importDeviceTypeExcel

• 参数与响应要点：

  • 分页查询接收查询条件VO，返回分页结果。
  • 新增/更新接收设备类型VO，返回成功状态。
  • 树形查询返回树形结构或平铺列表。
  • 与物料关联查询接收物料代号，返回设备类型信息。
  • 可用物料/仓库列表返回可选列表。

• 参数校验与业务规则：

  • 控制器层对必填参数进行校验（如@NotNull）。
  • 服务层负责业务逻辑编排与数据一致性。

章节来源

• DeviceTypeApi.java:19-22
• DeviceTypeController.java:42-198
• DeviceTypeService.java:24-151

物料主数据API（PartMainApi）

• 职责：提供物料主数据的查询与详情查询能力。

• 关键接口：

  • 列表查询（不分页）：POST /device/part/main/list
  • 详情查询（按代号）：GET /device/part/main/detail/one
  • 详情查询（按编号）：GET /device/part/main/detail/one/code

• 参数与响应要点：

  • 列表查询接收查询条件VO，返回物料主数据列表。
  • 详情查询接收物料代号或编号，返回单条物料信息。

• 参数校验与业务规则：

  • 控制器层对查询参数进行校验，保证查询条件有效。

章节来源

• PartMainApi.java:23-44

依赖关系分析

• 控制器依赖服务接口：控制器通过@Autowired注入服务实现，调用服务方法完成业务处理。
• 服务接口继承通用分页接口：服务接口继承IService，便于复用MyBatis-Plus的分页与CRUD能力。
• VO/DO映射：控制器与服务层之间以VO/DTO作为数据传输载体，避免直接暴露DO。

图表来源

• DeviceMainController.java:41-41
• DeviceTypeController.java:39-40
• DeviceMainService.java:27-27
• DeviceTypeService.java:17-17

性能与扩展性

• 分页查询：建议在大数据量场景使用分页接口，避免一次性加载过多数据。
• 批量操作：批量导入/导出、批量删除等接口适合批量处理，注意控制批次大小与超时时间。
• 文件上传：图片/附件上传建议限制文件大小与格式，并结合异步处理与进度反馈。
• 缓存策略：对只读查询（如设备类型树、物料列表）可考虑缓存热点数据，降低数据库压力。
• 幂等性：对于写操作建议引入幂等令牌或去重机制，防止重复提交导致的数据不一致。

故障排查指南

• 参数校验失败：检查请求体/路径参数是否满足@NotNull、@Validated等注解约束。
• 文件上传失败：确认Content-Type为multipart/form-data，文件大小与类型符合限制。
• 导入失败：核对Excel模板字段与顺序，查看导入结果中的错误明细。
• 权限问题：确认用户具备相应角色权限，避免因鉴权失败导致的403/401。
• 服务不可用：检查服务健康状态与日志，定位异常堆栈与数据库连接情况。

结论

本文档梳理了设备主数据、设备类型与物料主数据的核心API，明确了HTTP方法、URL路径、请求参数、响应格式与常见错误处理方式。建议在集成时优先使用分页与列表查询接口，配合参数校验与文件上传规范，确保系统的稳定性与可维护性。

附录：接口清单与示例

设备主数据接口

• 不分页查询

  • 方法：POST
  • 路径：/device/main/list
  • 请求体：设备查询条件VO
  • 响应：ResultData<List<DeviceMainVo>>

• 分页查询

  • 方法：POST
  • 路径：/device/main/page
  • 请求体：设备查询条件VO（含分页参数）
  • 响应：ResultData<IPage<DeviceMainVo>>

• 详情查询

  • 方法：GET
  • 路径：/device/main/detail/
  • 路径参数：deviceNo
  • 响应：ResultData<MainDetailVo>

• 保存详情

  • 方法：POST
  • 路径：/device/main/detail/save
  • 请求体：MainDetailVo
  • 响应：ResultData<MainDetailVo>

• 更新详情

  • 方法：POST
  • 路径：/device/main/detail/update
  • 请求体：MainDetailVo
  • 响应：ResultData<MainDetailVo>

• 删除

  • 方法：POST
  • 路径：/device/main/del
  • 请求体：Long[] ids
  • 响应：ResultData

• 导入

  • 方法：POST
  • 路径：/device/main/import
  • 表单参数：file(MultipartFile)
  • 响应：ResultData<ImportResultInfo>

• 导出

  • 方法：POST
  • 路径：/device/main/export
  • 请求体：设备查询条件VO
  • 响应：void（下载文件流）

• 图片上传

  • 方法：POST
  • 路径：/device/main/upload/img
  • 表单参数：multipartFile(MultipartFile)
  • 响应：ResultData<LsscAttachmentVo>

• 附件上传

  • 方法：POST
  • 路径：/device/main/upload/file
  • 表单参数：multipartFile(MultipartFile)
  • 响应：ResultData<LsscAttachmentVo>

• IOT批量查询

  • 方法：POST
  • 路径：/device/main/api/query/list
  • 请求体：List<String> deviceCodeList
  • 响应：ResultData<List<DeviceInfo>>

• 库房序列件新增

  • 方法：POST
  • 路径：/device/main/store/add
  • 请求体：List<DeviceMainForStoreVo>
  • 响应：ResultData

• 打印指令拼装

  • 方法：POST
  • 路径：/device/main/printDeviceInfo
  • 请求体：List<String> deviceCodeList
  • 响应：ResultData<String>

章节来源

• DeviceMainController.java:44-216
• DeviceMainService.java:36-165

设备类型接口

• 分页查询

  • 方法：POST
  • 路径：/deviceType/page
  • 请求体：DeviceTypeQueryVo
  • 响应：ResultData<IPage<DeviceTypeVo>>

• 列表查询

  • 方法：POST
  • 路径：/deviceType/findDeviceTypeList
  • 请求体：DeviceTypeQueryVo
  • 响应：ResultData<List<DeviceTypeVo>>

• 详情查询

  • 方法：GET
  • 路径：/deviceType/
  • 路径参数：id
  • 响应：ResultData<DeviceTypeVo>

• 新增

  • 方法：POST
  • 路径：/deviceType/add
  • 请求体：DeviceTypeVo
  • 响应：ResultData

• 更新

  • 方法：POST
  • 路径：/deviceType/update
  • 请求体：DeviceTypeVo
  • 响应：ResultData

• 删除

  • 方法：POST
  • 路径：/deviceType/
  • 路径参数：id
  • 响应：ResultData

• 批量删除

  • 方法：POST
  • 路径：/deviceType/batchDelete
  • 请求体：Long[] ids
  • 响应：ResultData

• 树形查询

  • 方法：POST
  • 路径：/deviceType/tree
  • 请求体：DeviceTypeQueryVo
  • 响应：ResultData<List<DeviceTypeTreeVo>>

• 树形列表

  • 方法：POST
  • 路径：/deviceType/treeList
  • 请求体：无
  • 响应：ResultData<List<DeviceTypeVo>>

• 与物料关联查询

  • 方法：GET
  • 路径：/deviceType/getDeviceTypeByPartNo
  • 查询参数：partNo(String, 必填)
  • 响应：ResultData<DeviceTypeVo>

• 可用物料列表

  • 方法：GET
  • 路径：/deviceType/queryPartMainList
  • 请求体：无
  • 响应：ResultData<List<PartMainVo>>

• 可用仓库列表

  • 方法：GET
  • 路径：/deviceType/queryStoreMainList
  • 请求体：无
  • 响应：ResultData<List<StoreMainVo>>

• 图片/附件上传与删除

  • 方法：POST/GET
  • 路径：/deviceType/upload/img、/deviceType/upload/file、/deviceType/upload/safetyTipsImg
  • 路径：/deviceType/del/img/{id}、/deviceType/del/file/{id}、/deviceType/del/safetyTipsImg/
  • 响应：ResultData<LsscAttachmentVo>/ResultData

• 导入

  • 方法：POST
  • 路径：/deviceType/importExcel、/deviceType/importDeviceTypeExcel
  • 表单参数：file(MultipartFile)
  • 响应：ResultData<ImportResultInfo>

章节来源

• DeviceTypeController.java:42-198
• DeviceTypeService.java:24-151

物料主数据接口

• 列表查询（不分页）

  • 方法：POST
  • 路径：/device/part/main/list
  • 请求体：PartMainQueryVo
  • 响应：ResultData<List<PartMainVo>>

• 详情查询（按代号）

  • 方法：GET
  • 路径：/device/part/main/detail/one
  • 查询参数：partNo(String, 必填)
  • 响应：ResultData<PartMainVo>

• 详情查询（按编号）

  • 方法：GET
  • 路径：/device/part/main/detail/one/code
  • 查询参数：partCode(String, 必填)
  • 响应：ResultData<PartMainVo>

章节来源

• PartMainApi.java:23-44