Skip to main content

存货核算管理 · 进销存台账 —— 需求解读与改造方案(合并版 v2.0)

存货核算管理 · 进销存台账 —— 需求解读与改造方案(合并版 v2.0)

一份文档,两类读者:上篇(§1–§10)大白话讲懂需求,给产品/业务/老板看;下篇(§11–§15)技术分析与实施,给开发/实施看。
上篇不出现任何技术名词;下篇结论均有代码证据(附录 A)。
现状盘点:wimoor-finance / wimoor-erp / wimoor-ui / init-config(2026-11-11)。本档为方案,不含代码改动。
衔接文档:《ERP库存操作-财务凭证重构方案.md》(outbox 事件层)、《AI实施任务书-采购付款入库凭证新架构.md》(凭证池/映射规则)——本方案在"存货成本"维度上延伸,不推翻其已裁决结论。
合并说明:由《需求解读大白话版》与《进销存台账改造方案 v1.0》合并而来,两份原文不再单独维护。


上篇 · 需求解读(大白话)

1. 这个功能到底是干啥的?

一句话:老板问"仓库里的货值多少钱",系统要能用会计认可的方式回答,并且这个数能和财务的账本对上。 进销存台账(存货核算)就是干这件事的。

  • 进 = 采购入库(货进来了)
  • 销 = 销售出库(货卖出去了)
  • 存 = 期末结存(还剩多少)
  • 核算 = 给每一笔货的变动算出金额,而不只是数件数
svg
图1 · 一个货品的旅程:上面动的是「货」,下面动的是「钱」进 = 采购入库 | 销 = 销售出库 | 存 = 期末结存业务世界(货 · 数量)采购下单到货入库 +100件销售出库 −30件结存 70件× 计价单价× 计价单价会计世界(钱 · 金额)(只签合同,不记账)暂估入账 +8,000元结转成本 −2,400元结存 5,600元合同不入账借 库存商品 / 贷 应付-暂估借 主营业务成本 / 贷 库存商品= 台账结存金额进销存台账(存货核算):每一笔「数量变动」× 计价单价 = 「金额变动」,逐笔滚动结存从而随时回答:还剩多少件?值多少钱?和总账对得上吗?——这就是这个功能要干的事

注意:仓库里少 30 件货的同时,账上少了 2,400 元(30 × 80元)——卖货不光是"发货",还得把货的成本从「库存商品」挪到「主营业务成本」,不然利润就算不对。这一步叫结转成本,是存货核算最核心的输出之一。


2. 先背 7 个词(都是一句话的事)

词 大白话
存货 仓库里 + 在途的货,在会计上算公司资产
计价方法 给每件货定一个会计认可的单价(本项目默认"移动加权平均",见 §5)
暂估 货到了票没到,先按采购价估个金额入账,票到了再改准
红字冲销 改账从不删原记录,而是记一笔负数对冲——保住追溯链
收发存 本期收入(收)、本期发出(发)、期末结存(存)——库存的"本月流水账"
勾稽 对账:台账金额 = 财务账本余额 = 数量×单价,三个来源互相对得上
结转成本 卖出货时把货的成本挪进"主营业务成本",用来算利润

3. 现在有啥、还缺啥

现在系统已经能干的:

  • 看每个货还剩多少件(在哪个仓库、哪天进的出的、什么单据)
  • 看大概值多少钱——但这个钱是拿"采购均价"估出来的,不是会计认账的成本
  • 暂估管理是完整的:货到了票没到,先记一笔"欠供应商的钱(估的)",发票到了能自动冲掉改准
  • 采购台账:买了啥、付了多少、还欠多少

还缺的(客户要的"存货核算"缺的就是这些):

缺什么 大白话是什么意思 现在的后果
① 钱的流水账 明细只有"件数",没有每笔的单价、金额、结存(还剩多少钱) 只能回答"还剩多少件",答不了"值多少钱"
② 明确的计价规则 卖出时按什么价算成本,没有正式规则 成本是拍的,不是算的
③ 卖货成本结转 卖了货,要把货的成本从"库存"转到"销售成本",利润才准 现在不转,利润算不对
④ 收发存汇总表 本月一共进了多少、出了多少、剩了多少(要带钱数) 这张点名要的表出不来
⑤ 对账功能 台账的钱数、财务账本的钱数、仓库的件数,三方要能核对 "勾稽校验"按钮是空壳,点了没结果
⑥ 月底结账前检查 暂估还挂着多少没冲?账对上了吗? 没有,结账靠人工肉眼
⑦ 小毛病 导出按钮是坏的;"批量生成凭证"生成的是空白凭证 体验差,容易误以为功能在

一句话总结缺口:现在是"数量流水账",客户要的是"数量+钱数都能查、能对账的账本"。


4. 数据从哪来

记账需要两样东西:多少件 和 一件多少钱。它们来自三个地方:

svg
图2 · 数据从哪来:三类来源,自动流入台账,不需要人手工录仓库的进出记录数量:进了多少件、出了多少件采购单 + 采购发票价格:先按采购价估,发票来了改准能算进货价的费用运费、关税等,按规则摊到货上进销存台账每笔:数量 × 单价 = 金额滚出"还剩多少钱"存货明细账收发存汇总表对账报告注意:"卖出时的成本价"不是售价,是按计价规则(默认:平均成本)从台账里算出来的。

关键点:这些数据业务里本来就有(采购在下单、仓库在收发货、发票在录入),台账只是把它们接过来,配上价格自动记账。人要做的只有一件事:配置"按什么价算"的规则,剩下的自动跑。


5. 数据怎么流转(跟着一笔货走一遍)

svg
图3 · 跟着一笔货走一遍:上面是仓库的件数,下面是账上的钱数仓库(件数)台账(钱数)① 下单② 货到 +100件③ 发票到④ 卖出 −30件⑤ 月底账不动只是约定+8,000元先按采购价"估"改成真价差价自动调成本−2,400元转成销售成本出表对账结账月底出三张表:存货明细账(每笔进出+结存)、收发存汇总(进/出/剩)、对账报告(和财务账本核对)三张表的数全对得上 → 结账,这个月的存货就算清了

