DM-ROW 接口文档

Appearance

库存盘点管理 ​

**本文引用的文件** - [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) - [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) - [StockCheckOrdersVo.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/StockCheckOrdersVo.java) - [StockCheckDetailVo.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/StockCheckDetailVo.java) - [CheckDetailsExcelVo.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/excel/CheckDetailsExcelVo.java) - [CheckDetailsImport.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/excel/CheckDetailsImport.java) - [CheckStockExcelVo.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/excel/CheckStockExcelVo.java) - [StockCheckDetailExportVo.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/StockCheckDetailExportVo.java) - [StockCheckDetailNumVo.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/StockCheckDetailNumVo.java) - [StockCheckQueryVo.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/StockCheckQueryVo.java) - [StockCheckOrdersVo.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/StockCheckOrdersVo.java) - [StockCheckDetailVo.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/StockCheckDetailVo.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) - [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)

目录 ​

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

简介 ​

本技术文档围绕库存盘点管理模块展开，重点覆盖以下方面：

  • 盘点订单与明细的数据模型设计与职责边界
  • 盘点计划制定、任务分配、执行、差异处理的业务流程
  • 实际盘点与系统库存的对比分析机制
  • 不同盘点场景（循环盘点、专项盘点、期末盘点）的实现思路
  • 盘点数据的Excel导入导出能力（模板、校验、批量处理）
  • 盘点管理API接口设计（计划创建、执行、差异上报、处理确认）
  • 最佳实践（盘点策略、准确性保障、效率提升）

项目结构 ​

本模块位于设备与仓储业务域下的仓储子域中，核心数据模型与视图对象集中于 store-common 模块，Excel导入导出与查询参数位于同一包下，便于统一管理。

图表来源

章节来源

核心组件 ​

  • 盘点订单实体：承载盘点单基本信息、仓库归属、责任人、审批信息与状态流转字段。
  • 盘点明细实体：承载每个盘点货位/序列的库存数与盘点数、差异结果、备注等。
  • 订单/明细视图：用于对外接口的数据封装与参数校验。
  • 导入导出与查询参数：支撑Excel导入导出、数量统计与查询过滤。

章节来源

架构总览 ​

从数据模型到接口与Excel处理的整体关系如下：

图表来源

详细组件分析 ​

盘点订单 StockCheckOrdersDo 设计与流程 ​

  • 设计要点
    • 单据主键与业务标识：包含盘点单号、仓库代号、责任人与审批信息。
    • 状态字段：盘点状态与审批状态，支持流程化推进。
    • 扩展性：基于通用基类扩展，便于审计与扩展字段。
  • 执行流程（概念性）
    • 制定盘点计划：生成盘点单号、选择仓库、设定盘点时间与责任人。
    • 分配任务：按库区/库位或产品线维度下发盘点任务。
    • 执行盘点：移动端或PC端录入实际盘点数，形成明细。
    • 差异处理：系统自动比对库存数与盘点数，生成差异并进入审批/处理流程。
    • 归档结案：完成审批与处理后关闭单据。

章节来源

盘点明细 StockCheckDetailDo 处理机制 ​

  • 字段覆盖范围：包含盘点单号、物料、库区/库位、序列号/箱号、包装数量、库存数、盘点数、结果、入账产线与备注。
  • 对比分析逻辑（概念性）
    • 库存数来自系统当前可用库存；盘点数由执行端录入。
    • 差异 = 盘点数 - 库存数；结果可标记为正常、盘盈、盘亏等。
    • 支持按库位/序列/箱号进行精细化差异定位。
  • 数量统计与导出
    • 提供数量汇总视图与导出视图，便于报表与审批材料输出。

章节来源

