2026-06-12 16:00:56 +08:00

100 KiB

Raw Blame History

Sales Purchase Document Form Archive Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将销售订单、采购订单新增/编辑抽屉升级为真实纸质业务单据风格，并在保存成功后由后端生成 PDF 归档快照，支持预览、下载、批量下载和归档失败重试。

Architecture: 后端新增通用 document_archives 归档底座，销售/采购路由在业务保存后调用归档服务生成 PDF，归档失败不阻断业务保存但必须产生可见状态。前端新增单据纸面组件族，销售订单、采购订单只替换抽屉内部表现形式，不改变字段、计算和提交语义。

Tech Stack: FastAPI, SQLAlchemy 2, Pydantic, ReportLab PDF, Python zipfile, Vue 3 Composition API, Vite, CSS design tokens.

Scope And Non-Negotiables

第一版只覆盖销售订单和采购订单，不扩展到入库单、质检单、仓库出入库单、盘库单。
外层仍使用现有 FormDrawer 入口，内层替换为 v3 确认过的“工厂联单/归档单”视觉。
不删除销售订单、采购订单现有字段，不改变 payload 字段名和计算逻辑。
PDF 是主归档文件，Word 不在本计划中实现为主留档。
合同生成逻辑保持独立，不复用当前 window.print() 合同代码作为订单归档。
业务保存成功后生成 PDF；PDF 生成失败不能回滚业务单据，但列表必须显示“归档失败”并允许重试。
归档状态、业务文案和错误信息使用中文：未生成、已归档、归档失败。
当前项目目录可能不是 git 工作区。执行任务时若 git status 可用，每个任务结束提交一次；若不可用，记录变更文件和验证结果。

Visual Benchmark

已确认的视觉基准：

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
outputs/document-form-mockups/order-form-document-mockup-v3.html

必须保留的视觉特征：

真实米白纸张、轻纸纹、黑色表格线。
金属夹、叠纸阴影、装订孔。
标题居中大黑字：销售订单、采购订单。
右上角红/绿单据编号章。
竖向 ERP留存联 标记。
PDF 归档章不能遮挡核心数据。
明细区域是纸面表格行，不再是多张卡片堆叠。
底部有签字/确认栏。

File Structure

Backend

Create: backend/app/models/document_archive.py
- SQLAlchemy model for document_archives.
Modify: backend/app/models/__init__.py
- Export DocumentArchive so Base.metadata.create_all() includes the table in tests.
Create: backend/app/schemas/document_archives.py
- Pydantic read models and batch download request.
Modify: backend/app/schemas/database.py
- Add archive fields to SalesOrderRead and SalesOrderCreateResult.
Modify: backend/app/schemas/operations.py
- Add archive fields to PurchaseOrderRead.
Create: backend/sql/add_document_archives_patch.sql
- MySQL migration for the archive table.
Modify: backend/requirements.txt
- Add ReportLab dependency.
Create: backend/app/services/document_archives.py
- Collect sales/purchase data, render PDF, persist archive rows, return latest archive, build zip.
Create: backend/app/api/routes/document_archives.py
- Generic generate/preview/download/batch download endpoints.
Modify: backend/app/api/router.py
- Register document archive router.
Modify: backend/app/services/sales_planning.py
- Enrich sales order query with latest archive metadata.
Modify: backend/app/services/operations.py
- Enrich purchase order query with latest archive metadata.
Modify: backend/app/api/routes/sales.py
- Generate archive after sales order save.
Modify: backend/app/api/routes/purchase.py
- Generate archive after purchase order create/update.
Create: backend/tests/test_document_archive_model.py
Create: backend/tests/test_document_archive_service.py
Create: backend/tests/test_document_archive_routes.py
Create: backend/tests/test_sales_order_document_archive.py
Create: backend/tests/test_purchase_order_document_archive.py

Frontend

