仓储管理服务

**本文引用的文件** - [store.sql](file://docs/ddl/store.sql) - [StockMainDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/StockMainDo.java) - [PartMainDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/PartMainDo.java) - [SupplierDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/SupplierDo.java) - [StoreMainDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/StoreMainDo.java) - [StockMainVo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/vo/StockMainVo.java) - [StockMainController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/StockMainController.java) - [StoreInOrdersController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/StoreInOrdersController.java) - [StoreOutOrdersController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/StoreOutOrdersController.java) - [StoreTransferOrdersController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/StoreTransferOrdersController.java) - [StoreExceptionCode.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/constant/StoreExceptionCode.java)

目录

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

引言

本技术文档面向仓储管理服务，聚焦于库存主数据、物料主数据、供应商管理等核心模块，并深入解析入库、出库、调拨转移、库存盘点等业务场景的实现机制。同时，给出仓储相关的RESTful接口规范、数据模型定义、最佳实践建议（如库存优化策略、批次管理、有效期控制），并提供可追溯的源码路径以便开发者快速理解与落地。

项目结构

仓储管理服务位于后端工程 lemes-cloud 的 lemes-business-devicemate 子模块中，采用“公共模型 + 服务端”的分层组织方式：

• 公共模块：定义实体、VO、常量与通用工具，供各业务模块复用
• 服务端：提供控制器、服务层、Mapper 层，承载具体业务逻辑与对外接口

图表来源

• StockMainController.java:22-277
• StoreInOrdersController.java:20-75
• StoreOutOrdersController.java:21-129
• StoreTransferOrdersController.java:19-90

章节来源

• StockMainController.java:22-277
• StoreInOrdersController.java:20-75
• StoreOutOrdersController.java:21-129
• StoreTransferOrdersController.java:19-90

核心组件

• 实体层：库存台账、物料主数据、供应商、仓库等核心实体
• VO 层：用于接口返回与查询封装
• 控制器层：暴露 RESTful 接口，统一返回结构
• 异常常量：集中定义仓储模块的错误码

章节来源

• StockMainDo.java:1-64
• PartMainDo.java:1-130
• SupplierDo.java:1-73
• StoreMainDo.java:1-62
• StockMainVo.java:1-274
• StoreExceptionCode.java:1-367

架构总览

仓储服务遵循典型的三层架构：控制器负责请求接入与参数校验，服务层编排业务流程，持久层通过 MyBatis-Plus 访问数据库。接口统一返回 ResultData 包裹，便于前端消费与错误处理。

图表来源

• StockMainController.java:22-277
• StoreInOrdersController.java:20-75
• StoreOutOrdersController.java:21-129
• StoreTransferOrdersController.java:19-90
• store.sql:1-800

详细组件分析

库存主数据模块

• 功能职责：提供库存台账查询、明细查询（普通/序列/批次）、序列号生成、库内平移、导出、按仓库/产品线筛选等能力
• 关键接口
  • 分页查询库存台账：POST /stockMain/page
  • 查询库存明细（普通/序列/批次）：POST /stockMain/pageGeneral | pageOrder | pageBatch
  • 库内平移：POST /stockMain/moveInStore
  • 序列号生成：POST /stockMain/queryOrderNumber
  • 导出：POST /stockMain/exportExcel | exportOrderExcel | exportBatchExcel
  • 产品线/仓库/物料选择：POST /stockMain/product/line | product/lineNoRepeat | list/part | store/select
  • 根据仓库/序列号查询存储信息：GET /stockMain/findStorePartInfoListByStoreNo | /getPartMainStoreInfoBySerialNo
  • 在线库存查询：POST /stockMain/part/getInStockNumber | /part/getPartStoreInfoList
  • 仓库+物料库存数量：GET /stockMain/store/number/list | /store/number | /store/number/no
  • 库区库位查询：POST /stockMain/store/getAreaAndBin

图表来源

• StockMainController.java:37-42
• StockMainDo.java:1-64

章节来源

• StockMainController.java:22-277
• StockMainDo.java:1-64
• StockMainVo.java:1-274

物料主数据模块

• 功能职责：维护物料主数据，包含物料编码/名称/规格/UOM/控制类型/价格/有效期/寿命件等属性
• 关键实体字段要点
  • 物料代号/编码/名称/规格/UOM
  • 控制类型、币种、单价
  • 是否有效期件/寿命件、最大寿命值及单位
  • 首选供应商、ABC分类、序列号生成规则等

图表来源

• PartMainDo.java:1-130

章节来源

• PartMainDo.java:1-130

供应商管理模块

• 功能职责：维护供应商基础信息，支持查询、导入等
• 关键实体字段要点
  • 供应商代号/编码/名称/地址/联系人/电话/邮箱/传真/网址/备注/有效标志

图表来源

• SupplierDo.java:1-73

章节来源

• SupplierDo.java:1-73

仓库管理模块

• 功能职责：维护仓库基础信息，包括仓库编码/名称/所属部门/类型/管理员/位置/有效标志等
• 关键实体字段要点
  • 仓库代号/编码/名称/部门代号/仓库类型/管理员账户/位置/管理员名称/有效标志

图表来源

• StoreMainDo.java:1-62

章节来源

• StoreMainDo.java:1-62

入库流程模块

• 功能职责：提供入库单的分页查询、导出、批量删除、按ID查询等能力
• 关键接口
  • 分页查询：POST /storeInOrders/page
  • 导出：POST /storeInOrders/exportExcel
  • 批量删除：POST /storeInOrders/delete
  • 按ID查询：GET /storeInOrders/by/

图表来源

• StoreInOrdersController.java:20-75

章节来源

• StoreInOrdersController.java:20-75

出库流程模块

• 功能职责：提供出库单的分页查询、新增/更新、出库、退回、详情查询、批量删除、导出等能力
• 关键接口
  • 分页查询：POST /storeOutOrders/page
  • 新增：POST /storeOutOrders/add
  • 更新：POST /storeOutOrders/update
  • 出库：POST /storeOutOrders/stockOut
  • 退回：POST /storeOutOrders/doReturn
  • 详情：POST /storeOutOrders/detail
  • 批量删除：POST /storeOutOrders/delete
  • 导出：POST /storeOutOrders/exportExcel

图表来源

• StoreOutOrdersController.java:21-129

章节来源

• StoreOutOrdersController.java:21-129

调拨转移模块

• 功能职责：提供调拨单的分页查询、新增、删除、按单号查询、导出、获取单号等能力
• 关键接口
  • 分页查询：POST /store/transfer/page
  • 新增：POST /store/transfer/add
  • 删除：GET /store/transfer/del/
  • 按单号查询：GET /store/transfer/query/
  • 导出：POST /store/transfer/export
  • 获取单号：GET /store/transfer

图表来源

• StoreTransferOrdersController.java:19-90

章节来源

• StoreTransferOrdersController.java:19-90

数据模型与关系

基于 DDL 定义与实体映射，仓储核心数据模型如下：

图表来源

• store.sql:384-481
• store.sql:252-314
• store.sql:203-251
• store.sql:420-481
• PartMainDo.java:1-130
• SupplierDo.java:1-73
• StoreMainDo.java:1-62
• StockMainDo.java:1-64

章节来源

• store.sql:203-481
• PartMainDo.java:1-130
• SupplierDo.java:1-73
• StoreMainDo.java:1-62
• StockMainDo.java:1-64

依赖分析

• 控制器依赖服务层，服务层依赖 Mapper，Mapper 依赖数据库
• 统一异常码集中于 StoreExceptionCode，便于错误识别与国际化
• 实体与 VO 通过 MyBatis-Plus 注解映射到数据库表

图表来源

• StoreExceptionCode.java:1-367

章节来源

• StoreExceptionCode.java:1-367

性能考虑

• 分页查询：优先使用分页接口，避免一次性加载大量数据
• 导出优化：对大表导出建议异步任务+分批写入，避免阻塞主线程
• 字段选择：导出时仅选择必要字段，减少网络与内存开销
• 缓存策略：对高频只读数据（如字典/基础配置）可引入缓存
• 并发控制：出库/调拨等涉及库存变更的操作需加锁或使用乐观锁，确保一致性

故障排查指南

• 参数校验失败：检查请求体与必填字段，参考接口注释与 VO 定义
• 重复数据冲突：依据异常码定位重复项（如仓库/库区/库位/物料编码重复）
• 导入失败：核对 Excel 格式与字段映射，关注重复序列号/箱号等提示
• 库存不足：确认在库数量与冻结数量，检查是否被占用或锁定

常见错误码定位参考：

• 仓库/库区/库位/物料编码重复：EX201001 ~ EX201052
• 供应商名称/编码重复：EX201011 ~ EX201012
• 物料名称/编码重复：EX201024 ~ EX201025
• 导入文件中存在相同序列号/箱号：EX201051 / EX201052
• 供应商不存在：EX201060

章节来源

• StoreExceptionCode.java:1-367

结论

仓储管理服务以清晰的分层架构与完善的实体/VO/异常体系支撑库存、物料、供应商与仓库等核心业务。通过 RESTful 接口与统一返回结构，满足多终端接入需求；结合 DDL 定义与实体映射，形成稳定的数据模型与关系约束。建议在生产环境中配合缓存、异步导出与并发控制等手段进一步提升性能与稳定性。

附录

• 接口规范示例（以路径与方法为主，具体参数以各控制器为准）
  • 库存台账
    • POST /stockMain/page
    • POST /stockMain/pageGeneral
    • POST /stockMain/pageOrder
    • POST /stockMain/pageBatch
    • POST /stockMain/moveInStore
    • POST /stockMain/queryOrderNumber
    • POST /stockMain/exportExcel
    • POST /stockMain/exportOrderExcel
    • POST /stockMain/exportBatchExcel
    • POST /stockMain/product/line
    • POST /stockMain/product/lineNoRepeat
    • POST /stockMain/list/part
    • POST /stockMain/store/select
    • GET /stockMain/findStorePartInfoListByStoreNo
    • GET /stockMain/getPartMainStoreInfoBySerialNo
    • POST /stockMain/part/getInStockNumber
    • POST /stockMain/part/getPartStoreInfoList
    • GET /stockMain/store/number/list
    • GET /stockMain/store/number
    • GET /stockMain/store/number/no
    • POST /stockMain/store/getAreaAndBin
  • 入库单
    • POST /storeInOrders/page
    • POST /storeInOrders/exportExcel
    • POST /storeInOrders/delete
    • GET /storeInOrders/by/
  • 出库单
    • POST /storeOutOrders/page
    • POST /storeOutOrders/add
    • POST /storeOutOrders/update
    • POST /storeOutOrders/stockOut
    • POST /storeOutOrders/doReturn
    • POST /storeOutOrders/detail
    • POST /storeOutOrders/delete
    • POST /storeOutOrders/exportExcel
  • 调拨单
    • POST /store/transfer/page
    • POST /store/transfer/add
    • GET /store/transfer/del/
    • GET /store/transfer/query/
    • POST /store/transfer/export
    • GET /store/transfer