7.6 KiB
7.6 KiB
嘉恒仓库库级出入库流水设计
背景
嘉恒仓库已经承载原材料库、半成品库、成品库、辅料库、废料库、退货库六类库存。当前页面支持点击某个物料查看该物料的批次台账和库存流水，但缺少“站在某一个仓库整体视角查看所有出入库流水”的入口。
本设计在仓库页新增库级流水入口。入口跟随当前选中的仓库 tab，用于查看当前仓库下所有物料、批次和业务单据产生的出入库流水。
目标
- 在嘉恒仓库页面的出入库操作区右侧新增一个“流水”图标按钮，位置对应用户截图红框区域。
- 当前选中哪个仓库 tab，点击按钮就查看该仓库的出入库流水。
- 六大仓库都支持库级流水：原材料库、半成品库、成品库、辅料库、废料库、退货库。
- 流水数据来自统一库存流水表
wh_inventory_txn，不新增另一套流水记录体系。 - 库级流水和现有物料级“库存流水”并存，形成“仓库总览 -> 物料明细 -> 批次追溯”的层级。
非目标
- 本次不新增复杂趋势图、库存金额图表或 BI 看板。
- 本次不替代物料详情抽屉中的批次台账和物料流水。
- 本次不改变现有出入库业务的入账逻辑。
- 本次不新增导出功能；可在后续版本增加“导出当前筛选流水”。
页面入口
在嘉恒仓库页面的出入库操作区右侧新增一个图标按钮。
按钮要求：
- 图标使用符合当前 Ruoyi 风格的“流水/列表/票据”类图标。
- 鼠标悬停显示提示：
查看当前仓库出入库流水。 - 按钮文本可显示为
流水，避免只有图标导致用户不理解。 - 按钮始终跟随当前选中仓库 tab，不在每个仓库 tab 内重复放置。
示例：
仓库 tab：原材料库 / 半成品库 / 成品库 / 辅料库 / 废料库 / 退货库
出入库操作区：
入库 [+ 期初入库] [+ 客料入库] ...
出库 [- 生产出库] [- 委外出库] ...
[流水]
抽屉交互
点击“流水”按钮后，从右侧弹出大抽屉。
抽屉标题格式：
{当前仓库名} · 出入库流水
例如：
原材料库 · 出入库流水
成品库 · 出入库流水
退货库 · 出入库流水
抽屉内容分为三块：
- 顶部汇总卡片
- 筛选区
- 流水明细表
抽屉滚动遵循全局抽屉规则：鼠标滚动只控制抽屉，不滚动底层主页面；抽屉必须完整显示在屏幕可视范围内。
顶部汇总
汇总数据按当前仓库和当前筛选条件计算。
建议展示：
- 入库笔数
- 出库笔数
- 入库重量(kg)
- 出库重量(kg)
- 最近一笔流水时间
数量口径：
- 原材料库、辅料库、废料库以重量为主，数量不作为核心汇总。
- 半成品库、成品库、退货库同时展示数量和重量。
如果汇总接口暂不单独返回，可前端基于当前分页结果做轻量展示，但最终推荐由后端返回全量筛选条件下的汇总，避免分页导致汇总不完整。
筛选与排序
筛选区保留系统全局业务列表筛选规则：
- 搜索框支持任意文字模糊搜索。
- 搜索范围包括物料编码、物料名称、批次号、流水类型、来源单据、运单号、备注。
- 重要业务字段支持排序，字段名旁显示上下箭头。
筛选项：
- 日期范围：按
biz_time过滤。 - 出入库方向：全部、入库、出库、调整。
- 业务类型：采购入库、销售出库、退货入库、返工出库等。
- 物料：可选当前仓库内出现过的物料。
- 批次号：支持输入模糊匹配。
排序字段：
- 流水时间
- 业务类型
- 物料编码
- 批次号
- 变动重量
- 变动数量
- 金额
默认排序：
流水时间倒序，最新流水在最上方。
流水表字段
通用字段：
- 流水时间
- 方向
- 业务类型
- 物料编码 / 物料名称
- 批次号
- 变动数量
- 变动重量(kg)
- 单价
- 金额
- 来源单据
- 经办人
- 运单号 / 订单照片
- 备注
不同仓库展示口径：
- 原材料库：隐藏或置空数量列，突出重量。
- 辅料库：隐藏或置空数量列，突出重量。
- 废料库：隐藏或置空数量列，突出重量和金额。
- 半成品库：展示数量和重量。
- 成品库：展示数量和重量。
- 退货库：展示数量和重量，并突出发货批次、退货单、返工出库来源。
方向判断：
weight_change_kg > 0或qty_change > 0为入库。weight_change_kg < 0或qty_change < 0为出库。- 盘库造成的正负调整显示为调整，也保留原始正负数。
数据接口
新增后端分页接口：
GET /inventory/transaction-ledger
参数：
warehouse_type: 必填，枚举RAW | SEMI | FINISHED | AUX | SCRAP | RETURNwarehouse_id: 可选，指定具体仓库 IDkeyword: 可选，模糊搜索direction: 可选，IN | OUT | ADJUST | ALLtxn_type: 可选，业务类型item_id: 可选，物料 IDlot_no: 可选，批次号模糊搜索start_date: 可选end_date: 可选page: 默认 1page_size: 默认 10sort_key: 默认biz_timesort_direction: 默认desc
返回：
{
"items": [],
"total": 0,
"summary": {
"in_count": 0,
"out_count": 0,
"adjust_count": 0,
"in_qty": 0,
"out_qty": 0,
"in_weight_kg": 0,
"out_weight_kg": 0,
"latest_biz_time": null
}
}
接口内部使用 wh_inventory_txn 作为主表，关联：
md_itemwh_warehousewh_locationwh_stock_lot- 操作人表，如果当前流水已有
operator_user_id
与现有功能关系
库级流水：
- 入口位于出入库操作区。
- 查询当前仓库所有物料和批次的流水。
- 用于回答“这个仓库最近发生了哪些出入库”。
物料级流水：
- 入口是点击库存列表中的某个物料。
- 查询该物料在当前仓库下的流水。
- 用于回答“这个物料为什么变成当前库存”。
批次台账：
- 入口同样是点击库存列表中的物料。
- 查询该物料下面每个批次的现存状态。
- 用于回答“当前还剩哪些批次，批次来源是什么”。
三者保留并互补，不互相替代。
错误与空状态
- 当前仓库没有流水时显示空状态：
暂无{仓库名}出入库流水。 - 接口失败时使用右上角全局提示，几秒后自动收回，鼠标悬停时保持不收。
- 筛选结果为空时显示：
没有符合条件的流水。 - 如果仓库正在盘库锁库，流水仍可查看，但出入库动作不可操作。
测试方案
后端测试：
- 按仓库类型过滤只返回对应仓库流水。
- 方向过滤能区分入库、出库、调整。
- 关键词搜索覆盖物料、批次、来源、备注。
- 分页返回
items、total和summary。 - 原材料库流水数量口径保持重量优先，不恢复原材料数量概念。
前端静态测试：
- 嘉恒仓库页面存在“流水”入口。
- 六大仓库 tab 都可打开同一流水抽屉。
- 请求使用
/inventory/transaction-ledger。 - 旧物料级库存流水仍保留。
前端构建：
npm run build通过。
浏览器冒烟：
- 登录后进入嘉恒仓库。
- 切换任意仓库 tab。
- 点击“流水”按钮。
- 抽屉标题和当前仓库一致。
- 搜索、日期筛选、分页能正常工作。
后续可选增强
- 增加“导出当前筛选流水”。
- 增加流水趋势图。
- 增加来源单据点击跳转。
- 增加按业务类型聚合的迷你统计。