按上面 5 步说人话:

  1. 下单:只是约定了价格,货没到、钱没付,账上不动。
  2. 货到仓库:仓库多了 100 件;账上马上要承认"公司多了 8,000 元的货"——但发票没到,先按采购价估着记(这就是"暂估")。
  3. 发票到了:把估的那笔冲掉(不删除,用红字抵消),按发票上的真实价重新记。估少了估多了的差价,自动摊进这批货的成本里。
  4. 卖出 30 件:仓库少了 30 件;账上要把这 30 件的成本(按当时的平均价算,比如 80 元/件 = 2,400 元)从"库存"转到"销售成本"——不做这步利润就是错的。
  5. 月底:系统自动汇总出三张表,并和财务账本核对。全对上,结账;对不上,报告会告诉你差在哪、为什么。

展开:完整业务流程(含"票货不齐"分支)——发票那一步是整套流程的灵魂:

svg
图4 · 完整业务流程:从采购到出报表(含「票货不齐」处理)① 采购下单(约定采购价,此时不记账)② 到货入库 +N 件 → 会计上必须记「存货」③ 发票到了吗?否是④a 货到票未到 → 暂估入库借:库存商品 | 贷:应付账款-暂估金额 = 数量 × 采购单价(先「估」着入账)④b 票已到 → 先红冲暂估(红字),再按发票价正式入账借:库存商品+进项税 | 贷:应付账款⑤ 暂估价 vs 发票价 的价差 → 自动调整存货单价⑥ 销售出库 −M 件(FBA 发货 / 自发货)⑦ 结转成本:借 主营业务成本 | 贷 库存商品出库单价由计价方法算出(本项目默认:移动加权平均)⑧ 期末:台账 ↔ 总账 ↔ 数量账 三方勾稽 → 结账、出报表

三种时序在同一个机制下都成立(这就是"暂估"的价值):

时序 发生什么 账上怎么处理
先货后票(最常见) 入库时发票还没到 ④a 暂估入账 → 票到了走 ④b 红冲+正式入账
先票后货 发票先到、货还在路上 先记"在途",货到了转存货(暂估余额自然为 0)
部分开票 100 件只开了 60 件的票 60 件红冲暂估+正式,40 件继续挂着暂估

移动加权平均(默认的计价规则)用数字看一眼——这也是"存货明细账"的长相:

日期 业务 收入数量 收入金额 发出数量 发出金额 结存数量 结存金额 移动平均单价
04-01 期初         100 件 1,000 元 10.00 元
04-05 采购入库 100 件 +100 1,200 元     200 件 2,200 元 11.00 元
04-10 销售出库 50 件     −50 550 元 150 件 1,650 元 11.00 元
04-15 采购入库 50 件 +50 650 元     200 件 2,300 元 11.50 元
04-20 销售出库 80 件     −80 920 元 120 件 1,380 元 11.50 元

规律就一句:每次进货后平均单价会变(4/5 那笔:2,200 ÷ 200 = 11),出库按"当时的平均价"结转成本。 每行留着当笔单价和结存,谁来审计都能一路追到单据。


6. 月底三张表:分别来自哪里

表 从哪来 是台账出的吗
存货明细账 台账的逐笔记录 ✅ 是,台账原样翻出来
收发存汇总 台账按月汇总 ✅ 是,同一本账的小结
对账报告 台账 + 财务账本 + 仓库的库存数量 三方比对 ⚠️ 台账只是其中一方
svg
图5 · 三张表的出身:前两张来自台账本身,第三张是"三方比对"的产物进销存台账逐笔记:数量 × 单价 = 金额① 存货明细账② 收发存汇总③ 对账报告台账 + 财务账本 + 仓库数量三个数摆一起比,差在哪比喻:台账是日记本 → ①逐页翻、②按月写小结,都从日记本来;③是拿你的小结去和会计的账本、仓库的库存表互相核对


7. 三方勾稽到底怎么核对

核对不在汇总账页面上做(那页只有台账自己的数)。三个数分别在系统的三个地方,「勾稽校验」页负责把它们抄到一起比:

要比的数 在系统的哪 打开哪个页面能看到
① 台账的期末金额、期末数量 进销存台账本身 汇总账页
② 财务账本的余额 财务的账簿("库存商品"等科目还值多少钱) 「财务」→ 科目余额表 / 总账
③ 仓库的件数 仓库的实时库存 「仓库」/「产品」的库存查询
svg
图6 · 三方核对:三个数各在各的页面,「勾稽校验」页负责抄到一起比① 进销存台账期末金额 3,725 元 / 305 件② 财务账本(科目余额表)"库存商品"科目余额 3,725 元③ 仓库库存实际剩余 305 件「勾稽校验」页:自动抄数比对①的金额=②的余额?①的件数=③的件数?结果(✓/⚠ + 差异原因)回写到汇总账的「勾稽」列

具体比的就是两道算术题(外加一道暂估的):

  1. 金额题:台账的期末金额合计 = 财务账本里"库存商品"科目的余额吗?
  2. 数量题:台账的期末数量 = 仓库里实际剩余的件数吗?
  3. 暂估题(顺带):台账里"暂估未开票"的钱数 = 财务账本里"应付账款-暂估"挂账的钱数吗?

都成立 → 打 ✓;有对不上的 → 打 ⚠,点进去看差异原因(盘亏没处理?货到票没到的时点差?漏记?),能解释的解释、记错的调账,全对上才能结账。


8. 汇总账页签的优化设计

系统现有"进销存台账 → 汇总账"页签,栏目已按目标设计好,但数据不全、口径是估的。优化方向是把它做成标准的收发存月报表:

