ForgeFlow-ERP/docs/superpowers/specs/2026-06-11-sales-purchase-document-form-archive-design.md

销售/采购订单单据化与 PDF 归档设计

背景

当前销售订单、采购订单新增页面主要是抽屉内的卡片式数据录入表单。它能完成业务数据提交，但视觉上更像后台管理系统，不像正式业务单据。

本次先按方案 B 试点：只改造“销售订单”和“采购订单”。目标是验证“真实单据填写 + 保存即归档”的产品方向，跑通后再扩展到到货入库单、仓库出入库单、质检单、盘库单等其他单据。

设计目标

1. 销售订单、采购订单新增表单改为真实“单据”形态，用户感觉是在填写正式业务单。
2. 外层仍沿用当前系统抽屉，不改变用户从列表点击新增的入口习惯。
3. 内层采用 v3 效果图方向：工厂联单/归档单风格，而不是普通网页卡片拟纸。
4. 单据保存成功时，后端基于当时业务数据生成不可变 PDF 归档快照。
5. PDF 作为主归档文件，Word 只作为按需辅助导出，不作为原始留档依据。
6. 列表支持单据归档状态展示、单份预览、单份下载、多选批量下载。

视觉方向

采用“工厂联单/归档单嵌入系统抽屉”的风格。

已确认的 v3 效果图文件：

• outputs/document-form-mockups/sales-order-document-form-mockup-v3-real-paper.png
• outputs/document-form-mockups/purchase-order-document-form-mockup-v3-real-paper.png

关键视觉特征：

• 真实纸张底色，偏米白而不是冷白网页卡片。
• 纸张纹理轻量保留，避免影响阅读。
• 外层有档案板/叠纸阴影，体现这是一张正式归档单。
• 顶部使用金属夹/装订元素，增强真实“夹在文件板上”的感觉。
• 单据标题使用黑色居中大字，例如“销售订单”“采购订单”。
• 单据编号使用右上红/绿编号章，不再放在普通卡片角标里。
• 表单字段使用真实单据表格格线，减少圆角输入框感。
• 明细使用表格行，表现为“纸上填写格”，不再使用多张卡片堆叠。
• 底部保留签字/确认栏，例如销售确认、客户确认、财务复核、制单人。
• PDF 归档章弱化为纸面印章，不能遮挡核心数据。

交互范围

销售订单新增

保持现有字段和业务逻辑，不删字段、不改变提交语义。

单据结构：

1. 单据头部：公司名、销售订单标题、销售订单号、归档联标记。
2. 抬头信息：客户、销售人员、下单日期、交期、税率、送货地址。
3. 订单明细：产品、客户料号、订单数量、销售单价、明细交期、金额。
4. 汇总信息：订单总数、未税金额、含税金额、归档状态。
5. 备注与签字：备注、销售确认、客户确认、财务复核、制单人。
6. 操作区：保存草稿、保存并生成 PDF 归档。

采购订单新增

保持现有字段和业务逻辑，不删字段、不改变提交语义。

单据结构：

1. 单据头部：公司名、采购订单标题、采购单号、归档联标记。
2. 采购路径：到货库、采购方式、归档策略。
3. 抬头信息：供应商、采购人员、预计到货、提前预警、税率、关联销售订单。
4. 采购明细：原材料、性能要求、采购重量、辅助吨数、单价、元/吨、明细交期。
5. 汇总信息：采购总重量、折合吨数、含税金额、归档状态。
6. 备注与签字：采购确认、供应商确认、仓库接收、制单人。
7. 操作区：保存草稿、保存并生成 PDF 归档。

归档规则

主档格式

PDF 是主归档文件。

原因：

• PDF 更适合固定原始单据快照。
• PDF 不易被用户误编辑。
• 后续预览、下载、批量下载更稳定。

Word 只做辅助导出。

原因：

• Word 可编辑，不适合作为原始留档依据。
• 如果后续客户需要对外沟通版本，可以导出 Word，但系统内部追溯以 PDF 为准。

生成时机

第一版采用“保存成功后自动生成 PDF 归档”。

具体规则：

