# 全系统纸质单据统一改造设计

## 背景

系统已经开始从普通后台表单向正式业务单据升级：销售订单、采购订单已经接入 `DocumentPaper` 纸质单据和 PDF 归档；仓库中的 `原材料库 · 客料入库单` 已被用户认可为“模板级别”；`生产余料入库单 / 生产废料入库单` 第一阶段也已经开始改成同一套纸质单据语言。

用户明确补充：这不是仓库专属改造，而是全系统所有“单据型业务”都要采用统一纸质单据体系。为了避免仓库、采购、销售、生产各自长出不同样式，本设计把目标升级为“全系统业务单据纸质化 + PDF 归档统一体系”。

## 单据边界

### 纳入纸质化的对象

满足任一条件就纳入：

- 会创建正式业务凭证：销售订单、采购订单、到货入库单、质量校验单、发货单、退货/返工单。
- 会改变库存或形成库存流水：各库入库、出库、特殊调整、盘库。
- 会形成生产追溯闭环：生产出库、生产台账入库、生产入库结算、生产领料出库。
- 用户后续需要预览、下载、批量下载或审计留档。

### 不纳入纸质化的对象

这些仍按系统管理/主数据维护表单处理，不强行改成纸质单据：

- 供应商名录、客户名录、人员管理、设备管理。
- 原材料名录、产品管理、产品需规清单、BOM、工艺路线。
- 系统权限、系统拓展、导入工具、基础配置。

原因：这些是主数据或配置记录，不是业务凭证。强行纸质化会降低维护效率，也会把“单据”的正式感稀释掉。

## 现状清单

### 已基本纸质化且已有 PDF 归档

| 模块 | 页面 | 单据 | 前端状态 | 后端归档类型 | 备注 |
| --- | --- | --- | --- | --- | --- |
| 订单与计划 | `SalesPlanningView.vue` | 销售订单 | 使用 `DocumentPaper`、`DocumentLineTable`、`DocumentArchiveActions` | `销售订单` | 已有预览、下载、重新生成、批量下载 |
| 采购与库存 | `PurchaseOrderView.vue` | 采购订单 | 使用 `DocumentPaper`、`DocumentArchiveActions` | `采购订单` | 已有预览、下载、重新生成、批量下载 |
| 采购与库存 | `PurchaseReceiptView.vue` | 到货入库单 | 使用 `DocumentPaper`、`DocumentArchiveActions` | `到货入库单` | 新增到货入库已纸质化 |
| 采购与库存 | `QualityInspectionView.vue` | 质量校验单 | 使用 `DocumentPaper`、`DocumentLineTable`、`DocumentArchiveActions` | `质量校验单` | 质检放行弹窗仍需继续统一交互 |
| 生产执行 | `ProductionLedgerView.vue` | 生产领料出库单 | 列表详情有 `DocumentArchiveActions` | `生产领料出库单` | 主要是归档入口，填单发生在仓库生产出库 |
| 生产执行 | `ProductionLedgerView.vue` | 生产入库结算单 | 列表详情有 `DocumentArchiveActions` | `生产入库结算单` | 对应生产台账入库 |

### 已套纸质外壳但仍有混用 UI

| 模块 | 页面 | 单据 | 当前问题 | 优先级 |
| --- | --- | --- | --- | --- |
| 嘉恒仓库 | `InventoryLedgerView.vue` | 特殊入库单 / 特殊出库单 | 明细编辑区仍像现代卡片控件，和纸质单据割裂 | P0 |
| 嘉恒仓库 | `InventoryLedgerView.vue` | 生产出库单 | 已使用纸质外壳，但来源批次选择、产品/BOM信息仍需统一纸质表格语言 | P0 |
| 嘉恒仓库 | `InventoryLedgerView.vue` | 生产台账入库结算单 | 已有纸质外壳和摘要格，但三库联动字段、异常说明区域仍需与纸质单据模板对齐 | P0 |
| 嘉恒仓库 | `InventoryLedgerView.vue` | 生产入库单 / 返工入库单 | 结单区和摘要区仍有旧卡片感 | P1 |
| 嘉恒仓库 | `InventoryLedgerView.vue` | 销售出库单 | 已套纸质外壳，但销售订单关联、包装备注、发货明细区域需统一 | P1 |
| 嘉恒仓库 | `InventoryLedgerView.vue` | 原材料退货出库单、退货入库单、退货废料入库单、返工出库单 | 已套纸质外壳，但字段区仍有普通表单/表格痕迹 | P1 |
| 嘉恒仓库 | `InventoryLedgerView.vue` | 期初入库、委外入库/出库、报废出库、售卖出库等通用分支 | 通用分支第一阶段只统一了生产余料/废料一部分，仍需逐个验收 | P1 |

### 需要补充纸质化或确认是否作为单据