svg
图7 · 优化后的「汇总账」= 收发存月报表(期初 → 收 → 发 → 期末,行行自洽)SKU物料名称仓库会计期间(必选,默认当月)查询重置期末存货金额3,725 元本期收入(收)+2,810 元本期发出(发)−2,735 元其中:暂估未开票600 元SKU物料名称仓库期初本期收入(收)本期发出(发)期末(存)勾稽数量金额数量金额数量金额数量金额平均单价SKU-A数据线华南仓1001,0001501,8501301,4701201,38011.50✓SKU-B充电器华南仓2002,40060960801,0401802,32012.89✓SKU-C保护壳华东仓5025000452255255.00⚠合计3503,6502102,8102552,7353053,725① 会计期间必选(默认当月)——每行必须满足:期初 + 本期收 − 本期发 = 期末(数量、金额都成立)② 点击任意行 → 明细账(该 SKU 本月每一笔进出);勾稽列:✓ = 与财务账本、仓库数量对上;⚠ = 有差异,点开看原因③ "累计入库/出库(年初至今)"收进右侧"更多列";顶部四张卡片给老板一眼看总数

改 6 个地方:① 列结构改成期初→收→发→期末四段式(补"期初"列,行行自洽);② 会计期间变必选;③ 金额为主、单价放期末段;④ 加合计行和顶部数字卡片;⑤ 加勾稽状态列(对账结果透传);⑥ 累计列降级、支持点行下钻明细账。

每列数据分别来自系统哪个功能(数量现成,钱数要靠新能力算):

表上的数 来自系统的哪个功能 状态
SKU、物料名称 产品(产品资料) ✅ 现成
仓库 仓库(仓库档案) ✅ 现成
本期入库数量 采购(收货入库)、仓库(盘点调整、调拨入)、销售退货 ✅ 现成
本期出库数量 发货(销售出库、FBA 发货)、仓库(盘点调整、调拨出) ✅ 现成
期末数量 仓库的库存余额(实时件数) ✅ 现成
期初数量 上个月的期末结转过来 ✅ 规则现成
会计期间 财务(会计期间设置,每月一期) ✅ 现成
入库金额 ⭐ 存货核算(要建):入库按采购价先记(暂估),发票台账的发票到了改成发票价,运费/关税从采购记账分摊进来 🔴 要建
出库金额 ⭐ 存货核算(要建):按当时的平均成本价 × 件数 🔴 要建
期初/期末金额 ⭐ 存货核算(要建):上月期末结转 / 期初+收−发 🔴 要建
移动平均单价 ⭐ 存货核算(要建):期末金额 ÷ 期末数量 🔴 要建
暂估未开票金额 发票台账 / 供应商台账(货到票未到的挂账,已有) 🟡 已有,提上来
勾稽状态 ⭐ 对账(要建):本表 ↔ 财务账本 ↔ 仓库件数 🔴 要建
批量生成凭证 凭证管理(把本月进出生成凭证) 🟡 空壳要修

9. 功能边界:发票、凭证是"借数据",不重做

发票、凭证的记账功能系统已经有了(有专门的方案在完善)。做台账不需要重做它们。它们出现在流程故事里,只因为两件事:

  • 发票管着"单价":金额 = 数量 × 单价。数量仓库有;单价先按采购价估、发票来了改真价。没有发票这步,货值永远是估的。
  • 凭证是对账对象:三方勾稽的"财务账本"就是凭证记出来的。台账要和它对上,就得用同一个价。
svg
图8 · 功能边界:中间是这次要建的,四周都是"拿来用"的现成功能本次要建:进销存台账本体① 给每笔进出配上单价,记成金额② 算出库存货值(期初/收/发/期末)③ 出汇总账、明细账两张表④ 三方勾稽,出对账结果仓库(现成)提供:进了多少、出了多少采购 / 发票台账(现成)提供:采购价、发票真价凭证 / 财务账本(现成)提供:账本余额(对账用)数量价格账本余额一句话:仓库给"多少件"、采购/发票给"一件多少钱"、财务账本给"账上余额"——台账把它们接起来算成货值,再和两边对账。

给开发/客户描述范围,一句话就够:

这个功能 = 算清库存货值(数量来自仓库,单价来自采购价/发票价)+ 三方勾稽。发票和凭证功能是现成的,只用它的数据,不重做它。


10. 验收时看什么(就三件)

  1. 明细账自洽:每行 期初 + 本期收 − 本期发 = 期末,金额、数量、单价都能追到单据;
  2. 卖货成本正确:出库 50 件,账上就少了对应的 550 元成本(而不是拍脑袋);
  3. 三个数对得上:台账结存 = 财务账本"库存商品"余额 = 仓库件数 × 单价,差异有解释。

下篇 · 现状分析与改造方案(技术)

读者:开发 / 实施。所有结论的代码证据见附录 A;与既有两份重构方案的分工见附录 B。
本篇的业务含义都在上篇讲过,这里只讲"现状到底缺什么、怎么补"。

11. 技术目标与能力清单

一句话目标:把"进销存台账 = ERP 数量视图 × 物料均价"升级为财务存货核算账——以计价方法为核心,落财务侧存货成本流水 + 期间结存,输出存货明细账 / 收发存汇总表,与总账、ERP 数量账三方勾稽,并全程挂在凭证池(outbox 事件 → 映射规则 → 凭证)的同一事件源上。

能力清单(验收基准,业务解释见上篇对应章节):

# 能力 上篇对应 说明
R1 存货计价方法管理 §2/§5 按会计主体/存货类别配置:移动加权平均、月末一次加权平均、先进先出、个别计价;变更留痕
R2 存货成本构成核算 §4 入库成本 = 采购价 + 可资本化费用(头程、关税等);费用按规则分摊到 SKU
R3 存货明细账(会计口径) §5/§6 期初/本期收入/本期发出/本期结存,数量×单价×金额三栏齐全,按存货科目+存货项目(SKU,可选仓库)
R4 收发存汇总表 §6/§8 按期间×仓库/存货类别/存货项目的收、发、存数量与金额汇总
R5 发出成本结转 §5 销售出库/FBA 出库按计价方法结转成本(借 主营业务成本 / 贷 库存商品)
R6 暂估与价差处理 §5 票货不齐任意时序;暂估入库、红冲暂估、发票价差自动调整存货成本
R7 存货↔总账勾稽 §7 台账结存金额 = 总账"库存商品/发出商品/在途物资"等科目余额;差异可解释、可追踪
R8 期末处理 §7 结账前检查(暂估余额清单、勾稽差异)、(可选)存货跌价准备计提/转回
R9 全链路追溯 §5 存货变动→业务单据→事件→凭证,任一方向可查(复用凭证池追踪)

