DM-ROW 接口文档

Appearance

库存主数据管理 ​

**本文引用的文件** - [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) - [StockDetailDo.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/StockDetailDo.java) - [SafeStockDo.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/SafeStockDo.java) - [StockValueStatisticsDo.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/StockValueStatisticsDo.java) - [StockCheckDetailDo.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/StockCheckDetailDo.java) - [StockCheckOrdersDo.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/StockCheckOrdersDo.java) - [StockMainMapper.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/mapper/store/StockMainMapper.java) - [StockMainService.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/service/store/StockMainService.java) - [StockValueStatisticsServiceImpl.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/service/store/impl/StockValueStatisticsServiceImpl.java) - [StoreInOrderDetailDo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/store/StoreInOrderDetailDo.java) - [StoreOutDetailVo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/store/StoreOutDetailVo.java) - [StoreMainVo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/store/StoreMainVo.java) - [StockMainVo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/store/StockMainVo.java)

目录 ​

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

引言 ​

本技术文档围绕库存主数据管理模块展开，系统性阐述库存实体与明细模型的设计原理、库存查询与统计机制、安全库存管理策略，以及与入出库流程、调拨转移等模块的关联关系。文档以“库存主数据”为核心，结合仓库维度（仓库、库区、库位）、物料维度（物料、产品线）与批次/有效期维度，给出可操作的最佳实践与接口使用指引。

项目结构 ​

库存主数据管理涉及两类代码域：

  • 领域模型与服务：位于 lemes-cloud 的 store-common 模块，定义库存主表、明细表、安全库存、价值统计、盘点相关实体。
  • 作业执行与统计：位于 lemes-job-devicemate 的 executor 模块，提供按日聚合的库存查询、价值统计作业等。

图表来源

章节来源

核心组件 ​

  • 库存主数据 StockMainDo：描述某仓库/库区/库位下某物料/产品线的总库存、在库库存、其他库存（如LSSC）等聚合值。
  • 库存明细 StockDetailDo：承载批次（序列号/箱号）、包装数量、单价、有效期、剩余寿命、入库时间、冻结数量、在库标识等细粒度信息。
  • 安全库存 SafeStockDo：定义某仓库-物料的安全上下限与最高库存，用于库存预警与优化建议。
  • 库存价值统计 StockValueStatisticsDo：按仓库/产品线/统计日期/金额类型存储库存金额统计结果。
  • 盘点相关：StockCheckOrdersDo（盘点单）、StockCheckDetailDo（盘点明细），支撑库存准确性校验与差异处理。

章节来源

架构总览 ​

库存主数据管理采用“领域模型 + 作业执行”的分层架构：

  • 领域模型层：定义库存主数据、明细、安全库存、统计与盘点实体，确保数据一致性与可扩展性。
  • 作业执行层：通过按日聚合查询与价值统计作业，驱动库存报表与预警分析；同时与入出库明细联动，计算在库/在线库存金额。

图表来源

详细组件分析 ​

数据模型与字段定义 ​

  • 库存主数据 StockMainDo
    • 关键字段：台账代号、仓库/库区/库位代号、物料代号、产品线代号、库存总数量、在库库存、其他库存。
    • 业务含义：作为库存聚合的主键维度，支持按仓库/库区/库位/物料/产品线多维查询与统计。
  • 库存明细 StockDetailDo
    • 关键字段：台账代号、序列号、箱号、包装数量、剩余库存、单价、有效期、剩余寿命、入库时间、冻结数量、在库标识。
    • 业务含义：支撑批次管理、有效期控制、冻结库存与成本核算。
  • 安全库存 SafeStockDo
    • 关键字段：仓库代号、物料代号、最高库存、最低库存、安全库存。
    • 业务含义：为库存优化与预警提供阈值依据。
  • 库存价值统计 StockValueStatisticsDo
    • 关键字段：仓库代号、产品线代号、统计日期、统计金额、金额类型（在线/在库/入库/出库）。
    • 业务含义：形成库存金额的时序化报表，辅助财务与运营分析。
  • 盘点相关
    • StockCheckOrdersDo：盘点单号、仓库、责任人、盘点时间、状态、审批信息。
    • StockCheckDetailDo：物料、库区/库位、序列号/箱号、包装数量、库存数量、盘点数量、结果、备注等。

图表来源

章节来源