Create: frontend/src/components/documentForms/DocumentPaper.vue
- Paper shell: clip, stacked paper, binder holes, title, document number stamp, retained-copy mark.
Create: frontend/src/components/documentForms/DocumentGrid.vue
- Paper-style label/value grid for header fields.
Create: frontend/src/components/documentForms/DocumentLineTable.vue
- Paper-style editable line table wrapper.
Create: frontend/src/components/documentForms/DocumentArchiveActions.vue
- Archive status, preview, download, retry, batch download buttons.
Modify: frontend/src/styles/main.css
- Add document paper CSS tokens and responsive layout.
Modify: frontend/src/services/api.js
- Keep downloadResource() and openResource(); add postDownloadResource() for batch zip.
Modify: frontend/src/views/SalesPlanningView.vue
- Replace sales order drawer internals with document form components and add archive actions to list.
Modify: frontend/src/views/PurchaseOrderView.vue
- Replace purchase order drawer internals with document form components and add archive actions to list.
Create: frontend/scripts/test-document-form-components.mjs
Create: frontend/scripts/test-sales-purchase-document-archive-ui.mjs

Task 1: Archive Data Model And SQL Foundation

Files:

Create: backend/app/models/document_archive.py
Modify: backend/app/models/__init__.py
Create: backend/app/schemas/document_archives.py
Modify: backend/app/schemas/database.py
Modify: backend/app/schemas/operations.py
Create: backend/sql/add_document_archives_patch.sql
Test: backend/tests/test_document_archive_model.py
Step 1: Write the failing model test

Create backend/tests/test_document_archive_model.py:

from __future__ import annotations

import unittest
from datetime import datetime

from sqlalchemy import BigInteger, create_engine, select
from sqlalchemy.ext.compiler import compiles
from sqlalchemy.orm import sessionmaker


@compiles(BigInteger, "sqlite")
def _compile_bigint_for_sqlite(type_, compiler, **kw) -> str:
    _ = type_, compiler, kw
    return "INTEGER"


import app.models.document_archive  # noqa: E402,F401
import app.models.master_data  # noqa: E402,F401
import app.models.miniapp  # noqa: E402,F401
import app.models.operations  # noqa: E402,F401
import app.models.org  # noqa: E402,F401
import app.models.planning  # noqa: E402,F401
import app.models.sales  # noqa: E402,F401
from app.models.base import Base  # noqa: E402
from app.models.document_archive import DocumentArchive  # noqa: E402


class DocumentArchiveModelTest(unittest.TestCase):
    def setUp(self) -> None:
        engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
        Base.metadata.create_all(engine)
        self.SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False, future=True)
        self.db = self.SessionLocal()

    def tearDown(self) -> None:
        self.db.close()

    def test_document_archive_round_trips_chinese_business_status(self) -> None:
        row = DocumentArchive(
            document_type="销售订单",
            business_id=101,
            document_no="销售2026-00001",
            archive_version=1,
            template_version="单据纸面V1",
            file_format="PDF",
            file_name="销售订单-销售2026-00001-v1.pdf",
            file_path="outputs/document_archives/sales_order/销售订单-销售2026-00001-v1.pdf",
            file_hash="abc123",
            status="已归档",
            error_message=None,
            created_by=None,
            created_at=datetime(2026, 6, 11, 10, 0, 0),
            updated_at=datetime(2026, 6, 11, 10, 0, 0),
        )
        self.db.add(row)
        self.db.commit()

        saved = self.db.scalar(select(DocumentArchive).where(DocumentArchive.document_type == "销售订单"))

        self.assertIsNotNone(saved)
        self.assertEqual(saved.status, "已归档")
        self.assertEqual(saved.template_version, "单据纸面V1")
        self.assertEqual(saved.archive_version, 1)

Step 2: Run the model test to verify it fails

Run:

cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP
PYTHONPATH=backend pytest backend/tests/test_document_archive_model.py -q

Expected: FAIL with ModuleNotFoundError: No module named 'app.models.document_archive'.

Step 3: Create the SQLAlchemy model

Create backend/app/models/document_archive.py:

from __future__ import annotations

from sqlalchemy import BigInteger, DateTime, Integer, String, Text
from sqlalchemy.orm import Mapped, mapped_column

