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) - [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) - [SysUserApi.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/SysUserApi.java) - [StockMainApi.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/StockMainApi.java)目录
简介
本文件为 DeviceMate 项目的完整 API 接口文档，面向前端开发者与第三方集成商，系统性梳理并规范 RESTful API 的 HTTP 方法、URL 模式、请求参数、响应格式与错误码解释。当前已覆盖以下核心领域：
- 设备管理 API：设备台账、计量台账、库房序列件新增
- 仓储管理 API：库存相关接口（以 StockMainApi 为准）
- 用户管理 API：用户查询、权限标识查询
为确保准确性，本文所有接口定义均基于后端 Java 接口契约进行抽象化描述，并提供典型请求/响应场景说明。
项目结构
DeviceMate 后端采用多模块分层架构，核心业务按功能域拆分为 device、store、workflow、common 等模块。API 定义主要位于各模块的 client/api 包中，通过 Feign 声明式客户端对外暴露。
图表来源
章节来源
核心组件
本节对三大核心接口组件进行概览式说明，包括接口职责、请求方式、URL 模式与典型用途。
设备台账接口（DeviceMainApi）
- 职责：提供设备信息查询、库房序列件新增、计量台账查询等能力
- 请求方式：POST、GET（依据具体接口）
- URL 前缀：/api（部分接口）
- 典型用途：设备基础信息批量查询、新增设备台账、IoT 计量数据查询
用户管理接口（SysUserApi）
- 职责：用户信息查询、按姓名批量查询、报表权限标识查询
- 请求方式：GET、POST
- 典型用途：用户检索、权限判定、组织架构联动
仓储管理接口（StockMainApi）
- 职责：库存相关查询与操作（以接口契约为准）
- 请求方式：GET/POST（依据具体接口）
- 典型用途：库存明细查询、出入库登记、调拨转移
章节来源
架构总览
下图展示了 API 的总体交互关系与职责划分：
图表来源
详细组件分析
设备管理 API
设备台账接口（DeviceMainApi）
接口一：批量查询设备信息（for IOT）
- 方法：POST
- URL：/api/query/list
- 请求体：设备编号列表（JSON 数组）
- 响应：ResultData<List<DeviceInfo>>
- 场景：IOT 设备状态同步、批量定位设备
- 示例请求（示意）：POST /api/query/list，Body 为 ["CODE001","CODE002"]
接口二：库房序列件新增设备台账
- 方法：POST
- URL：/store/add
- 请求体：设备台账集合（校验注解启用）
- 响应：ResultData
- 场景：新购设备入库时批量登记
- 示例请求（示意）：POST /store/add，Body 为 [{...},{...}]
接口三：IoT 计量台账查询
- 方法：POST
- URL：/for/iot/list
- 请求体：查询条件映射
- 响应：ResultData<List<DeviceMeasureVo>>
- 场景：计量类设备数据采集与展示
- 示例请求（示意）：POST /for/iot/list，Body 为
图表来源
章节来源
仓储管理 API
库存主接口（StockMainApi）
- 接口职责：库存相关查询与操作（以接口契约为准）
- 请求方式：GET/POST（依据具体接口）
- 典型场景：库存明细查询、出入库登记、调拨转移
- 参数与响应：以接口契约为准，建议遵循统一响应包装
图表来源
章节来源
用户管理 API
用户接口（SysUserApi）
接口一：根据用户代号或账号批量查询
- 方法：GET
- URL：/getUserByNoOrAccount
- 查询参数：
- userNos：用户代号数组（可选）
- accounts：用户账号数组（可选）
- 响应：BaseResponse<List<SysUserVo>>
- 场景：批量用户检索、组织联动
接口二：查询用户信息（带查询对象）
- 方法：POST
- URL：/queryUserInfo
- 请求体：SysUserQueryVo
- 响应：BaseResponse<List<SysUserVo>>
- 场景：复杂条件筛选用户
接口三：根据姓名查询用户
- 方法：GET
- URL：/queryByName
- 查询参数：name（必填）
- 响应：BaseResponse<SysUserVo>
- 场景：单用户快速定位
接口四：根据姓名批量查询用户
- 方法：GET
- URL：/queryByNameList
- 查询参数：names（必填，数组）
- 响应：BaseResponse<List<SysUserVo>>
- 场景：批量用户检索
接口五：判断报表查询管理员权限
- 方法：GET
- URL：/queryUserReportFlag
- 响应：BaseResponse<String>（1 表示可查看全量数据，0 表示仅本部门）
- 场景：报表权限控制
图表来源
章节来源
依赖分析
- 组件内聚与耦合
- 设备模块与通用模块职责清晰分离，设备模块专注设备相关接口，通用模块提供用户与库存等跨域能力
- 外部依赖
- 接口契约依赖统一响应包装类型（如 ResultData、BaseResponse），便于前后端约定一致的数据结构
- 集成点
- 通过网关/服务层统一暴露，便于鉴权、限流、日志与监控
图表来源
章节来源
性能考虑
- 批量接口优先：尽量使用批量查询/新增接口（如设备批量查询、用户批量查询），减少网络往返
- 参数校验前置：启用校验注解（如设备台账新增接口），在网关层尽早拦截无效请求
- 缓存策略：对高频只读数据（如用户信息、字典项）建议引入缓存，降低数据库压力
- 分页与限制：对列表查询建议增加分页与条数限制，避免大结果集导致性能问题
故障排除指南
- 常见错误码
- 400：请求参数缺失或格式不正确（如缺少必填字段、数组为空）
- 401：未授权或会话失效
- 403：权限不足（如报表权限标识为仅本部门）
- 404：接口不存在或资源不存在
- 500：服务器内部错误
- 建议排查步骤
- 确认请求方法与 URL 是否匹配接口定义
- 检查请求头 Content-Type 是否为 application/json
- 核对必填参数是否完整，数组参数长度是否合理
- 查看统一响应中的状态码与消息字段，定位具体错误原因
结论
本文档基于现有接口契约，对 DeviceMate 的设备管理、仓储管理与用户管理三大领域的 API 进行了系统化梳理。建议在后续迭代中补充更详细的实体模型说明与错误码清单，并持续完善统一响应结构，以便为前端与第三方集成提供更稳定可靠的接口体验。