R1/R3/R4/R5/R6/R7 是核心闭环;R2/R8/R9 是完整性与合规增强。


12. 现状分析(代码证据级)

12.1 现有进销存台账:一张"跨服务实时视图",不是账

mermaid
100%

关键事实:

  1. 财务侧没有任何存货台账表。FinInventoryLedgerServiceImpl 全部查询经 RemoteERPService Feign 转发 ERP,返回即丢弃,不落库。
  2. 金额口径是"算"出来的:totalAmount = ROUND(SUM(quantity) × m.price_wavg, 2)——金额 = ERP 数量 × 物料表上的移动加权均价(t_erp_material.price_wavg)。该均价由采购付款/收货时在 ERP 侧维护(PurchaseFormPaymentServiceImpl.handleAvgPrice:401,含运费 price_ship_wavg),是业务估算价,不是会计成本账。
  3. 明细账只有数量:getInventoryLedgerDetail 输出数量变动(in/out)、单据号、时间,无单价、无金额、无结存、无凭证号。t_erp_inventory_record 自带数量收发存结构(startinbound/inbound/endinbound 等期初-发生-期末列),但同样只有数量。
  4. 前端页面跑在后端前面:ledger/inventory/index.vue 已按目标口径设计了"本期入库/出库(数量+金额)、累计收发、变动前/后数量金额、发生时单价、凭证号"等列,后端 SQL 根本不返回这些字段——页面上这些列实际为空/零。
  5. 三个功能是空壳:勾稽校验与趋势图 selectCheckResult/selectChartTrend 直接返回空列表(ServiceImpl:103-121);"批量生成凭证"生成一张金额=0、无科目的草稿凭证(ServiceImpl:124-171);前端导出 handleExport 未调 API(index.vue:460)。
  6. 成本计算是死代码:本地 FinInventoryLedgerMapper.xml 预留了完整成本核算 SQL(selectRecordsForCostCalculation / updateInventoryAmount / updateRecordFinance / selectInventoryBalance),但 Mapper 从未被注入任何 Service;且其引用的 current_amount / unit_cost / amount_change / voucher_id 列在 init-config DDL 中并不存在。FinPurchaseLedgerMapper.xml 同为死代码(跨库直查 db_erp.*,口径与线上 Feign SQL 不一致)。

12.2 现有能力矩阵

能力(对照 §11) 前端 后端 状态
汇总账(数量/金额/均价) 有 Feign 实现,金额=数量×price_wavg ⚠️ 弱口径(R3 部分)
本期/累计收发(数量+金额) 列已有 无数据源 ❌ 断层(R4)
明细账(单价/金额/结存/凭证号) 列已有 仅数量变动 ❌ 断层(R3)
勾稽校验 Tab 已有 返回空列表 ❌ 未实现(R7)
金额趋势图 接口已有 返回空列表 ❌ 未实现
批量生成凭证 按钮已有 金额=0 草稿凭证桩 ❌ 桩(与 R5 相关)
导出 按钮已有 前端空壳 ❌ 桩
计价方法配置 — — ❌ 无(R1;MODIFICATION_PLAN.md 仅纸面规划)
成本计算/回写 — Mapper 死代码,列不存在 ❌ 死代码(R1/R5)
暂估跟踪 GR/IR 仅凭证池追踪抽屉可见 ✅ fin_purchase_estimation_tracking 完整(含预付防双记账) ✅(R6 半环)
发票价差处理 — 暂估红冲口径已固化(封顶暂估余额),但价差不调存货成本 ⚠️(R6)
凭证存货数量明细 — fin_voucher_inventory_detail(数量/单价附件) ⚠️ 附件性质,不参与核算(R9)
发出成本结转 — 出库事件(SALE_OUT/FBA_OUT)在凭证重构方案中已定义、未落地 ❌(R5)
期末处理 结账页 closing 无任何存货期末逻辑 ❌(R8)
报表"存货"行 资产负债表 取总账科目公式,不读台账 ✅(但与台账无勾稽)

12.3 存货核算链路现状(凭证侧,作为本方案的上游)

  1. 暂估(GR/IR)是最完整的一块:fin_purchase_estimation_tracking 按 (groupid, po_entry_id) 行级跟踪已入库未开票(applyReceipt/applyReversal/applyInvoice,状态机 0→3),红冲暂估金额"优先取发票匹配固化值、回退暂估单价×开票数、封顶暂估余额"(InvoiceVoucherStrategy:299-326),另有 prepaid_consumed_amount 防预付双记账。但暂估余额与"存货成本"之间没有任何换算关系——台账不知道哪些结存是暂估价入的。
  2. 凭证→存货明细:合并生成凭证时从池行 aux_dimensions 提取 SKU/数量/单价写入 fin_voucher_inventory_detail(FinVoucherPoolServiceImpl.saveInventoryDetails:648-680,单价缺失时 amount÷quantity 反推)——只是分录的"数量单价附件",不参与计价,也不生成成本流水。
  3. 计价方法:财务侧零实现。全库唯一计价逻辑是 ERP 侧 handleAvgPrice(移动加权,付款/收货时点更新 price_wavg);"先进先出"仅出现在亚马逊结算报表(fifo_cost,与存货核算无关);个别计价不存在。
  4. 科目预留但未接线:fin_accounting_subjects.is_inventory_detail_enabled(启用存货明细核算)开关存在于科目表与前端科目管理,但没有任何核算逻辑读它。
  5. 期末:closing 包(结账模板/损益结转/反结账)与 PreClosingCheck 只查损益、未记账凭证、借贷平衡——没有暂估清单、没有存货勾稽、没有跌价/成本差异。
  6. 旧管线:ErpInventoryVoucherStrategy(erpinventory,fin_mapping_erp_inventory 两阶段)已被《ERP库存操作-财务凭证重构方案》裁决下线(裁决⑤);前端 inventoryconfig.vue 成孤儿组件未挂载。存货核算不得再依赖旧管线。

