存货核算管理 · 进销存台账 —— 需求解读与改造方案(合并版 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. 这个功能到底是干啥的?
一句话:老板问"仓库里的货值多少钱",系统要能用会计认可的方式回答,并且这个数能和财务的账本对上。 进销存台账(存货核算)就是干这件事的。
- 进 = 采购入库(货进来了)
- 销 = 销售出库(货卖出去了)
- 存 = 期末结存(还剩多少)
- 核算 = 给每一笔货的变动算出金额,而不只是数件数
注意:仓库里少 30 件货的同时,账上少了 2,400 元(30 × 80元)——卖货不光是"发货",还得把货的成本从「库存商品」挪到「主营业务成本」,不然利润就算不对。这一步叫结转成本,是存货核算最核心的输出之一。
2. 先背 7 个词(都是一句话的事)
| 词 | 大白话 |
|---|---|
| 存货 | 仓库里 + 在途的货,在会计上算公司资产 |
| 计价方法 | 给每件货定一个会计认可的单价(本项目默认"移动加权平均",见 §5) |
| 暂估 | 货到了票没到,先按采购价估个金额入账,票到了再改准 |
| 红字冲销 | 改账从不删原记录,而是记一笔负数对冲——保住追溯链 |
| 收发存 | 本期收入(收)、本期发出(发)、期末结存(存)——库存的"本月流水账" |
| 勾稽 | 对账:台账金额 = 财务账本余额 = 数量×单价,三个来源互相对得上 |
| 结转成本 | 卖出货时把货的成本挪进"主营业务成本",用来算利润 |
3. 现在有啥、还缺啥
现在系统已经能干的:
- 看每个货还剩多少件(在哪个仓库、哪天进的出的、什么单据)
- 看大概值多少钱——但这个钱是拿"采购均价"估出来的,不是会计认账的成本
- 暂估管理是完整的:货到了票没到,先记一笔"欠供应商的钱(估的)",发票到了能自动冲掉改准
- 采购台账:买了啥、付了多少、还欠多少
还缺的(客户要的"存货核算"缺的就是这些):
| 缺什么 | 大白话是什么意思 | 现在的后果 |
|---|---|---|
| ① 钱的流水账 | 明细只有"件数",没有每笔的单价、金额、结存(还剩多少钱) | 只能回答"还剩多少件",答不了"值多少钱" |
| ② 明确的计价规则 | 卖出时按什么价算成本,没有正式规则 | 成本是拍的,不是算的 |
| ③ 卖货成本结转 | 卖了货,要把货的成本从"库存"转到"销售成本",利润才准 | 现在不转,利润算不对 |
| ④ 收发存汇总表 | 本月一共进了多少、出了多少、剩了多少(要带钱数) | 这张点名要的表出不来 |
| ⑤ 对账功能 | 台账的钱数、财务账本的钱数、仓库的件数,三方要能核对 | "勾稽校验"按钮是空壳,点了没结果 |
| ⑥ 月底结账前检查 | 暂估还挂着多少没冲?账对上了吗? | 没有,结账靠人工肉眼 |
| ⑦ 小毛病 | 导出按钮是坏的;"批量生成凭证"生成的是空白凭证 | 体验差,容易误以为功能在 |
一句话总结缺口:现在是"数量流水账",客户要的是"数量+钱数都能查、能对账的账本"。
4. 数据从哪来
记账需要两样东西:多少件 和 一件多少钱。它们来自三个地方:
关键点:这些数据业务里本来就有(采购在下单、仓库在收发货、发票在录入),台账只是把它们接过来,配上价格自动记账。人要做的只有一件事:配置"按什么价算"的规则,剩下的自动跑。
5. 数据怎么流转(跟着一笔货走一遍)
按上面 5 步说人话:
- 下单:只是约定了价格,货没到、钱没付,账上不动。
- 货到仓库:仓库多了 100 件;账上马上要承认"公司多了 8,000 元的货"——但发票没到,先按采购价估着记(这就是"暂估")。
- 发票到了:把估的那笔冲掉(不删除,用红字抵消),按发票上的真实价重新记。估少了估多了的差价,自动摊进这批货的成本里。
- 卖出 30 件:仓库少了 30 件;账上要把这 30 件的成本(按当时的平均价算,比如 80 元/件 = 2,400 元)从"库存"转到"销售成本"——不做这步利润就是错的。
- 月底:系统自动汇总出三张表,并和财务账本核对。全对上,结账;对不上,报告会告诉你差在哪、为什么。
展开:完整业务流程(含"票货不齐"分支)——发票那一步是整套流程的灵魂:
三种时序在同一个机制下都成立(这就是"暂估"的价值):
| 时序 | 发生什么 | 账上怎么处理 |
|---|---|---|
| 先货后票(最常见) | 入库时发票还没到 | ④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. 月底三张表:分别来自哪里
| 表 | 从哪来 | 是台账出的吗 |
|---|---|---|
| 存货明细账 | 台账的逐笔记录 | ✅ 是,台账原样翻出来 |
| 收发存汇总 | 台账按月汇总 | ✅ 是,同一本账的小结 |
| 对账报告 | 台账 + 财务账本 + 仓库的库存数量 三方比对 | ⚠️ 台账只是其中一方 |
7. 三方勾稽到底怎么核对
核对不在汇总账页面上做(那页只有台账自己的数)。三个数分别在系统的三个地方,「勾稽校验」页负责把它们抄到一起比:
| 要比的数 | 在系统的哪 | 打开哪个页面能看到 |
|---|---|---|
| ① 台账的期末金额、期末数量 | 进销存台账本身 | 汇总账页 |
| ② 财务账本的余额 | 财务的账簿("库存商品"等科目还值多少钱) | 「财务」→ 科目余额表 / 总账 |
| ③ 仓库的件数 | 仓库的实时库存 | 「仓库」/「产品」的库存查询 |
具体比的就是两道算术题(外加一道暂估的):
- 金额题:台账的期末金额合计 = 财务账本里"库存商品"科目的余额吗?
- 数量题:台账的期末数量 = 仓库里实际剩余的件数吗?
- 暂估题(顺带):台账里"暂估未开票"的钱数 = 财务账本里"应付账款-暂估"挂账的钱数吗?
都成立 → 打 ✓;有对不上的 → 打 ⚠,点进去看差异原因(盘亏没处理?货到票没到的时点差?漏记?),能解释的解释、记错的调账,全对上才能结账。
8. 汇总账页签的优化设计
系统现有"进销存台账 → 汇总账"页签,栏目已按目标设计好,但数据不全、口径是估的。优化方向是把它做成标准的收发存月报表:
改 6 个地方:① 列结构改成期初→收→发→期末四段式(补"期初"列,行行自洽);② 会计期间变必选;③ 金额为主、单价放期末段;④ 加合计行和顶部数字卡片;⑤ 加勾稽状态列(对账结果透传);⑥ 累计列降级、支持点行下钻明细账。
每列数据分别来自系统哪个功能(数量现成,钱数要靠新能力算):
| 表上的数 | 来自系统的哪个功能 | 状态 |
|---|---|---|
| SKU、物料名称 | 产品(产品资料) | ✅ 现成 |
| 仓库 | 仓库(仓库档案) | ✅ 现成 |
| 本期入库数量 | 采购(收货入库)、仓库(盘点调整、调拨入)、销售退货 | ✅ 现成 |
| 本期出库数量 | 发货(销售出库、FBA 发货)、仓库(盘点调整、调拨出) | ✅ 现成 |
| 期末数量 | 仓库的库存余额(实时件数) | ✅ 现成 |
| 期初数量 | 上个月的期末结转过来 | ✅ 规则现成 |
| 会计期间 | 财务(会计期间设置,每月一期) | ✅ 现成 |
| 入库金额 | ⭐ 存货核算(要建):入库按采购价先记(暂估),发票台账的发票到了改成发票价,运费/关税从采购记账分摊进来 | 🔴 要建 |
| 出库金额 | ⭐ 存货核算(要建):按当时的平均成本价 × 件数 | 🔴 要建 |
| 期初/期末金额 | ⭐ 存货核算(要建):上月期末结转 / 期初+收−发 | 🔴 要建 |
| 移动平均单价 | ⭐ 存货核算(要建):期末金额 ÷ 期末数量 | 🔴 要建 |
| 暂估未开票金额 | 发票台账 / 供应商台账(货到票未到的挂账,已有) | 🟡 已有,提上来 |
| 勾稽状态 | ⭐ 对账(要建):本表 ↔ 财务账本 ↔ 仓库件数 | 🔴 要建 |
| 批量生成凭证 | 凭证管理(把本月进出生成凭证) | 🟡 空壳要修 |
9. 功能边界:发票、凭证是"借数据",不重做
发票、凭证的记账功能系统已经有了(有专门的方案在完善)。做台账不需要重做它们。它们出现在流程故事里,只因为两件事:
- 发票管着"单价":金额 = 数量 × 单价。数量仓库有;单价先按采购价估、发票来了改真价。没有发票这步,货值永远是估的。
- 凭证是对账对象:三方勾稽的"财务账本"就是凭证记出来的。台账要和它对上,就得用同一个价。
给开发/客户描述范围,一句话就够:
这个功能 = 算清库存货值(数量来自仓库,单价来自采购价/发票价)+ 三方勾稽。发票和凭证功能是现成的,只用它的数据,不重做它。
10. 验收时看什么(就三件)
- 明细账自洽:每行 期初 + 本期收 − 本期发 = 期末,金额、数量、单价都能追到单据;
- 卖货成本正确:出库 50 件,账上就少了对应的 550 元成本(而不是拍脑袋);
- 三个数对得上:台账结存 = 财务账本"库存商品"余额 = 仓库件数 × 单价,差异有解释。
下篇 · 现状分析与改造方案(技术)
读者:开发 / 实施。所有结论的代码证据见附录 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 现有进销存台账:一张"跨服务实时视图",不是账
关键事实:
- 财务侧没有任何存货台账表。
FinInventoryLedgerServiceImpl全部查询经RemoteERPServiceFeign 转发 ERP,返回即丢弃,不落库。 - 金额口径是"算"出来的:
totalAmount = ROUND(SUM(quantity) × m.price_wavg, 2)——金额 = ERP 数量 × 物料表上的移动加权均价(t_erp_material.price_wavg)。该均价由采购付款/收货时在 ERP 侧维护(PurchaseFormPaymentServiceImpl.handleAvgPrice:401,含运费price_ship_wavg),是业务估算价,不是会计成本账。 - 明细账只有数量:
getInventoryLedgerDetail输出数量变动(in/out)、单据号、时间,无单价、无金额、无结存、无凭证号。t_erp_inventory_record自带数量收发存结构(startinbound/inbound/endinbound 等期初-发生-期末列),但同样只有数量。 - 前端页面跑在后端前面:
ledger/inventory/index.vue已按目标口径设计了"本期入库/出库(数量+金额)、累计收发、变动前/后数量金额、发生时单价、凭证号"等列,后端 SQL 根本不返回这些字段——页面上这些列实际为空/零。 - 三个功能是空壳:勾稽校验与趋势图
selectCheckResult/selectChartTrend直接返回空列表(ServiceImpl:103-121);"批量生成凭证"生成一张金额=0、无科目的草稿凭证(ServiceImpl:124-171);前端导出handleExport未调 API(index.vue:460)。 - 成本计算是死代码:本地
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 存货核算链路现状(凭证侧,作为本方案的上游)
- 暂估(GR/IR)是最完整的一块:
fin_purchase_estimation_tracking按(groupid, po_entry_id)行级跟踪已入库未开票(applyReceipt/applyReversal/applyInvoice,状态机 0→3),红冲暂估金额"优先取发票匹配固化值、回退暂估单价×开票数、封顶暂估余额"(InvoiceVoucherStrategy:299-326),另有prepaid_consumed_amount防预付双记账。但暂估余额与"存货成本"之间没有任何换算关系——台账不知道哪些结存是暂估价入的。 - 凭证→存货明细:合并生成凭证时从池行
aux_dimensions提取 SKU/数量/单价写入fin_voucher_inventory_detail(FinVoucherPoolServiceImpl.saveInventoryDetails:648-680,单价缺失时 amount÷quantity 反推)——只是分录的"数量单价附件",不参与计价,也不生成成本流水。 - 计价方法:财务侧零实现。全库唯一计价逻辑是 ERP 侧
handleAvgPrice(移动加权,付款/收货时点更新price_wavg);"先进先出"仅出现在亚马逊结算报表(fifo_cost,与存货核算无关);个别计价不存在。 - 科目预留但未接线:
fin_accounting_subjects.is_inventory_detail_enabled(启用存货明细核算)开关存在于科目表与前端科目管理,但没有任何核算逻辑读它。 - 期末:closing 包(结账模板/损益结转/反结账)与 PreClosingCheck 只查损益、未记账凭证、借贷平衡——没有暂估清单、没有存货勾稽、没有跌价/成本差异。
- 旧管线:
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 总体架构
设计原则(与既有裁决一致):
- 同源:每笔存货成本流水对应一条已消费的财务事件(event_id 幂等),凭证与台账同批产生,不允许"凭证有了、台账没有";
- 红字对冲,不删原事件(既有裁决⑨):退货/撤销/冲销在成本流水中同样以红字(金额取负 + reversed_id 引用)表达;
- 数量事实以 ERP 为准,价格/成本事实以财务为准:ERP price_wavg 降级为业务参考价,计价引擎结果是会计权威(P0 双轨并行,见 §15 风险);
- 期间封口:成本流水的会计期间判定同既有规则(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 周)
- 幂等升级 SQL:
fin_inventory_valuation_config / fin_inventory_cost_flow / fin_inventory_period_balance(+reconcile 视图),同步回写 init-config DDL; - 计价引擎(MOVING_WEIGHTED)+ 默认配置初始化;
- 成本流水接线:PURCHASE_RECEIPT / INVOICE_ESTIMATE_REVERSAL / INVOICE_FORMAL 三事件(暂估口径既有,改写成本流水);SALE_OUT/FBA_OUT 若出库事件未上线,先以 ERP 出库记录时间窗补扫双跑(幂等键防重);
- 期初开账:指定切换期间 P0,
OPENING流水一次性导入(期初数量取 t_erp_inventory,期初单价取 price_wavg),与总账库存类科目余额核对出开账差异表,人工确认; - 台账输出:存货明细账 / 收发存汇总 / 成本台账升级 + 勾稽校验(A vs B、A vs C)真实现;
- 工程清理:删除或接线两个死 Mapper(建议删除);
batchGenerateVoucher0 元桩修正为"从所选成本流水生成凭证池行"或下线按钮;导出修复;前端三 Tab 补数据 + 计价配置页。
验收:采购入库→(票到价差)→出库结转全链金额可查明细账;每行期初+收发=期末自洽;勾稽差异可解释;老页面无回归。
P1 —— 事件全面化 + 价差 + 资本化 + 勾稽闭环(约 3 周)
- 与 outbox P1/P2 咬合:re/ch/clear 红字、FBA_INVENTORY、盘点、调拨全部事件化入成本流水;
- 价差自动化(任意票货时序)、费用资本化分摊(头程/关税 → FEE_ALLOCATE);
- 暂估余额清单页 + 三方勾稽报告页 + PreClosingCheck 存货门槛;fin_inventory_reconcile_diff 落表;
- MONTHLY_WEIGHTED(月末一次加权)计价选项。
验收:暂估余额 = 台账暂估挂账 = 总账暂估科目;三方勾稽报表上线且结账受控。
P2 —— 计价扩展 + 减值 + 双轨收敛(约 2 周+)
- FIFO(fin_inventory_cost_layer 批次层)/ 个别计价;
- 存货跌价准备计提/转回(成本 vs 可变现净值,科目已有预留);
- 差异自动分类规则化;ERP price_wavg 与财务计价双轨收敛(财务结果回写或 ERP 只留数量);
- 期后事项:存货周转/库龄分析(复用现有 ERP 周转报告 + 成本金额)。
每阶段交付物(沿用项目惯例):DMS 幂等升级 SQL + Java/Mapper + 编译验证 + 灰度与回滚说明。
15. 风险与开放问题
| 风险 | 影响 | 对策 |
|---|---|---|
| 计价双轨漂移(ERP price_wavg vs 财务引擎) | 业务报表与财务台账金额不一致 | P0 双轨 + 差异报表;对外口径声明"财务为会计权威";P2 收敛 |
| 期初开账不准 | 后续所有结存失真 | 开账差异表人工确认;开账流水可整体重算;保留切换期间前后双跑对比 |
| 与 outbox 重构排期耦合 | 事件未上线导致成本流水断供 | 消费接口兼容"时间窗补扫"双跑(幂等键防重),不阻塞 P0 |
| 逐笔滚动结存性能 | 大 SKU 量下明细账/重算慢 | 按 (material, warehouse) 分区;期间重算批处理;period_balance 快照兜底 |
| 红字/冲销复杂口径 | 退货换货成本错乱 | 统一红字对冲不删原事件(既有裁决⑨),成本流水同规;换货拆红+蓝两条 |
| 死代码/空壳误导实施 | 误把 Mapper XML 当已实现 | P0-6 明确删除/接线,代码注释标注口径来源 |
开放问题(需客户/产品裁决):
- 核算维度粒度:P0 建议 SKU+仓库,FIFO 再引批次——是否接受?
- 在途/发出商品(FBA_IN_TRANSIT、发出商品)是否纳入同一台账按仓型/科目分列?建议纳入。
- 存货跌价准备是否本期必须?(建议 P2 可选)
- 发票价差直接调存货成本 vs 走"材料成本差异"科目?建议 P0 直接调成本,P2 加开关。
is_inventory_detail_enabled科目开关的语义:建议=该科目启用成本流水核算(挂 cost_flow),未启用的科目仅走总账——是否符合客户预期?- 期初切换期间选哪个月(建议取最近一个未结账期间的月初)?
附录 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 存货核算层 |