Excel 导入导出与批量处理 ​

  • 导入模板
    • 明细导入模板：包含盘点单号、物料、库区/库位、序列/箱号、包装数量、库存数、盘点数等字段。
    • 库存导入模板：用于批量导入系统库存快照，作为对比基准。
  • 数据校验
    • 字段必填性与格式校验（如单号、物料编码、库区/库位编码、数量类型等）。
    • 关联性校验（仓库与库区/库位匹配、物料在系统中存在等）。
  • 批量处理
    • 基于导入模板解析后，批量写入明细表，并触发差异计算与状态更新。

图表来源

不同盘点场景实现方案 ​

  • 循环盘点
    • 频率：周期性滚动覆盖全仓或部分区域。
    • 方案：按库区/库位设定轮换周期，结合任务分配与执行提醒。
  • 专项盘点
    • 触发：针对特定物料、批次、序列或问题区域。
    • 方案：定向下发任务，限制盘点范围，加强差异复核。
  • 期末盘点
    • 触发：会计期末结账前。
    • 方案：全仓或全产品线盘点，严格审批流程与差异处理时限。

（本节为概念性说明，不直接分析具体文件）

API 接口设计（概念性） ​

  • 盘点计划创建
    • 请求：仓库、盘点时间、责任人、审批信息
    • 返回：盘点单号与初始状态
  • 盘点执行
    • 请求：明细录入（盘点数、序列/箱号、备注）
    • 返回：保存成功与实时差异
  • 差异上报
    • 请求：差异明细与原因说明
    • 返回：差异单据与审批入口
  • 处理确认
    • 请求：审批通过/驳回
    • 返回：状态变更与库存调整（如适用）

（本节为概念性说明，不直接分析具体文件）

依赖关系分析 ​

  • 组件内聚与耦合
    • 实体与视图分离，降低接口与存储层耦合。
    • Excel导入导出与明细/订单视图解耦，便于独立演进。
  • 外部依赖
    • Excel处理依赖通用框架（见 lemes-framework-excel 模块）。
    • 查询参数与导出视图依赖通用工具与枚举。

图表来源

性能考虑 ​

  • 批量导入优化
    • 使用批量写入与事务控制，减少往返开销。
    • 导入前进行字段与关联性预校验，降低失败重试成本。
  • 查询与导出
    • 明细导出采用分页与增量策略，避免大表一次性导出。
    • 统计视图缓存近期高频查询结果，缩短响应时间。
  • 差异计算
    • 明细层面的差异计算应尽量在服务端聚合，避免逐条对比带来的性能损耗。

（本节提供一般性指导，不直接分析具体文件）

故障排查指南 ​

  • 常见问题
    • 导入失败：检查模板字段是否齐全、编码是否正确、仓库与库区/库位是否匹配。
    • 差异异常：核对库存快照是否最新、盘点数是否为整数、序列/箱号是否唯一。
    • 导出为空：确认查询条件是否过严、权限是否允许导出该仓库/区域。
  • 建议步骤
    • 查看导入返回的错误清单，逐项修正。
    • 在明细列表中筛选差异单据，复核差异原因与处理状态。
    • 如涉及库存调整，确保审批流程已闭环后再进行后续操作。

（本节提供一般性指导，不直接分析具体文件）

结论 ​

本模块以清晰的数据模型与视图对象为基础，配合Excel导入导出与查询统计能力，能够支撑多种盘点场景。通过标准化的流程与状态管理，可有效提升盘点准确性与效率。建议在实际落地时结合业务规则完善审批与差异处理流程，并持续优化导入导出与查询性能。

附录 ​

  • 盘点场景最佳实践
    • 循环盘点：设定轮换周期与预警机制，定期复盘差异趋势。
    • 专项盘点：限定范围与责任人，强化审批与复核。
    • 期末盘点：提前冻结出入库、确保库存快照准确、预留充足审批时间。
  • 准确性保障
    • 强制序列/箱号唯一性校验；引入双人复核与抽盘机制。
    • 定期对账与差异复盘，持续改进盘点策略。
  • 效率提升
    • 移动端扫码/RFID辅助录入；批量导入与自动差异计算；智能任务分配与进度可视化。

（本节为概念性总结，不直接分析具体文件）