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