from app.models.base import Base


class DocumentArchive(Base):
    __tablename__ = "document_archives"

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    document_type: Mapped[str] = mapped_column(String(50))
    business_id: Mapped[int] = mapped_column(BigInteger)
    document_no: Mapped[str] = mapped_column(String(100))
    archive_version: Mapped[int] = mapped_column(Integer)
    template_version: Mapped[str] = mapped_column(String(50))
    file_format: Mapped[str] = mapped_column(String(20))
    file_name: Mapped[str] = mapped_column(String(255))
    file_path: Mapped[str] = mapped_column(String(500))
    file_hash: Mapped[str | None] = mapped_column(String(128), nullable=True)
    status: Mapped[str] = mapped_column(String(32))
    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
    created_by: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
    created_at: Mapped[object] = mapped_column(DateTime)
    updated_at: Mapped[object] = mapped_column(DateTime)

Step 4: Export the model

Modify backend/app/models/__init__.py:

from app.models.document_archive import DocumentArchive

Add "DocumentArchive" to __all__.

Step 5: Create archive schemas

Create backend/app/schemas/document_archives.py:

from __future__ import annotations

from datetime import datetime

from pydantic import BaseModel, Field


class DocumentArchiveRead(BaseModel):
    archive_id: int
    document_type: str
    business_id: int
    document_no: str
    archive_version: int
    template_version: str
    file_format: str
    file_name: str
    status: str
    error_message: str | None = None
    created_at: datetime


class DocumentArchiveGenerateResult(BaseModel):
    business_id: int
    document_type: str
    document_no: str
    archive_status: str
    archive_version: int | None = None
    archive_error_message: str | None = None


class DocumentArchiveBatchDownloadRequest(BaseModel):
    document_type: str
    business_ids: list[int] = Field(default_factory=list, min_length=1)

Step 6: Add archive fields to sales schemas

Modify backend/app/schemas/database.py.

In SalesOrderRead, add:

    archive_status: str = "未生成"
    archive_version: int | None = None
    archive_created_at: datetime | None = None
    archive_error_message: str | None = None

In SalesOrderCreateResult, add:

    archive_status: str = "未生成"
    archive_version: int | None = None
    archive_error_message: str | None = None

If datetime is not already imported in backend/app/schemas/database.py, extend the existing datetime import to include it.

Step 7: Add archive fields to purchase schemas

Modify backend/app/schemas/operations.py.

In PurchaseOrderRead, add:

    archive_status: str = "未生成"
    archive_version: int | None = None
    archive_created_at: datetime | None = None
    archive_error_message: str | None = None

If datetime is not already imported in backend/app/schemas/operations.py, extend the existing datetime import to include it.

Step 8: Create the MySQL SQL patch

Create backend/sql/add_document_archives_patch.sql:

CREATE TABLE IF NOT EXISTS document_archives (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  document_type VARCHAR(50) NOT NULL COMMENT '单据类型：销售订单/采购订单',
  business_id BIGINT NOT NULL COMMENT '业务主表ID',
  document_no VARCHAR(100) NOT NULL COMMENT '业务单号',
  archive_version INT NOT NULL COMMENT '归档版本',
  template_version VARCHAR(50) NOT NULL DEFAULT '单据纸面V1' COMMENT '模板版本',
  file_format VARCHAR(20) NOT NULL DEFAULT 'PDF' COMMENT '文件格式',
  file_name VARCHAR(255) NOT NULL COMMENT '文件名',
  file_path VARCHAR(500) NOT NULL COMMENT '文件路径',
  file_hash VARCHAR(128) NULL COMMENT '文件哈希',
  status VARCHAR(32) NOT NULL COMMENT '归档状态：已归档/归档失败',
  error_message TEXT NULL COMMENT '归档失败原因',
  created_by BIGINT NULL COMMENT '生成用户ID',
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_document_archives_version (document_type, business_id, archive_version, file_format),
  KEY idx_document_archives_business_latest (document_type, business_id, archive_version),
  KEY idx_document_archives_document_no (document_no),
  KEY idx_document_archives_status (status, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Step 9: Run the model test to verify it passes

Run:

cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP
PYTHONPATH=backend pytest backend/tests/test_document_archive_model.py -q

Expected: PASS.

Step 10: Record checkpoint

Run:

git status --short || true

Expected in this workspace: either changed files are listed, or git reports this directory is not a git repository.

Task 2: PDF Archive Rendering Service

Files:

Modify: backend/requirements.txt
Create: backend/app/services/document_archives.py
Test: backend/tests/test_document_archive_service.py
Step 1: Add a PDF dependency

Modify backend/requirements.txt and append:

reportlab>=4.2,<5.0

Step 2: Write the failing service test

Create backend/tests/test_document_archive_service.py:

from __future__ import annotations

import unittest
from datetime import date, datetime
from pathlib import Path
from tempfile import TemporaryDirectory

from sqlalchemy import BigInteger, create_engine
from sqlalchemy.ext.compiler import compiles
from sqlalchemy.orm import sessionmaker


@compiles(BigInteger, "sqlite")
def _compile_bigint_for_sqlite(type_, compiler, **kw) -> str:
    _ = type_, compiler, kw
    return "INTEGER"


import app.models.document_archive  # noqa: E402,F401
import app.models.master_data  # noqa: E402,F401
import app.models.miniapp  # noqa: E402,F401
import app.models.operations  # noqa: E402,F401
import app.models.org  # noqa: E402,F401
import app.models.planning  # noqa: E402,F401
import app.models.sales  # noqa: E402,F401
from app.models.base import Base  # noqa: E402
from app.models.document_archive import DocumentArchive  # noqa: E402
from app.models.master_data import Item  # noqa: E402
from app.models.sales import Customer, SalesOrder, SalesOrderItem  # noqa: E402
from app.services.document_archives import (  # noqa: E402
    DOCUMENT_TYPE_SALES_ORDER,
    generate_document_archive,
    get_latest_archive,
)


class DocumentArchiveServiceTest(unittest.TestCase):
    def setUp(self) -> None:
        engine = create_engine("sqlite+pysqlite:///:memory:", future=True)
        Base.metadata.create_all(engine)
        self.SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False, future=True)
        self.db = self.SessionLocal()
        now = datetime(2026, 6, 11, 10, 0, 0)
        self.customer = Customer(
            id=1,
            customer_code="CUS001",
            customer_name="嘉恒客户",
            short_name="嘉恒",
            status="ACTIVE",
            created_at=now,
            updated_at=now,
        )
        self.product = Item(
            id=10,
            item_code="CP00010",
            item_name="钢制碗",
            item_type="FINISHED",
            unit_id=None,
            status="ACTIVE",
            created_at=now,
            updated_at=now,
        )
        self.order = SalesOrder(
            id=100,
            order_no="销售2026-00001",
            customer_id=1,
            order_date=date(2026, 6, 11),
            promised_date=date(2026, 6, 20),
            sales_employee_id=None,
            delivery_address="宁波市测试路1号",
            tax_rate=0.13,
            total_amount=600,
            status="OPEN",
            created_at=now,
            updated_at=now,
        )
        self.item = SalesOrderItem(
            id=1000,
            sales_order_id=100,
            line_no=1,
            product_item_id=10,
            customer_part_no="KH-001",
            order_qty=100,
            delivered_qty=0,
            unit_price=6,
            line_amount=600,
            promised_date=date(2026, 6, 20),
            status="OPEN",
            created_at=now,
            updated_at=now,
        )
        self.db.add_all([self.customer, self.product, self.order, self.item])
        self.db.commit()
        self.tempdir = TemporaryDirectory()

    def tearDown(self) -> None:
        self.tempdir.cleanup()
        self.db.close()

    def test_generate_sales_order_archive_creates_pdf_and_archive_row(self) -> None:
        result = generate_document_archive(
            self.db,
            document_type=DOCUMENT_TYPE_SALES_ORDER,
            business_id=100,
            created_by=None,
            archive_root=Path(self.tempdir.name),
        )

        self.assertEqual(result.archive_status, "已归档")
        self.assertEqual(result.archive_version, 1)
        archive = get_latest_archive(self.db, DOCUMENT_TYPE_SALES_ORDER, 100)
        self.assertIsNotNone(archive)
        self.assertEqual(archive.document_no, "销售2026-00001")
        pdf_path = Path(archive.file_path)
        self.assertTrue(pdf_path.exists())
        self.assertEqual(pdf_path.read_bytes()[:4], b"%PDF")

    def test_generate_archive_uses_version_sequence(self) -> None:
        generate_document_archive(self.db, DOCUMENT_TYPE_SALES_ORDER, 100, archive_root=Path(self.tempdir.name))
        second = generate_document_archive(self.db, DOCUMENT_TYPE_SALES_ORDER, 100, archive_root=Path(self.tempdir.name))

        self.assertEqual(second.archive_version, 2)
        rows = self.db.query(DocumentArchive).filter(DocumentArchive.business_id == 100).all()
        self.assertEqual(len(rows), 2)

Step 3: Run the service test to verify it fails

Run:

cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP
PYTHONPATH=backend pytest backend/tests/test_document_archive_service.py -q

Expected: FAIL with ModuleNotFoundError: No module named 'app.services.document_archives'.

Step 4: Create service constants and helpers

Create backend/app/services/document_archives.py with these top-level constants and helpers:

from __future__ import annotations

import hashlib
import re
from dataclasses import dataclass
from datetime import datetime
from decimal import Decimal
from pathlib import Path
from zipfile import ZIP_DEFLATED, ZipFile

from fastapi import HTTPException
from reportlab.lib import colors
from reportlab.lib.pagesizes import A4
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.cidfonts import UnicodeCIDFont
from reportlab.pdfgen import canvas
from sqlalchemy import func, select
from sqlalchemy.orm import Session, aliased

from app.models.document_archive import DocumentArchive
from app.models.master_data import Item
from app.models.operations import PurchaseOrder, PurchaseOrderItem, PurchaseOrderSalesOrderLink, Supplier
from app.models.org import Employee
from app.models.sales import Customer, SalesOrder, SalesOrderItem
from app.schemas.document_archives import DocumentArchiveGenerateResult

DOCUMENT_TYPE_SALES_ORDER = "销售订单"
DOCUMENT_TYPE_PURCHASE_ORDER = "采购订单"
ARCHIVE_STATUS_READY = "已归档"
ARCHIVE_STATUS_FAILED = "归档失败"
ARCHIVE_STATUS_MISSING = "未生成"
TEMPLATE_VERSION = "单据纸面V1"
FILE_FORMAT_PDF = "PDF"


@dataclass(frozen=True)
class ArchiveLine:
    line_no: int
    name: str
    code: str
    spec: str
    qty_text: str
    price_text: str
    amount_text: str
    date_text: str
    remark: str


@dataclass(frozen=True)
class ArchiveContext:
    document_type: str
    document_no: str
    title: str
    party_label: str
    party_name: str
    owner_label: str
    owner_name: str
    date_label: str
    date_text: str
    promised_label: str
    promised_text: str
    tax_rate_text: str
    address_or_target_text: str
    remark: str
    total_label: str
    total_text: str
    lines: list[ArchiveLine]
    signature_labels: tuple[str, str, str, str]


def default_archive_root() -> Path:
    return Path(__file__).resolve().parents[3] / "outputs" / "document_archives"


def safe_filename(value: str) -> str:
    normalized = re.sub(r"[\\/:*?\"<>|\\s]+", "-", str(value or "").strip())
    return normalized.strip("-") or "单据"


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def decimal_text(value: object, places: int = 2) -> str:
    amount = Decimal(str(value or 0))
    return f"{amount:,.{places}f}"


def date_text(value: object | None) -> str:
    return str(value or "-")[:10]

Step 5: Add latest archive and version helpers