| 模块 | 页面 | 业务 | 判断 | 优先级 |
| --- | --- | --- | --- | --- |
| 发货概览 | `DeliveryManagementView.vue` | 发货台账/发货明细 | 如果存在独立发货动作，应形成发货单；若发货统一走成品库销售出库，则只保留流水归档入口 | P1 |
| 发货概览 | `ReturnManagementView.vue` | 退货/返工/废料处置 | 属于业务凭证，需要与退货库单据闭环统一 | P1 |
| 发货概览 | `ScrapReworkView.vue` | 报废返工处理 | 若仍在使用，应按退货/返工处置单统一；若已被仓库/退货库替代，应清理或降级为台账 | P2 |
| 生产执行 | `CompletionReceiptView.vue` | 成品入库 | 旧入口如果仍可用，需要和仓库生产入库/生产台账入库统一；如果已被新流程替代，应标记为旧入口 | P2 |
| 嘉恒仓库 | `StocktakeDialog.vue` | 盘库单 | 盘库会改库存，应纳入纸质盘库单和 PDF 归档，但可排在特殊出入库之后 | P2 |

## 推荐方案

### 方案 A：继续逐页局部改造

每个页面自己套 `DocumentPaper` 和单独 CSS。

优点：

- 单次改动小。
- 速度快。

缺点：

- 很容易再次出现“仓库一套、采购一套、销售一套”。
- 样式复制越来越多。
- 后续 PDF、预览、下载、异常说明、签核栏会重复实现。

结论：不推荐作为长期方案，只适合救急。

### 方案 B：沉淀全系统单据底座，分批迁移

把现在的 `DocumentPaper`、`DocumentGrid`、`DocumentLineTable`、`WarehouseDocumentFormShell` 抽象成全系统单据组件。仓库继续推进，但所有新样式都进入通用单据层。

优点：

- 风格统一。
- 后续新增单据成本低。
- 能保留现有业务逻辑，不需要一次性大重构。
- 适合当前系统已经上线、仍在快速迭代的状态。

缺点：

- 第一批需要先做组件抽象和兼容层。
- 每个单据仍要逐个检查字段和业务交互。

结论：推荐。

### 方案 C：一次性全系统重构

一次把所有单据型页面、归档、PDF 重新设计和重写。

优点：

- 最终一致性最高。

缺点：

- 风险大。
- 容易影响已经可用的采购、销售、仓库主流程。
- 验收压力大。

结论：当前不推荐。

## 目标架构

### 前端组件层

保留现有组件并向通用命名演进：

- `DocumentPaper`：纸张、标题、编号章、签核栏、留存联。
- `DocumentGrid`：只读/展示型字段格。
- `DocumentLineTable`：明细表。
- `DocumentArchiveActions`：预览、下载、重新生成。

新增或演进：

- `DocumentFormShell`：全系统通用填单外壳，替代仓库专属 `WarehouseDocumentFormShell`。
- `DocumentSection`：通用单据分区，替代仓库专属 `WarehouseDocumentSection`。
- `DocumentActionBar`：通用底部操作区，替代仓库专属 `WarehouseDocumentActionBar`。
- `DocumentField`：纸质输入格，承载 input、select、textarea、readonly。
- `DocumentSelectorPanel`：纸质风格的下拉、多选、来源批次选择、关联订单选择。
- `DocumentInlineSummary`：纸质风格的金额/数量/重量汇总条。
- `DocumentSettlePanel`：结单、异常说明、偏差确认等正式确认区。

兼容规则：

- 第一阶段不删除 `WarehouseDocument*` 组件。
- 新通用组件先复用当前纸质 CSS 变量和视觉语言。
- 仓库页面逐步从 `warehouse-paper-*` 类迁移到 `document-paper-*` 类。
- 老类名保留一段时间作为兼容，避免正在使用的仓库单据被打断。

### 前端页面层

每个单据页面遵循同一结构：

1. `DocumentFormShell`
2. 单据头：标题、单据编号、业务日期、公司/模块名。
3. 基础信息区：客户/供应商/仓库/经办人/业务日期/关联单据。
4. 明细区：物料/产品/批次/数量/重量/单价/金额。
5. 辅助信息区：照片、运单号、运费、包装备注、用途、说明。
6. 汇总区：数量、重量、金额、差异、异常说明。
7. 签核区：制单、经办、审核、仓库/财务。
8. 操作区：保存、保存并归档、归档状态动作。

### 后端归档层

继续使用现有 `document_archives` 表和统一路由：

- `POST /document-archives/{document_type_key}/{business_id}/generate`
- `GET /document-archives/{document_type_key}/{business_id}/latest/preview`
- `GET /document-archives/{document_type_key}/{business_id}/latest/download`
- `POST /document-archives/batch-download`

现有支持的归档类型：

- `销售订单`
- `采购订单`
- `到货入库单`
- `质量校验单`
- `生产领料出库单`
- `生产入库结算单`
- `仓库出入库单`

新增归档类型只在确实不是现有类型能表达时添加。优先复用：

- 普通仓库动作统一走 `仓库出入库单`。
- 生产出库走 `生产领料出库单`。
- 生产台账入库走 `生产入库结算单`。
- 采购流程走 `采购订单 / 到货入库单 / 质量校验单`。
- 销售下单走 `销售订单`。

### PDF 规则

