基础资料、商品与库存

模块职责

基础资料是所有单据的前置口径，决定“谁买、买什么、从哪里出、按什么价格、走什么权限”。库存模块负责把各种入库、出库、调拨、盘点、关闭和撤销动作落成库存流水，并维护实时库存。

主要入口

  • 基础资料控制器：application/controllers/basedata
  • 商品控制器：application/controllers/inner/Goods.php、application/controllers/inner/Materiel.php
  • 库存控制器：application/controllers/Storage.php、application/controllers/scm/InvOi.php、application/controllers/scm/InvTf.php、application/controllers/pda
  • App 商品和库存 API 映射：application/config/appapis.php
  • 商品同步老接口映射：application/config/apis.php

关键 Service

  • application/Services/Materiels/MaterielSer.php：物料格式化、新增/更新、分类、扩展数据、供货状态、VIN 同步通知。
  • application/Services/Materiels/MaterielCacheSer.php：物料缓存。
  • application/Services/Materiels/MaterielCacheQuerySer.php：普通物料缓存查询。
  • application/Services/Materiels/MaterielCacheQueryEsSer.php：ES 物料查询。
  • application/Services/Materiels/MaterielCacheStationSer.php：服务站维度物料缓存。
  • application/Services/BaseData/StockSer.php：仓库/货位库存查询。
  • application/Services/Storage/InventorySer.php：库存流水保存、删除、实时库存加减。
  • application/Services/KzInventory/KzInventorySer.php：库存中心相关能力。
  • application/Services/BaseData/PriceManagerSer.php、QuoteManagerSer.php：价格、报价、客户价格规则。

关键模型

  • 商品：application/models/bs/GoodsModel.php、GoodsExtModel.php、GoodsCategoryModel.php、GoodsBarCodeModel.php
  • 物料：application/models/materiels
  • 库存：application/models/bs/InventoryModel.php、InventorySubModel.php、InventoryRealTimeModel.php
  • 仓库货位：application/models/bs/StockModel.php、application/models/bs/StoreModel.php
  • 客户和供应商：application/models/bs/ContactModel.php、SupplierModel.php
  • 价格：ContactPriceModel.php、QuoteRuleModel.php、CostPriceModel.php

商品主流程

商品中心/后台录入
  -> MaterielSer::formatData / formatGoodsData 规整字段
  -> 校验分类、品牌、单位、供货状态、备货状态
  -> 写入 bs_goods / goods_ext / materiels 相关表
  -> 刷新缓存或 ES
  -> MqSer::sendGoodsUpdateToVin 通知 VIN/数据平台
  -> 被采购、销售、活动、移动商城查询

关键业务字段：

  • skuId：外部或商品中心 SKU 编码。
  • invId：站管家内部商品 ID，单据明细大量使用。
  • number、name、brand、category：商品展示和筛选字段。
  • status：供货状态，具体值看 application/KzData/Enums/MaterielEnums.php。
  • stockType：备货状态。

库存主流程

库存不是只看一张表，系统同时维护流水和实时库存：

  • 库存流水：记录每次业务单据引起的库存变化，来源是 InventorySubModel。
  • 实时库存：按服务站、商品、仓库、货位汇总当前数量，来源是 InventoryRealTimeModel。
  • 库存查询：采购、销售、活动、移动商城大多最终会查实时库存或库存中心封装。

InventorySer::save() 的业务含义：

  • 接收业务单据组装好的库存明细。
  • 写入库存流水，包含 sid、iid、billType、transType、invId、skuId、locationId、locationAreaId、qty。
  • 调用 changeInventoryQty() 增减实时库存。
  • 销售出库时还会触发商品销量或搜索数据更新。

InventorySer::delete() 的业务含义：

  • 根据单据 ID、单据类型、交易类型找到旧库存流水。
  • 按反向数量回滚实时库存。
  • 删除或标记旧流水。

常见库存交易类型

交易类型在 application/KzData/Enums/TransTypeEnums.php：

  • 150501：采购入库。
  • 150502：销售退货入库。
  • 150601：普通销售出库。
  • 150602：销售订单退货。
  • 150706：其他入库。
  • 150806：其他出库。
  • 150701：盘盈。
  • 150801：盘亏。
  • 103091：调拨单。
  • 103092：服务站间调拨单。
  • 170500、170501、170502：货位调整。

业务边界

  • 采购入库增加库存，采购退货或未发货关闭不一定直接减库存，要看单据状态和是否已经入库/出库。
  • 销售出库减少库存，销售退货入库增加库存。
  • 盘点调整可能增加或减少库存。
  • 货位调整需要同时处理调出货位和调入货位，不能只看商品总库存。
  • 秒杀、活动、移动商城会额外检查活动库存、锁定库存、服务站仓库存或指定仓库存。

排查建议

  • 商品查不到：先查 skuId 和 invId 是否对应，再看物料状态、分类、服务站缓存。
  • 列表有库存但下单库存不足：确认查询口径是服务站对应仓、指定仓、全局预留还是库存中心返回。
  • 库存异常：先看库存流水，再看实时库存；如果流水正确但实时库存错，重点查 InventorySer::changeInventoryQty() 调用链。
  • 报表库存和业务库存不一致：业务库实时库存与 Hologres/BI 表有同步延迟或口径差异，报表入口在 application/Services/Report。