12.4 采购台账现状(对照)

FinPurchaseLedger(/api/v1/purchase/ledger/*)= 采购订单/付款业务视图(Feign → PurchaseFormMapper.getPayRecSumReport:订单额、已付、未付、到货、付款明细/记付款)。它是"采购业务台账",不是"存货核算"的一部分,但其中的付款/收货数据是成本流水的上游事实源之一。本地 FinPurchaseLedgerMapper.xml 亦为死代码,建议随本次改造清理(见 §14 P0-6)。

12.5 与凭证管线重构的关系(关键判断)

《ERP库存操作-财务凭证重构方案》已定稿五层架构:L0 业务 → L1 outbox 事件 → L2 财务归一(含暂估跟踪)→ L3 fin_mapping_rule 映射 → L4 凭证池/凭证。

关键判断:存货核算层应该建在 L2(财务事件)之上,而不是 ERP 数量表之上。
理由:台账与凭证必须同源同口径,否则"库存商品科目余额 vs 台账结存"永远对不上;而 ERP 数量表只是数量事实源,价格事实源(采购价、发票价、费用分摊)全在财务事件里。本方案在其之上插入 L2.5 存货核算层(成本流水 + 期间结存 + 计价引擎),不改动其已裁决的 outbox/映射/凭证池设计。

12.6 差距总表(GAP)

# 要求 现状 差距 等级
G1 R1 计价方法 仅 ERP price_wavg 业务均价,无财务计价配置/引擎 整块缺失 🔴
G2 R3 存货明细账 明细只有数量变动,无单价/金额/结存/期初 整块缺失 🔴
G3 R4 收发存汇总 仅有当前余额汇总;本期/累计收发无数据源 整块缺失 🔴
G4 R5 发出成本结转 出库事件未落地,批量生成凭证是 0 元桩 整块缺失 🔴
G5 R6 暂估价差 暂估红冲已有;发票价差不调整存货成本 半环 🟡
G6 R7 三方勾稽 check 接口返回空列表 整块缺失 🔴
G7 R2 成本构成 头程资本化在事件设计中,无分摊进 SKU 成本 缺失 🟡
G8 R8 期末处理 closing 无存货逻辑 缺失 🟡
G9 R9 追溯 凭证池追踪已有;成本流水↔凭证未建链 半环 🟡
G10 工程质量 台账 Mapper 死代码、DDL 与 SQL 不一致、导出/勾稽空壳、前后端口径断层 技术债 🟠

结论:现状是"业务数量台账 + 半套暂估核算",距离"存货核算管理"缺的是整条成本主线(G1/G2/G3/G4/G6)。 好消息是:暂估(GR/IR)、凭证池、映射规则、追踪链都已就位,成本主线可以顺着事件流补上,不需要推倒重来。


13. 修改方案(目标态)

13.1 总体架构

mermaid
100%

设计原则(与既有裁决一致):

  1. 同源:每笔存货成本流水对应一条已消费的财务事件(event_id 幂等),凭证与台账同批产生,不允许"凭证有了、台账没有";
  2. 红字对冲,不删原事件(既有裁决⑨):退货/撤销/冲销在成本流水中同样以红字(金额取负 + reversed_id 引用)表达;
  3. 数量事实以 ERP 为准,价格/成本事实以财务为准:ERP price_wavg 降级为业务参考价,计价引擎结果是会计权威(P0 双轨并行,见 §15 风险);
  4. 期间封口:成本流水的会计期间判定同既有规则(payload.bizdate → 已关账期间拒绝)。

13.2 数据模型(4 张新表;实施走 DMS 幂等升级 SQL 并回写 init-config DDL)

① fin_inventory_valuation_config —— 计价方法配置(R1)

列 类型 说明
id bigint PK  
groupid bigint 会计主体(fin_accounting_entity.id)
scope_type varchar ALL / STOCK_CATEGORY / MATERIAL
scope_id varchar 存货类别 ID 或物料 ID(ALL 时为空)
method varchar MOVING_WEIGHTED(默认)/ MONTHLY_WEIGHTED / FIFO / SPECIFIC
effective_from char(6) 生效期间(YYYYMM),计价方法切换不回溯历史
is_enabled bit  
created_time / updated_time / operator   留痕

唯一键 (groupid, scope_type, scope_id, effective_from)。缺省行:ALL → MOVING_WEIGHTED(初始化默认规则,幂等)。

② fin_inventory_cost_flow —— 存货成本流水(核心表,R3/R5/R9)

列 类型 说明
id bigint PK  
groupid / period / bizdate   会计主体 / 期间(YYYYMM) / 业务日期
materialid / sku / warehouseid / warehouse_type   核算维度(P0 = SKU+仓库;批次列预留)
subject_id varchar 存货类科目(库存商品/发出商品/FBA在途…,来自映射规则命中行)
direction varchar IN / OUT / ADJUST_IN / ADJUST_OUT
quantity / unit_price / amount decimal 本笔数量/单价/金额(红字为负)
balance_quantity / balance_amount / balance_unit_price decimal 逐笔滚动结存(移动加权);月末加权法下出库行单价暂空、月末回填
source_type varchar PURCHASE_RECEIPT / INVOICE_ESTIMATE_REVERSAL / INVOICE_FORMAL / FEE_ALLOCATE / SHIP_LOGISTICS_FEE / SALE_OUT / FBA_OUT / FBA_INVENTORY / INVENTORY_ADJUST / INVENTORY_TRANSFER / OPENING
source_event_id varchar outbox/pool event_id(幂等键组成部分)
source_doc_no varchar 业务单号(追溯)
voucher_pool_id / voucher_id varchar 成本流水→凭证链(R9)
cost_method varchar 记账时点的计价方法
price_source varchar ESTIMATE(暂估)/ FORMAL(发票)/ WEIGHTED / ALLOCATED(费用分摊)/ FIFO_LAYER
reversed_flag / reversed_id   红字链
created_time    

索引:uk(groupid, source_event_id, source_type, direction, seq)(幂等入账);idx(groupid, materialid, warehouseid, bizdate)(明细账);idx(groupid, period)(期间汇总)。

③ fin_inventory_period_balance —— 期间结存(R4 收发存汇总表、R7 勾稽)

列 类型 说明
groupid / period / materialid / warehouseid / subject_id   维度(warehouseid 可空 = 全仓汇总行)
begin_quantity / begin_amount   期初
in_quantity / in_amount / out_quantity / out_amount   本期收入 / 本期发出(含红字净额)
end_quantity / end_amount / avg_unit_price   期末
close_status tinyint 0 未结 / 1 已结(结账后锁定)
generated_time   生成/重算时间

唯一键 (groupid, period, materialid, warehouseid, subject_id)。每日增量重算 + 期末固化;也是收发存汇总表的直读来源。

④ fin_inventory_reconcile_diff —— 勾稽差异(R7,可 P1 先用报表视图)

groupid / period / diff_scope(LEDGER_VS_GL / LEDGER_VS_ERP) / materialid 或 subject_id / ledger_amount / gl_amount / erp_qty / erp_price / diff_amount / diff_type(时点差|价差|缺失流水|口径差) / status(待查|已解释|已调整) / remark。

FIFO 二期另建 fin_inventory_cost_layer(批次层,复用 fin_voucher_inventory_detail.batchNo 语义),P0 不建。

13.3 计价引擎(R1/R2/R5)

入口:IFinInventoryCostEngine.apply(flow) —— 每笔成本流水入账时调用,产出该笔单价与滚动结存。

方法 算法 期次
MOVING_WEIGHTED(默认) 每次 IN 后:unit_cost = (balance_amount + in_amount) / (balance_quantity + in_quantity);OUT 按当前 unit_cost 结转;红字按原流水反向 P0
MONTHLY_WEIGHTED 平时 OUT 只记数量;月末 unit_cost = (期初金额 + 本月 IN 金额) / (期初数量 + 本月 IN 数量),一次性回填 OUT 行单价并生成结转凭证 P1
FIFO 批次层核销(需 cost_layer 表) P2
SPECIFIC 指定批次/单件成本 P2

入库成本构成(R2):

  • 采购入库:暂估额 = 数量 × 采购单价(itemprice)——与既有 PurchaseEstimateVoucherStrategy 口径完全一致;
  • 票到:INVOICE_ESTIMATE_REVERSAL 红冲暂估流水 → INVOICE_FORMAL 按发票净额蓝字入账,净差即价差,直接进入移动加权 unit_cost(P0 不引入"材料成本差异"科目;如客户要求差异单列,P2 加开关);
  • 费用资本化:SHIP_LOGISTICS_FEE(fee_nature=CAPITALIZABLE) 头程、关税等以 FEE_ALLOCATE 按分摊基数(数量或金额)摊到 SKU,产生 direction=IN, price_source=ALLOCATED 的成本流水(借 库存商品-FBA在途 / 贷 应付账款-货代 的既有分录不变)。

出库结转(R5):SALE_OUT / FBA_OUT 事件驱动 direction=OUT 流水,单价来自计价引擎;对应映射规则分录(借 主营业务成本 / 贷 库存商品)已在默认规则集中(FinMappingRuleServiceImpl:387-418),无需改映射。

13.4 事件 → 成本流水映射(与凭证池同一事务)

event_type 流水方向 单价来源 说明
PURCHASE_RECEIPT(in) IN 蓝 ESTIMATE(amount×itemprice) 入库暂估
PURCHASE_RECEIPT(re/clear/ch 红) IN 红 取负原流水 对齐裁决⑦
INVOICE_ESTIMATE_REVERSAL IN 红 封顶暂估额 红冲暂估
INVOICE_FORMAL IN 蓝 FORMAL(发票净额/数量) 价差并入 unit_cost
FEE_ALLOCATE / SHIP_LOGISTICS_FEE(资本化) IN 费用 ALLOCATED 成本构成
SALE_OUT / FBA_OUT OUT WEIGHTED / FIFO_LAYER 发出结转
FBA_INVENTORY(STOCK_GAIN/DAMAGE/…) ADJUST_IN/OUT 计价单价 盘盈盘亏/调整
INVENTORY_ADJUST(盘点) ADJUST_IN/OUT 计价单价 盘盈盘亏
INVENTORY_TRANSFER(调拨) 仓对仓同价转移 计价单价 不改总成本,只换 warehouseid
OPENING(开账) IN 开账价 期初一次性导入,见 §14

实现落点(对齐既有代码范式):

  • 消费入口:FinOutboxConsumerServiceImpl(ERP 事件)与 FinVoucherPoolServiceImpl.pushPool(财务内部事件)在入池的同一事务内调用新增 IFinInventoryCostService.applyFlow(...);
  • 幂等:与 fin_voucher_pool.event_id 同键(uk(groupid, source_event_id, ...)),重复消费安全;
  • 失败语义:成本流水写失败 → 事件 mark-failed 重试(同 outbox 协议),禁止只出凭证不出台账;
  • 撤销:红字流水 + reversed_id,与既有红字原则一致;
  • 双跑兼容:outbox 未上线前(重构方案 P1 双跑期),成本流水也可由时间窗补扫写入(幂等键防重),保证本方案不被 outbox 进度阻塞。

13.5 台账输出(查询服务,R3/R4/R6/R9)

输出 数据来源 说明
存货明细账 period_balance 期初 + cost_flow 逐笔(含单价/金额/结存)+ 本期合计 + 期末 按 存货科目+SKU(+仓库/期间);每行带 source_doc_no / voucher_id 可跳转
收发存汇总表 fin_inventory_period_balance 直读 按 期间×仓库/存货类别/科目 汇总;支持导出
存货成本台账(现"汇总账"升级) period_balance 当期 + 结存 补齐前端已有列:本期收发数量金额、累计收发、移动平均单价、结存金额(布局见上篇 §8)
暂估余额清单 fin_purchase_estimation_tracking(已有) 补查询 API 与页面;列示 暂估额/已开票/预付冲减/账龄
发出成本结转明细 cost_flow(OUT) 对应主营业务成本明细(按期间/仓库/店铺)
勾稽报告 §13.6 差异清单 + 分类 + 处理状态

13.6 三方勾稽(R7/R8)

结账前(及每日批跑)校验,写 fin_inventory_reconcile_diff(P1 前先报表视图):

对账 公式 差异分类(对齐既有 §7 思路)
A 存货成本账 vs B 总账 Σ period_balance.end_amount(按科目分组)= 总账该科目期末余额 时点差(票货不齐/跨期)、价差、缺失流水、口径差(汇率/仓别/状态)
A 存货成本账 vs C ERP 数量账 Σ cost_flow.end_quantity = t_erp_inventory.quantity(fulfillable 等口径对齐) 数量差异=漏事件/双记;金额差异=计价双轨漂移
暂估勾稽 fin_purchase_estimation_tracking.estimated_amount = Σ 暂估类流水余额 = 总账"应付账款-暂估"余额 时点差正常,列清单
  • PreClosingCheckService 增加存货勾稽门槛(按会计主体配置:仅警告 / 阻断结账);
  • 差异处理走"可解释"流程:选差异 → 归类 → 填说明或生成调整流水/调整凭证。

13.7 REST API 契约(草案,沿用 /api/finance/… 与 Result/TableDataInfo 范式)

纯文本
# 计价配置

GET    /api/finance/inventory/valuation/list?groupid=

POST   /api/finance/inventory/valuation            (新增/修改,生效期间+方法)

DELETE /api/finance/inventory/valuation/{ids}



# 存货核算台账

GET    /api/finance/inventory/cost/detail?groupid=&period=&materialId=&warehouseId=&subjectId=   → 存货明细账(分页,含期初/结存)

GET    /api/finance/inventory/cost/summary?groupid=&period=&dimension=warehouse|category|subject → 收发存汇总

GET    /api/finance/inventory/cost/balance?groupid=&period=                                     → 期末结存快照

GET    /api/finance/inventory/cost/outbound?groupid=&period=                                    → 发出成本结转明细



# 暂估与勾稽

GET    /api/finance/inventory/estimation/list?groupid=&poNo=&status=                            → 暂估余额清单

GET    /api/finance/inventory/reconcile?groupid=&period=                                        → 三方勾稽报告

POST   /api/finance/inventory/reconcile/explain   {diffId, diffType, remark}                    → 差异归档

POST   /api/finance/inventory/cost/recalc         {groupid, period, materialId?}                → 期间重算(幂等)

旧 /api/v1/inventory/ledger/* 六个端点保留并升级数据源(明细/汇总改读 cost_flow/period_balance;check/chart 真实现;voucher 端点改为"从成本流水生成凭证池行"或下线,见 P0-6)。采购台账 /api/v1/purchase/ledger/* 不动。

13.8 前端改造(wimoor-ui)

页面 改动
进销存台账 ledger/inventory/index.vue 三个 Tab 对接真实数据:汇总账改四段式收发存(上篇 §8 布局);明细账补单价/金额/结存/凭证号列;勾稽 Tab 对接勾稽报告;修复 handleExport 真导出
计价方法配置(新,config/valuation) 按 会计主体×存货类别 配置方法+生效期间;变更历史
收发存汇总表(新,可并入台账 Tab4) 期间×维度收发存,导出
暂估余额清单(新) PO 行级暂估进度(数据已存在于追踪抽屉,提为独立页)
勾稽对账(新或并入台账 Tab3) 三方差异列表、分类、解释操作
存货成本调整单(P1,可选) 盘点/调整录入 → INVENTORY_ADJUST 事件
孤儿组件处置 inventoryconfig.vue 随旧管线下线(既有裁决⑤);MODIFICATION_PLAN.md 中"存货核算"章节以本方案为准修订

14. 实施路线

P0 —— 落表 + 计价 + 台账主循环(约 4 周)

  1. 幂等升级 SQL:fin_inventory_valuation_config / fin_inventory_cost_flow / fin_inventory_period_balance(+reconcile 视图),同步回写 init-config DDL;
  2. 计价引擎(MOVING_WEIGHTED)+ 默认配置初始化;
  3. 成本流水接线:PURCHASE_RECEIPT / INVOICE_ESTIMATE_REVERSAL / INVOICE_FORMAL 三事件(暂估口径既有,改写成本流水);SALE_OUT/FBA_OUT 若出库事件未上线,先以 ERP 出库记录时间窗补扫双跑(幂等键防重);
  4. 期初开账:指定切换期间 P0,OPENING 流水一次性导入(期初数量取 t_erp_inventory,期初单价取 price_wavg),与总账库存类科目余额核对出开账差异表,人工确认;
  5. 台账输出:存货明细账 / 收发存汇总 / 成本台账升级 + 勾稽校验(A vs B、A vs C)真实现;
  6. 工程清理:删除或接线两个死 Mapper(建议删除);batchGenerateVoucher 0 元桩修正为"从所选成本流水生成凭证池行"或下线按钮;导出修复;前端三 Tab 补数据 + 计价配置页。

验收:采购入库→(票到价差)→出库结转全链金额可查明细账;每行期初+收发=期末自洽;勾稽差异可解释;老页面无回归。

P1 —— 事件全面化 + 价差 + 资本化 + 勾稽闭环(约 3 周)

  1. 与 outbox P1/P2 咬合:re/ch/clear 红字、FBA_INVENTORY、盘点、调拨全部事件化入成本流水;
  2. 价差自动化(任意票货时序)、费用资本化分摊(头程/关税 → FEE_ALLOCATE);
  3. 暂估余额清单页 + 三方勾稽报告页 + PreClosingCheck 存货门槛;fin_inventory_reconcile_diff 落表;
  4. MONTHLY_WEIGHTED(月末一次加权)计价选项。

验收:暂估余额 = 台账暂估挂账 = 总账暂估科目;三方勾稽报表上线且结账受控。

P2 —— 计价扩展 + 减值 + 双轨收敛(约 2 周+)

  1. FIFO(fin_inventory_cost_layer 批次层)/ 个别计价;
  2. 存货跌价准备计提/转回(成本 vs 可变现净值,科目已有预留);
  3. 差异自动分类规则化;ERP price_wavg 与财务计价双轨收敛(财务结果回写或 ERP 只留数量);
  4. 期后事项:存货周转/库龄分析(复用现有 ERP 周转报告 + 成本金额)。

每阶段交付物(沿用项目惯例):DMS 幂等升级 SQL + Java/Mapper + 编译验证 + 灰度与回滚说明。


15. 风险与开放问题

风险 影响 对策
计价双轨漂移(ERP price_wavg vs 财务引擎) 业务报表与财务台账金额不一致 P0 双轨 + 差异报表;对外口径声明"财务为会计权威";P2 收敛
期初开账不准 后续所有结存失真 开账差异表人工确认;开账流水可整体重算;保留切换期间前后双跑对比
与 outbox 重构排期耦合 事件未上线导致成本流水断供 消费接口兼容"时间窗补扫"双跑(幂等键防重),不阻塞 P0
逐笔滚动结存性能 大 SKU 量下明细账/重算慢 按 (material, warehouse) 分区;期间重算批处理;period_balance 快照兜底
红字/冲销复杂口径 退货换货成本错乱 统一红字对冲不删原事件(既有裁决⑨),成本流水同规;换货拆红+蓝两条
死代码/空壳误导实施 误把 Mapper XML 当已实现 P0-6 明确删除/接线,代码注释标注口径来源

开放问题(需客户/产品裁决):

  1. 核算维度粒度:P0 建议 SKU+仓库,FIFO 再引批次——是否接受?
  2. 在途/发出商品(FBA_IN_TRANSIT、发出商品)是否纳入同一台账按仓型/科目分列?建议纳入。
  3. 存货跌价准备是否本期必须?(建议 P2 可选)
  4. 发票价差直接调存货成本 vs 走"材料成本差异"科目?建议 P0 直接调成本,P2 加开关。
  5. is_inventory_detail_enabled 科目开关的语义:建议=该科目启用成本流水核算(挂 cost_flow),未启用的科目仅走总账——是否符合客户预期?
  6. 期初切换期间选哪个月(建议取最近一个未结账期间的月初)?

附录 A:现状证据索引

结论 证据
台账为 Feign 实时视图、无财务落表 wimoor-finance/.../ledger/service/impl/FinInventoryLedgerServiceImpl.java:39-98(RemoteERPService 转发)
金额口径=数量×price_wavg wimoor-erp/erp-boot/.../mapper/finance/FinAccountMapper.xml:50-80(getInventoryLedgerSummary)
price_wavg 维护时机 wimoor-erp/.../purchase/service/impl/PurchaseFormPaymentServiceImpl.java:401(handleAvgPrice,付款:363/收货 PurchaseFormReceiveServiceImpl:589 调用)
明细无金额 FinAccountMapper.xml:110-135(getInventoryLedgerDetail 仅 quantity/status/operate)
check/chart 空壳 FinInventoryLedgerServiceImpl.java:103-121(return new ArrayList<>())
批量生成凭证=0 元桩 FinInventoryLedgerServiceImpl.java:124-171(totalAmount=ZERO、借方金额 0、无科目)
成本 Mapper 死代码 FinInventoryLedgerMapper.java:107-151 声明 updateInventoryAmount/updateRecordFinance/selectRecordsForCostCalculation/selectInventoryBalance,全库无调用方;FinInventoryLedgerMapper.xml:174-223 引用的 current_amount/unit_cost/amount_change/voucher_id 在 init-config/.../table-t_erp_inventory(_record).sql 中不存在
采购台账死代码 FinPurchaseLedgerMapper.xml(跨库 db_erp 直查)未注入任何 Service
暂估跟踪完整 init-config/.../table-fin_purchase_estimation_tracking.sql、20261027_fin_write_off_alignment.sql(prepaid_consumed_amount)、FinPurchaseEstimationTrackingMapper.xml:95-145、InvoiceVoucherStrategy.java:299-326
凭证存货明细 table-fin_voucher_inventory_detail.sql、FinVoucherPoolServiceImpl.saveInventoryDetails:648-680
计价仅 ERP 移动加权 全库关键词检索:FIFO 仅 wimoor-amazon AmzFinSettlementFormulaServiceImpl(结算报表);跌价/成本差异仅科目初始化 FinInitAccountingSubjectsData.xml:102 与报表公式
closing 无存货期末 wimoor-finance/.../closing/** 关键词检索仅 ProfitLossTemplateStrategy.java:338 一处
前端口径断层 wimoor-ui/src/views/finance/ledger/inventory/index.vue:46,111,178,460,488-497(列设计 vs 后端字段);api/finance/inventoryLedger.js:4-31
存货核算开关闲置 fin_accounting_subjects.is_inventory_detail_enabled(table-fin_accounting_subjects.sql:33)、前端 subjects/index.vue:266-268
旧管线已裁决下线 《ERP库存操作-财务凭证重构方案.md》裁决⑤;inventoryconfig.vue 未挂载 config/index.vue
菜单现状 init-config/mysql/database_data/db_admin/t_sys_menu.sql:236-267(进销存台账→/fin/ledger/inventory:261)

附录 B:与既有两份方案的边界

文档 负责 本方案不重复
ERP库存操作-财务凭证重构方案 outbox 事件层、映射事件模型、红字表达、org 归一、对账闭环框架 事件 DDL/协议/裁决全部沿用
AI实施任务书-采购付款入库凭证新架构 凭证池合并、fin_mapping_rule、辅助核算、暂估跟踪表 表结构与规则引擎沿用
本方案 存货成本流水/期间结存/计价引擎/收发存/勾稽/期末 —— 唯一新增层为 L2.5 存货核算层