PDF 是保存后的数据库事实快照，不从前端表单二次推导。

PDF 必须遵守：

- 不显示英文状态。
- 不显示前端省略号。
- 长文本完整换行，不超格。
- 制单、经办人默认使用当前登录账号或后端记录的操作人。
- 库存批次号使用业务认可的原材料库存批次号，不使用无业务意义的每库内部批次号。
- PDF 样式和前端纸质单据属于同一视觉体系，但不要求像素完全一致。

## 分期执行

### 第 0 期：全系统清单和统一底座

目标：

- 固化本文档的单据清单。
- 新增通用 `DocumentFormShell / DocumentSection / DocumentActionBar / DocumentField / DocumentSelectorPanel`。
- 把仓库当前纸质样式抽象为通用 `document-paper-*`，保留 `warehouse-paper-*` 兼容层。

验收：

- 销售订单、采购订单、客料入库单视觉不退化。
- 新通用组件有基础测试或源码断言。

### 第 1 期：仓库 P0 单据

目标：

- 特殊入库 / 特殊出库。
- 生产出库。
- 生产台账入库结算单。

原因：

- 这些单据业务风险最高，且当前混用 UI 最明显。
- 改完能沉淀“多行明细类单据”“生产闭环类单据”“异常说明类单据”三类模板。

验收：

- 不再出现普通卡片/普通表格突兀嵌在纸里。
- 特殊出入库说明、明细行、调整前后数据完整显示。
- 生产台账入库三库联动显示为一张结算单，不误写成只属于成品库。

### 第 2 期：仓库 P1 单据

目标：

- 生产入库 / 返工入库。
- 销售出库。
- 原材料退货出库、退货入库、退货废料入库、返工出库。
- 期初、委外、报废、售卖等通用分支。

验收：

- 6 大库所有出入库抽屉都统一纸质化。
- 流水里 PDF 预览、下载、重新生成入口完整。

### 第 3 期：采购、销售、质检细节统一

目标：

- 销售订单、采购订单、到货入库、质量校验页面继续消除残留普通控件。
- 关联销售订单、采购明细、质检备注弹窗等改成统一纸质选择/说明面板。

验收：

- 已有 PDF 归档能力不回退。
- 纸质字段、明细表、按钮区和仓库单据保持同一套视觉语言。

### 第 4 期：发货、退货、返工闭环

目标：

- 发货台账按销售订单聚合后的明细留档入口统一。
- 退货、返工、废料处置相关页面和退货库单据闭环。
- 若旧页面被新仓库流程替代，则标记为只读台账或移除入口，避免双流程。

验收：

- 用户能从销售订单、发货台账、退货库流水追溯到同一套 PDF 单据。

### 第 5 期：盘库与批量导出

目标：

- 盘库单纸质化和 PDF 归档。
- 各业务台账按时间/筛选条件批量导出单据或流水 Excel。

验收：

- 盘库调整说明进入 PDF。
- Excel 导出不使用省略号，长字段完整输出。

## 测试策略

### 前端测试

每批至少增加源码断言或组件测试：

- 单据页面使用通用 `DocumentFormShell` 或兼容的纸质单据组件。
- 不在纸质单据主体中裸露旧 `form-field / double-field / triple-field / workflow-tip` 作为主要布局。
- 归档按钮使用 `DocumentArchiveActions`。
- 保存按钮位于单据底部操作区，不悬在单据中间。

### 后端测试

继续沿用现有归档测试风格：

- 归档生成成功写入 `document_archives`。
- PDF 文件以 `%PDF` 开头。
- 归档失败不阻断业务保存。
- 列表返回最新 PDF 归档状态。
- 不同业务类型映射到正确 `document_type`。

### 浏览器验收

每批至少手动/浏览器验证：

- 典型桌面宽度。
- 当前内置浏览器窄视口。
- 单据可滚动、按钮位置合理。
- 长文本不挤坏单据。
- PDF 预览/下载入口可见。

## 设计约束

- 纸质化是表现层和归档层升级，不借机删字段。
- 不改变现有业务计算和提交语义。
- 不把主数据维护表单改成纸质单据。
- 不把 PDF 归档失败作为库存/订单保存失败。
- 不新增英文状态、英文备注或英文系统标志。
- 不在 PDF 中使用省略号。
- 不把仓库特有样式继续扩散到全系统，新增能力进入通用 `documentForms`。

## 下一步推荐

推荐进入第 0 期 + 第 1 期合并执行：

1. 先抽象通用单据底座，保留现有仓库兼容层。
2. 接着改 `特殊入库 / 特殊出库`。
3. 再改 `生产出库`。
4. 再改 `生产台账入库结算单`。

这样能最快解决用户当前肉眼最不舒服的仓库混 UI 问题，同时保证做出来的能力可以继续给采购、销售、质检、发货复用。

## 自检

- 无占位项。
- 已明确哪些页面纳入，哪些页面不纳入。
- 已避免把仓库纸质化做成孤岛。
- 已给出分期和优先级。
- 已保持“先视觉/交互统一，不改变业务逻辑”的边界。