• 新增销售订单保存成功后，立即生成销售订单 PDF 归档。
• 新增采购订单保存成功后，立即生成采购订单 PDF 归档。
• 如果 PDF 生成失败，业务单据仍可保存，但列表显示“归档失败”，允许用户重新生成。
• 归档生成时要记录模板版本、生成时间、生成用户、文件路径、文件哈希。

编辑后的处理

第一版建议采用版本化归档。

规则：

• 每次关键字段编辑后重新生成新的 PDF 归档版本。
• 历史归档版本保留。
• 列表默认展示最新归档。
• 详情中可查看历史归档版本。

这样不会出现“数据改了，但原来 PDF 覆盖掉了”的追溯风险。

数据模型建议

新增通用单据归档表，例如 document_archives。

建议字段：

• id
• document_type：销售订单、采购订单等。
• business_id：业务主表 ID。
• document_no：业务单号。
• archive_version：归档版本号。
• template_version：模板版本。
• file_format：PDF 或 DOCX。
• file_name
• file_path
• file_hash
• status：已生成、生成失败。
• error_message
• created_by
• created_at

第一版只要求销售订单、采购订单接入。

前端列表调整

销售订单列表、采购订单列表增加归档相关操作。

列表列建议：

• 归档状态：未生成、已归档、归档失败。
• 操作：预览、下载、重新生成。

批量操作：

• 勾选多张销售订单后可批量下载 PDF。
• 勾选多张采购订单后可批量下载 PDF。
• 批量下载由后端打包 zip。

后端接口建议

销售订单：

• POST /sales/orders/{id}/archive
• GET /sales/orders/{id}/archive/latest/preview
• GET /sales/orders/{id}/archive/latest/download
• POST /sales/orders/archives/batch-download

采购订单：

• POST /purchase/orders/{id}/archive
• GET /purchase/orders/{id}/archive/latest/preview
• GET /purchase/orders/{id}/archive/latest/download
• POST /purchase/orders/archives/batch-download

也可以抽象成通用接口：

• POST /document-archives/{document_type}/{business_id}/generate
• GET /document-archives/{document_type}/{business_id}/latest
• POST /document-archives/batch-download

第一版建议后端服务层通用，路由层可以先按销售/采购分别暴露，便于前端调用和权限控制。

技术实现建议

前端

新增通用单据表单组件：

• DocumentFormDrawer
• DocumentPaper
• DocumentGrid
• DocumentLineTable
• DocumentArchiveActions

销售订单和采购订单分别提供字段配置，不建议完全硬编码到一个巨大组件里。

后端

新增归档服务：

• 收集业务数据。
• 渲染 HTML 模板。
• 生成 PDF。
• 写入归档记录。
• 提供预览、下载、批量 zip。

PDF 生成建议后端完成，不能只依赖浏览器 window.print()。

文件存储

第一版可以先存在服务器本地目录，例如：

• outputs/document_archives/sales_order/
• outputs/document_archives/purchase_order/

后续正式环境再迁移到对象存储也可以。

风险与边界

1. 这次不是全系统单据化，只试点销售订单和采购订单。
2. 不改变销售订单、采购订单现有业务字段和计算逻辑。
3. 不把合同生成逻辑和单据归档混在一起。合同是对外合同，订单归档是内部业务原始单据。
4. PDF 归档失败不能阻断核心业务保存，但必须明确提醒并允许补生成。
5. 真实纸张效果要服务阅读，不能为了拟物牺牲表格清晰度。

验收标准

1. 新增销售订单页面不再是卡片堆叠，而是 v3 风格单据填写。
2. 新增采购订单页面不再是卡片堆叠，而是 v3 风格单据填写。
3. 保存销售订单后生成 PDF 归档记录。
4. 保存采购订单后生成 PDF 归档记录。
5. 销售订单列表可预览、下载、批量下载归档 PDF。
6. 采购订单列表可预览、下载、批量下载归档 PDF。
7. PDF 归档中显示单据编号、公司名、关键抬头、明细、汇总、制单信息。
8. PDF 主归档、Word 辅助导出的规则在代码和界面文案中保持一致。

设计结论

采用方案 B 作为第一版试点：

• 销售订单、采购订单先单据化。
• 使用 v3 工厂联单/归档单视觉方向。
• PDF 作为主归档。
• Word 作为后续按需辅助导出。
• 归档能力做成通用底座，后续再推广到其他业务单据。