第8章 库存与盘点模块：账实核对与库存闭环

本章目标：开发库存查询/流水（M1 收尾）与盘点（M2）功能。库存是前面所有出入库动作的"结果账本"，盘点则是"拿实物去对这本账"的校正机制。本章练的是聚合查询、多表关联、以及盘盈盘亏如何"生成调整流水并回写库存"。

学习目标

1. 会实现"按商品/按储位"的库存多维查询与汇总
2. 会做库存流水的条件查询与对账展示
3. 理解盘点的"计划数 vs 实盘数 → 差异 → 生成调整"闭环
4. 会用 AI 处理较复杂的关联查询与业务校验

8.1 库存查询：让数据"看得见"

库存数据在第6、7章已经被正确写入，本章给它配上查询能力。库存的看点是多维度汇总。

提示词

开发「库存管理」查询功能（包 com.yjoffer.miniwms.inventory）。# 引用 docs/api.md、#项目规则。
实现：
1. GET /api/inventory/page：库存明细分页，可按 仓库/库区/储位/商品 过滤，
   返回每行含 商品编码/名称/单位、储位编码、数量（关联 basedata 表补齐名称）
2. GET /api/inventory/summary?goodsId=：某商品在各储位/各仓库的分布汇总（每个储位多少、合计多少）
3. GET /api/inventory-log/page：库存流水分页，可按 商品/储位/变动类型(IN/OUT/盘点调整)/时间/关联单号 过滤，
   返回 变动类型、变动数量、变动前/后数量、关联单号、时间
说明：关联查询用 MyBatis-Plus 的方式（能 Wrapper 搞定就别写复杂 XML），需要多表 join 时可写注解/XML SQL。
mvnw compile 后用 curl 演示上面 3 个查询（用第6、7章产生的数据），贴结果。

预期结果

• 能查某商品在各储位的分布及合计
• 流水能按单号追溯："这笔库存变化是哪张单造成的"

注意事项

• ⚠️ 关联查询要防 N+1（列表每行再去查商品名）。确认 AI 用一次 join 或在服务层批量查，别循环里查库。让 AI 说明它怎么避免 N+1。
• 💡 这一步做完，M1 的功能就全齐了。可对照第2章那句"M1 验收标准"先自查一遍。

8.2 盘点：从"计划数 vs 实盘数"到库存校正

盘点流程：创建盘点单（选定范围：某仓库/库区）→ 系统带出"账面应存数"→ 仓管员录入"实盘数"→ 生成差异（盘盈/盘亏）→ 审核确认后，按差异调整库存并写"盘点调整"流水。

先做后端主结构与差异计算。

提示词

开发「盘点」模块（包 com.yjoffer.miniwms.stocktake，表 wms_stocktake_order / wms_stocktake_item）。
# 引用 docs/需求规格说明书.md 盘点流程、#docs/api.md、#项目规则。参照入库/出库的分层与状态机风格。

盘点单主表：单号PD+日期+流水、仓库、范围(可选库区)、状态(DRAFT盘点中/CONFIRMED已确认/CANCELLED)、制单人
盘点明细：goods_id、location_id、book_qty(账面数，创建时从 wms_inventory 带出)、actual_qty(实盘数，盘点时录入)、diff_qty(差异=actual-book)

接口：
1. POST /api/stocktake：创建盘点单，按范围(仓库/库区)抓取该范围内所有"商品+储位"的当前账面库存，
   生成明细并带出 book_qty，actual_qty 先为空/等于book
2. PUT /api/stocktake/{id}/items：录入实盘数 actual_qty，自动算 diff_qty（盘点中状态才可录）
3. POST /api/stocktake/{id}/confirm：确认盘点，在【单个事务】内对所有 diff_qty≠0 的明细：
   - 按 diff_qty 调整 wms_inventory（盘盈加、盘亏减；盘亏减到负要拦截）
   - 写 wms_inventory_log 变动类型=ADJUST（盘点调整），记录变动前后数量、关联盘点单号
   完成后状态置 CONFIRMED
4. GET /api/stocktake/page、/{id} 查询
mvnw compile 通过后自测：建盘点→改某行实盘制造盘盈盘亏→确认→验证库存被正确调整、有 ADJUST 流水。

关键校验：盘亏不能把库存调成负数

盘亏是"账面上有、实物没有"，直接把库存往下调。如果实盘录错导致盘亏超过账面，会把库存调成负数——这是数据事故。

追加提示词

盘点确认时对"盘亏"增加硬校验：调整后库存不得为负。若某明细 actual_qty 使库存会变成负数，
拒绝确认并提示。请说明你是在 diff 计算阶段拦截，还是在条件 UPDATE（qty >= -diff）阶段拦截，
并演示一次"盘亏超量被拒绝、库存保持不变"。

注意事项

• ⚠️ 盘点调整同样要走"库存变动 = 改库存 + 写流水"的原子事务，和出入库一致。别让盘点绕过流水直改库存，否则账本又对不上了。
• 💡 盘点范围、生成明细依赖当前库存快照——这解释了为什么第3章要求 wms_inventory 有 (goods_id, location_id) 唯一索引：盘点带数才不会重复。

8.3 前端：库存查询页 + 盘点页

提示词

参照已有前端风格，生成：
1. 库存查询 InventoryList.vue：过滤区(仓库/库区/储位/商品) + 表格 + 分页；一个"库存分布"弹窗看单商品多储位汇总
2. 库存流水 InventoryLogList.vue：过滤(商品/类型/时间/单号) + 表格；变动类型用不同颜色标签、数量带 +/-
3. 盘点 StocktakeList.vue + StocktakeEdit.vue：列表；创建盘点(选仓库/库区)→进编辑页录入各行实盘数、
   实时显示差异(盘盈绿/盘亏红)→确认盘点
菜单加「库存管理」「盘点管理」，npm run dev 验证。

8.4 提交

库存查询、流水、盘点(含盘盈盘亏调整)前后端完成，自测通过。
git add . && git commit -m "feat: 库存查询/流水/盘点模块完成，M1+盘点闭环打通"

本章检查清单

• [ ] 库存明细分页、单商品多储位汇总、流水查询均可用
• [ ] 流水能按关联单号追溯每一笔变动来源
• [ ] 盘点：创建带账面数 → 录实盘 → 差异计算 → 确认调整库存 + 写 ADJUST 流水
• [ ] 盘亏不会导致库存为负（有拦截且演示过）
• [ ] 前端库存/流水/盘点页面完成
• [ ] 已提交 Git

至此全部业务模块完成。进入 第9章 测试修复与部署，做质量收尾并上线。

常见问题

Q：盘点差异调整，和直接改库存数字有什么区别？ A：直接改数字 = 破坏账本，事后无法解释库存为什么变了。走"调整流水"= 每次变动都有据可查（谁、哪张盘点单、从多少变到多少）。WMS 的铁律是库存的每一次变化都必须有一条流水，盘点也不例外。

Q：库存查询要 join 那么多表，AI 写得又慢又乱？ A：把范围收窄：先只做"库存明细 + 商品名/储位名"最小必要关联，汇总/分布作为单独接口。别在一个接口里既要明细又要多级汇总。让 AI 拆成两个接口分别实现，各自简单。

Q：盘点是不是超出 M1 了？ A：是的，盘点属于 M2。如果你想先快速拿到可运行成果，可以把 8.2 盘点跳到第10章之后再回来做；8.1 库存查询（M1 必需）务必完成。