汤学会 e90d296047 chore: customize branding for Baihua

2026-06-14 21:05:49 +08:00

12 KiB

Raw Blame History

百华仓库全出入库单据纸质化与归档设计

背景

百华仓库已经有 6 大库：原材料库、半成品库、成品库、辅料库、废料库、退货库。当前出入库业务主要通过抽屉表单完成，保存后形成库存流水。用户已经认可 原材料库 · 客料入库 的纸质填单样板，但该样板目前只完成填写 UI，没有生成 PDF 归档，也没有预览和下载入口。

现有归档体系已覆盖销售订单、采购订单、到货入库单、质量校验单、生产领料出库单、生产入库结算单。仓库里大量非生产分支仍未纳入正式单据化：客料、委外、销售、退货、返工、特殊出入库、期初等。为避免后续继续碎片化，本方案把“所有仓库出入库填单纸质化、保存后 PDF 归档、流水入口预览下载、流水 Excel 导出”作为统一仓库单据化工程。

目标

6 大库所有入库、出库填单页面改造成正式纸质化单据风格。
每次出入库保存后生成 PDF 归档，业务保存成功但 PDF 失败不回滚业务。
保存成功提示区提供 预览PDF、下载PDF 快捷入口。
各库流水抽屉中每条流水展示 单据留档，支持预览、下载、重新生成。
物料/库存批次明细中的库存流水也能看到对应 PDF 留档入口。
生产台账入库 这类一次生成多个仓库流水的动作，使用一张 生产入库结算单，多条流水共用同一归档。
各库流水模块支持按当前筛选条件，尤其是时间范围，导出 Excel 清单。
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

仓库保存接口

所有普通仓库出入库保存成功后：

完成库存业务事务。
提交业务数据。
生成 PDF 归档。
返回归档状态。

生产专用动作保持现有生产归档类型。

流水接口

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。
仓库流水和生产台账详情统一指向同一份归档。

验收标准

所有仓库出入库入口打开后都是纸质化单据风格。
客料入库保存后能生成 仓库出入库单 PDF，并可预览和下载。
任意仓库流水行能看到归档状态；已归档可预览和下载。
生产台账入库 一次产生多条流水时，多条流水打开同一张 生产入库结算单。
PDF 失败不影响库存保存，页面显示失败并允许重新生成。
各库流水可按时间范围导出 Excel。
Excel 内容符合当前筛选范围，中文表头完整，数值和备注不丢失。
PDF 和 Excel 均不出现英文状态值或截断省略号。

设计结论

全仓库单据化采用“通用仓库作业单 + 生产专用单据”的双轨方案：

普通仓库出入库统一归档为 仓库出入库单。
生产领料和生产入库结算继续使用生产专用单据。
所有单据都通过仓库流水、库存明细流水、保存成功反馈提供预览和下载入口。
各库流水导出 Excel 与当前筛选条件保持一致。

该方案能覆盖 6 大库所有出入库入口，又避免为每个按钮单独造一套 PDF 逻辑。

12 KiB Raw Blame History Unescape Escape