库存查询与统计机制 ​

  • 按日查询
    • 接口：StockMainService.queryListByDay 返回库存聚合视图。
    • 实现：StockMainMapper.searchListByDay 提供按日聚合SQL。
  • 价值统计作业
    • 触发：StockValueStatisticsServiceImpl.stockCountList 按日汇总在线/在库库存金额。
    • 输入：当日库存聚合（来自 queryListByDay）。
    • 输出：按仓库/产品线/日期/金额类型的统计记录。

图表来源

章节来源

安全库存管理 ​

  • 设计要点
    • SafeStockDo 提供仓库-物料维度的安全上下限与最高库存，用于库存健康度评估与预警。
    • 价值统计作业中存在安全库存相关逻辑（注释片段），可用于生成安全库存不足的预警清单或颜色标记。
  • 使用建议
    • 基于 SafeStockDo 的阈值，对在库可用库存进行分级（如低于最小库存、低于安全库存、高于最高库存等）。
    • 结合入库/出库明细，动态更新在库可用库存与有效期，确保预警准确。

章节来源

批次管理与有效期控制 ​

  • 批次与有效期
    • StockDetailDo 提供序列号、箱号、有效期、剩余寿命、入库时间等字段，支撑批次追踪与效期管理。
    • StoreInOrderDetailDo 与 StoreOutDetailVo 含有有效期、入库时间、可用库存等字段，便于出入库场景下的效期控制。
  • 实施建议
    • 入库时写入有效期与剩余寿命；出库时按“先进先出”原则匹配批次。
    • 对接近有效期的库存进行预警与优先出库策略。

章节来源

与入出库流程的关联 ​

  • 入库流程
    • StoreInOrderDetailDo 描述入库单明细，包含仓库/库区/库位、序列号/箱号、包装数量、入库数量、单价、有效期等。
  • 出库流程
    • StoreOutDetailVo 提供出库明细视图，含规格、单位、ABC分类、控制类型、最大寿命、入库时间、实际可用库存等，支撑出库拣货与效期校验。
  • 与库存主数据的关系
    • 入出库明细通过仓库/库区/库位/物料/产品线维度与 StockMainDo 聚合，形成实时在库/在线库存。
    • 价值统计基于入出库单价与数量，计算库存金额。

图表来源

依赖分析 ​

  • 组件耦合
    • StockMainService 依赖 StockMainMapper 进行按日查询。
    • StockValueStatisticsServiceImpl 依赖 StockMainService 获取库存聚合，并依赖入库/出库明细进行金额统计。
    • 入出库明细与库存明细/主数据形成强关联，保证库存数据的准确性与时效性。
  • 外部依赖
    • MyBatis-Plus 注解（@TableName、@DS）用于数据库映射与数据源切换。
    • Lombok 注解（@Data、@Builder、@Accessors）简化实体定义。

图表来源

章节来源

性能考虑 ​

  • 查询优化
    • 按日聚合查询应建立合适的索引（仓库/库区/库位/物料/产品线组合），减少全表扫描。
    • 分页与缓存：对高频查询结果进行缓存，降低数据库压力。
  • 统计作业
    • 批处理与事务：价值统计作业应使用批处理与事务控制，避免长时间锁表。
    • 并行化：对不同仓库/产品线的统计任务进行并行化拆分，提升吞吐。
  • 批次与效期
    • 对接近有效期的库存进行预筛选，减少无效扫描。
    • 入库/出库时尽量批量提交，降低事务开销。

故障排查指南 ​

  • 常见问题
    • 库存金额统计为零：检查当日库存聚合是否为空，确认单价与数量字段是否缺失。
    • 安全库存预警不生效：核对 SafeStockDo 中的阈值配置，确认统计作业中的阈值比较逻辑。
    • 入出库后库存不一致：核查入出库明细与库存主数据/明细的维度一致性（仓库/库区/库位/物料/产品线）。
  • 排查步骤
    • 核对 StockMainMapper 的按日查询SQL与数据库索引。
    • 检查 StockValueStatisticsServiceImpl 的统计逻辑与事务边界。
    • 对照 StoreInOrderDetailDo 与 StoreOutDetailVo 的字段映射，确保效期与可用库存正确。

章节来源

结论 ​

库存主数据管理模块通过清晰的实体模型与按日统计作业，实现了从库存聚合到价值统计的完整闭环。结合安全库存与批次/有效期管理，能够有效支撑库存优化与风险控制。建议在生产环境中完善索引、缓存与并行化策略，持续监控统计作业的稳定性与准确性。

附录 ​