440 lines
12 KiB
Markdown
440 lines
12 KiB
Markdown
# 嘉恒仓库全出入库单据纸质化与归档设计
|
||
|
||
## 背景
|
||
|
||
嘉恒仓库已经有 6 大库：原材料库、半成品库、成品库、辅料库、废料库、退货库。当前出入库业务主要通过抽屉表单完成，保存后形成库存流水。用户已经认可 `原材料库 · 客料入库` 的纸质填单样板，但该样板目前只完成填写 UI，没有生成 PDF 归档，也没有预览和下载入口。
|
||
|
||
现有归档体系已覆盖销售订单、采购订单、到货入库单、质量校验单、生产领料出库单、生产入库结算单。仓库里大量非生产分支仍未纳入正式单据化：客料、委外、销售、退货、返工、特殊出入库、期初等。为避免后续继续碎片化，本方案把“所有仓库出入库填单纸质化、保存后 PDF 归档、流水入口预览下载、流水 Excel 导出”作为统一仓库单据化工程。
|
||
|
||
## 目标
|
||
|
||
1. 6 大库所有入库、出库填单页面改造成正式纸质化单据风格。
|
||
2. 每次出入库保存后生成 PDF 归档，业务保存成功但 PDF 失败不回滚业务。
|
||
3. 保存成功提示区提供 `预览PDF`、`下载PDF` 快捷入口。
|
||
4. 各库流水抽屉中每条流水展示 `单据留档`，支持预览、下载、重新生成。
|
||
5. 物料/库存批次明细中的库存流水也能看到对应 PDF 留档入口。
|
||
6. `生产台账入库` 这类一次生成多个仓库流水的动作，使用一张 `生产入库结算单`，多条流水共用同一归档。
|
||
7. 各库流水模块支持按当前筛选条件，尤其是时间范围，导出 Excel 清单。
|
||
8. PDF 和 Excel 中不使用前端省略号逻辑，长字段完整换行或完整输出。
|
||
|
||
## 范围
|
||
|
||
### 覆盖仓库
|
||
|
||
- 原材料库
|
||
- 半成品库
|
||
- 成品库
|
||
- 辅料库
|
||
- 废料库
|
||
- 退货库
|
||
|
||
### 覆盖入口
|
||
|
||
原材料库：
|
||
|
||
- 期初入库
|
||
- 客料入库
|
||
- 生产余料入库
|
||
- 委外余料入库
|
||
- 特殊入库
|
||
- 生产出库
|
||
- 委外出库
|
||
- 退货出库
|
||
- 报废出库
|
||
- 特殊出库
|
||
|
||
半成品库：
|
||
|
||
- 产中入库
|
||
- 期初入库
|
||
- 委外入库
|
||
- 特殊入库
|
||
- 产中出库
|
||
- 委外出库
|
||
- 特殊出库
|
||
|
||
成品库：
|
||
|
||
- 生产入库
|
||
- 返工入库
|
||
- 委外入库
|
||
- 期初入库
|
||
- 特殊入库
|
||
- 销售出库
|
||
- 特殊出库
|
||
|
||
辅料库：
|
||
|
||
- 期初入库
|
||
- 特殊入库
|
||
- 生产出库
|
||
- 特殊出库
|
||
|
||
废料库：
|
||
|
||
- 生产废料入库
|
||
- 返工废料入库
|
||
- 期初入库
|
||
- 委外废料入库
|
||
- 退货废料入库
|
||
- 特殊入库
|
||
- 售卖出库
|
||
- 特殊出库
|
||
|
||
退货库：
|
||
|
||
- 期初入库
|
||
- 退货入库
|
||
- 特殊入库
|
||
- 返工出库
|
||
- 特殊出库
|
||
|
||
跨库工具：
|
||
|
||
- 生产台账入库
|
||
|
||
## 单据归档类型
|
||
|
||
### 生产专用单据
|
||
|
||
保持现有设计：
|
||
|
||
- `生产领料出库单`
|
||
- `生产入库结算单`
|
||
|
||
这些单据用于生产主链路，不再重复映射到通用仓库作业单，避免一笔生产业务出现两套 PDF。
|
||
|
||
### 通用仓库作业单
|
||
|
||
新增通用归档类型：
|
||
|
||
- `仓库出入库单`
|
||
|
||
该类型覆盖除生产专用单据外的所有仓库出入库按钮。PDF 标题根据仓库和业务类型动态生成，例如：
|
||
|
||
- `客料入库单`
|
||
- `委外余料入库单`
|
||
- `委外出库单`
|
||
- `销售出库单`
|
||
- `退货入库单`
|
||
- `返工出库单`
|
||
- `特殊入库单`
|
||
- `售卖出库单`
|
||
|
||
通用类型的好处是后端只需一个归档收集器和一个路由 key，所有仓库业务通过配置映射生成不同标题与字段。
|
||
|
||
## 归档业务主键
|
||
|
||
### 单条库存流水动作
|
||
|
||
以本次业务动作形成的主 `wh_inventory_txn.id` 作为 `business_id`。
|
||
|
||
适用：
|
||
|
||
- 客料入库
|
||
- 委外出库
|
||
- 报废出库
|
||
- 售卖出库
|
||
- 期初入库
|
||
- 大多数普通入库/出库
|
||
|
||
### 多条库存流水动作
|
||
|
||
以主库存流水 ID 作为 `business_id`，同一动作产生的其它库存流水通过 `document_batch_no` 或关联表映射到同一归档。
|
||
|
||
适用：
|
||
|
||
- `生产台账入库`：使用现有 `生产入库结算单`，主流水优先级为成品入库、余料入库、废料入库。
|
||
- 后续若某个普通仓库动作一次形成多条流水，也沿用同样主流水规则。
|
||
|
||
### 特殊出入库
|
||
|
||
特殊出入库要保留“必须填写说明”的业务约束。若特殊调整有主表，则优先以特殊调整主表 ID 作为归档业务主键；若当前实现只有库存流水，则以本次特殊调整的主库存流水 ID 作为归档业务主键。PDF 必须完整展示调整说明和每条明细的调整前后数量/重量。
|
||
|
||
### 已有关联业务单据
|
||
|
||
如果某个仓库动作本质已经有更上游单据：
|
||
|
||
- 采购到货入库保留 `到货入库单`
|
||
- 销售订单保留 `销售订单`
|
||
- 生产主链路保留生产专用单据
|
||
|
||
但仓库内实际发生出库/入库时，仍应能从仓库流水看到该次仓库作业的留档。如果该仓库动作已有专用归档，则流水指向专用归档；否则指向 `仓库出入库单`。
|
||
|
||
## 纸质填单 UI 规则
|
||
|
||
### 通用结构
|
||
|
||
所有仓库出入库抽屉采用统一纸质单据底座：
|
||
|
||
- 抬头：嘉恒仓库、单据标题、单据编号或提交后生成提示。
|
||
- 基础信息区：仓库、库位、业务类型、来源/去向、经办人、时间。
|
||
- 明细区：物料/产品/半成品/废料/退货品、库存批次号、来源库存批次号、数量、重量、单价、金额。
|
||
- 辅助信息区：运单号、运费、辅助照片、用途、包装备注、退货/返工/委外方、说明。
|
||
- 备注区：用户备注和系统生成说明。
|
||
- 签核区：制单、仓库确认、业务确认、复核。
|
||
- 底部固定操作区：保存按钮、保存中状态。
|
||
|
||
### 业务字段不删减
|
||
|
||
纸质化只是表现层升级，不改变原有业务字段和校验。已有字段必须保留，只调整布局、标题、分区和视觉样式。此前用户明确要求去掉的字段除外。
|
||
|
||
### 保存后反馈
|
||
|
||
保存成功后显示：
|
||
|
||
- 业务保存结果
|
||
- PDF 归档状态
|
||
- `预览PDF`
|
||
- `下载PDF`
|
||
|
||
如果 PDF 失败：
|
||
|
||
- 显示 `PDF归档失败`
|
||
- 显示中文失败原因
|
||
- 提供 `重新生成`
|
||
- 不回滚库存流水
|
||
|
||
## PDF 内容规则
|
||
|
||
PDF 是业务快照，以保存后的数据库事实为准，不从前端表单重新计算。
|
||
|
||
PDF 必须包含：
|
||
|
||
- 单据标题
|
||
- 单据编号
|
||
- 业务时间
|
||
- 仓库和库位
|
||
- 业务类型
|
||
- 经办人
|
||
- 物料/产品/半成品/废料/退货品信息
|
||
- 库存批次号
|
||
- 来源库存批次号
|
||
- 数量/重量
|
||
- 单价/金额
|
||
- 运单号、运费、辅助照片链接或照片存在标记
|
||
- 业务说明和备注
|
||
- 关联采购单、销售单、生产台账、发货批次、退货处置等追溯信息
|
||
|
||
PDF 不得出现：
|
||
|
||
- 英文状态值
|
||
- 前端省略号
|
||
- 超出单元格的长文本
|
||
- 无业务意义的每库内部批次号
|
||
|
||
## 流水预览与下载入口
|
||
|
||
### 各库流水抽屉
|
||
|
||
在 `嘉恒仓库 -> 工具 -> 流水` 中新增 `单据留档` 列。
|
||
|
||
每条流水根据后端返回的归档字段展示：
|
||
|
||
- `未生成`
|
||
- `已归档`
|
||
- `归档失败`
|
||
- `预览PDF`
|
||
- `下载PDF`
|
||
- `重新生成`
|
||
|
||
### 库存明细右侧流水
|
||
|
||
物料/批次详情抽屉中的库存流水也新增 `单据留档`，行为与仓库流水一致。
|
||
|
||
### 生产台账入库
|
||
|
||
`生产台账入库` 保存后若一次生成成品、余料、废料多条流水，这几条流水的 `单据留档` 指向同一张 `生产入库结算单`。
|
||
|
||
## 流水 Excel 导出
|
||
|
||
### 入口位置
|
||
|
||
在各库流水抽屉顶部筛选区增加 `导出Excel` 按钮，放在 `查询` 按钮旁边。
|
||
|
||
### 导出范围
|
||
|
||
导出使用当前流水筛选条件：
|
||
|
||
- 当前仓库类型
|
||
- 当前仓库 ID
|
||
- 关键词
|
||
- 流水方向
|
||
- 流水类型
|
||
- 物料
|
||
- 库存批次号
|
||
- 开始日期
|
||
- 结束日期
|
||
- 排序字段
|
||
- 排序方向
|
||
|
||
如果用户没有选择时间范围，允许导出当前筛选条件下所有流水，但前端需要轻提示“当前未选择时间范围，将导出全部匹配流水”。第一版不强制时间范围，避免阻塞真实查账场景。
|
||
|
||
### Excel 字段
|
||
|
||
导出的 Excel 至少包含：
|
||
|
||
- 业务时间
|
||
- 仓库
|
||
- 库位
|
||
- 方向
|
||
- 流水类型
|
||
- 物料/产品编码
|
||
- 物料/产品名称
|
||
- 库存批次号
|
||
- 来源库存批次号
|
||
- 数量变化
|
||
- 重量变化
|
||
- 单价
|
||
- 金额
|
||
- 来源单据
|
||
- 经办人
|
||
- 运单号
|
||
- 运费
|
||
- 辅助照片
|
||
- 备注
|
||
- PDF归档状态
|
||
- PDF归档业务ID
|
||
|
||
Excel 需使用中文表头，冻结表头，自动筛选，合理列宽。
|
||
|
||
## 后端设计
|
||
|
||
### 归档服务
|
||
|
||
在 `document_archives.py` 中新增：
|
||
|
||
- `DOCUMENT_TYPE_WAREHOUSE_OPERATION = "仓库出入库单"`
|
||
- `collect_warehouse_operation_archive_context`
|
||
|
||
通用收集器根据主库存流水读取：
|
||
|
||
- 主库存流水
|
||
- 相关库存流水
|
||
- 库存批次
|
||
- 来源库存批次
|
||
- 仓库和库位
|
||
- 关联采购/销售/退货/发货/生产台账信息
|
||
- 物流字段
|
||
- 特殊调整说明
|
||
|
||
### 路由
|
||
|
||
`/document-archives/{document_type_key}/{business_id}/...` 增加：
|
||
|
||
- `warehouse-operation`
|
||
|
||
### 仓库保存接口
|
||
|
||
所有普通仓库出入库保存成功后：
|
||
|
||
1. 完成库存业务事务。
|
||
2. 提交业务数据。
|
||
3. 生成 PDF 归档。
|
||
4. 返回归档状态。
|
||
|
||
生产专用动作保持现有生产归档类型。
|
||
|
||
### 流水接口
|
||
|
||
`GET /inventory/transaction-ledger` 返回每行归档字段：
|
||
|
||
- `archive_status`
|
||
- `archive_business_id`
|
||
- `archive_document_type`
|
||
- `archive_error_message`
|
||
|
||
### Excel 导出接口
|
||
|
||
新增：
|
||
|
||
- `GET /inventory/transaction-ledger/export`
|
||
|
||
该接口接收与流水查询一致的筛选参数，返回 `.xlsx` 文件。
|
||
|
||
## 前端设计
|
||
|
||
### 单据化表单
|
||
|
||
抽出通用仓库纸质表单组件：
|
||
|
||
- `WarehouseDocumentFormShell`
|
||
- `WarehouseDocumentGrid`
|
||
- `WarehouseDocumentActionBar`
|
||
- `WarehouseArchiveShortcut`
|
||
|
||
`原材料库 · 客料入库` 样板迁移到通用组件上，其它表单逐步替换。
|
||
|
||
### PDF 操作组件
|
||
|
||
复用现有 `DocumentArchiveActions`，不再做第二套预览/下载按钮。
|
||
|
||
### Excel 导出
|
||
|
||
仓库流水抽屉筛选区新增 `导出Excel`。
|
||
|
||
导出时：
|
||
|
||
- 按钮显示 `导出中...`
|
||
- 禁止重复点击
|
||
- 使用 `downloadResource`
|
||
- 文件名格式：`{仓库名}出入库流水_{开始日期或全部}_{结束日期或全部}.xlsx`
|
||
|
||
## 实施分期
|
||
|
||
### Phase 1：底座和入口
|
||
|
||
- 新增通用 `仓库出入库单` 归档类型。
|
||
- 仓库流水接口返回归档字段。
|
||
- 仓库流水新增预览/下载/重新生成。
|
||
- 流水 Excel 导出。
|
||
- 客料入库补齐 PDF 归档。
|
||
|
||
### Phase 2：通用表单纸质化
|
||
|
||
- 期初入库
|
||
- 客料入库
|
||
- 委外余料入库
|
||
- 委外出库
|
||
- 报废出库
|
||
- 售卖出库
|
||
- 辅料生产出库
|
||
- 半成品产中/委外入出库
|
||
|
||
### Phase 3：专用业务表单纸质化
|
||
|
||
- 销售出库
|
||
- 退货入库
|
||
- 退货废料入库
|
||
- 返工出库
|
||
- 返工入库
|
||
- 返工废料入库
|
||
- 特殊出入库
|
||
|
||
### Phase 4：生产主链路统一入口
|
||
|
||
- 生产出库、生产台账入库、生产入库、生产余料入库、生产废料入库沿用生产专用 PDF。
|
||
- 仓库流水和生产台账详情统一指向同一份归档。
|
||
|
||
## 验收标准
|
||
|
||
1. 所有仓库出入库入口打开后都是纸质化单据风格。
|
||
2. 客料入库保存后能生成 `仓库出入库单` PDF，并可预览和下载。
|
||
3. 任意仓库流水行能看到归档状态；已归档可预览和下载。
|
||
4. `生产台账入库` 一次产生多条流水时，多条流水打开同一张 `生产入库结算单`。
|
||
5. PDF 失败不影响库存保存，页面显示失败并允许重新生成。
|
||
6. 各库流水可按时间范围导出 Excel。
|
||
7. Excel 内容符合当前筛选范围，中文表头完整，数值和备注不丢失。
|
||
8. PDF 和 Excel 均不出现英文状态值或截断省略号。
|
||
|
||
## 设计结论
|
||
|
||
全仓库单据化采用“通用仓库作业单 + 生产专用单据”的双轨方案：
|
||
|
||
- 普通仓库出入库统一归档为 `仓库出入库单`。
|
||
- 生产领料和生产入库结算继续使用生产专用单据。
|
||
- 所有单据都通过仓库流水、库存明细流水、保存成功反馈提供预览和下载入口。
|
||
- 各库流水导出 Excel 与当前筛选条件保持一致。
|
||
|
||
该方案能覆盖 6 大库所有出入库入口，又避免为每个按钮单独造一套 PDF 逻辑。
|