Add A4 carrier print mode (paper=a4) and document it in README + Swagger

- packing_list renders A5 content into top region of an A4 portrait page when paper=a4, so A5 paper loaded horizontally in an A4 tray prints upright - run.generate/print_document/print_api thread the optional paper param through - README: new Print Service section with A4 carrier usage + curl example - Swagger: POST /api/print description documents the A4 carrier mode
2026-08-05 16:53:47 +08:00
parent bf9199189a
commit ee2fab3847
5 changed files with 119 additions and 16 deletions
--- a/README.md
+++ b/README.md
@@ -118,7 +118,52 @@ WareShipManifest/
 - 数据处理与展示分离：排序在 SQL、合计与日期在 transform、模板只渲染。
 - 生成的 PDF 可用 `pymupdf`（`fitz`）渲染 PNG 做肉眼核对（验证用，非运行时依赖）。

+## 打印服务（HTTP 接口）
+
+系统内置一个 FastAPI 打印服务（`serve.py` / `core/print_api.py`），把装箱单 / 签收单直接发到物理打印机（后端为 SumatraPDF）。
+
+### 启动
+
+```bash
+.venv/Scripts/python.exe serve.py
+# 文档：http://<host>:8000/api/docs    健康检查：http://<host>:8000/api/health
+```
+
+### 调用约定
+
+`POST /api/print`（需 Bearer 鉴权，token 见 `config/settings.yaml` 的 `api.token`）：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `report_type` | 是 | `packing_list` / `sign_receipt` |
+| `params` | 是 | 报表参数：装箱单 `{paichan_no, box_no}`，签收单 `{receipt_no}` |
+| `printer` | 否 | 打印机名；缺省用 `printers.default` |
+| `dry_run` | 否 | `true` 只生成 PDF 不出纸；默认 `false`（真出纸） |
+| `paper` | 否 | 见下方「A4 承载模式」 |
+
+### A4 承载模式（装箱单专用）
+
+现场把 **A5 纸横向装入 A4 纸盒**可避免频繁调卡扣，但横向装载会让 A5 内容在页面上颠倒。
+解决方案：传 `"paper": "a4"`，接口会把 A5 内容渲染到 **A4 纵向页面顶部 148mm 区域**，并按 A4 纵向发打印指令——
+横向装载的 A5 纸自动承接页面顶部内容，出纸正立、完整。该模式已用真机实测验证。
+
+**启用条件（必须同时满足）：**
+1. 请求带 `"paper": "a4"`（仅对 `packing_list` 生效，`sign_receipt` 忽略该字段）；
+2. 物理上 A4 纸盒里的 **A5 纸为横向装载**。
+
+标准 A5 托盘（竖向装载）则**不要传 `paper`**，退回 A5 横向直打。
+
+```bash
+curl -X POST http://<host>:8000/api/print \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"report_type":"packing_list","params":{"paichan_no":"R07425","box_no":1},"paper":"a4","dry_run":false}'
+```
+
+> 承载模式生成的 PDF 文件名带 `_a4` 后缀（`..._a4.pdf`），以别于 A5 直打文件。
+> 集成时请直接读取响应里的 `pdf` 字段，勿硬编码路径。
+
 ## 路线图

- [ ] 后期对接真实打印机（PDF 方案可直接复用）。
+- [x] 对接真实打印机（FastAPI + SumatraPDF 打印服务，支持 A4 承载模式）。
 - [ ] 发货信息单（地址 / 收件人 / 总件数 / 物料编码）—— 与装箱单拆分，另出报表。
--- a/core/print_api.py
+++ b/core/print_api.py
@@ -46,6 +46,9 @@ app = FastAPI(
        "when `printer` is omitted.\n"
        "* Paper size and orientation are chosen automatically per report type: "
        "packing_list → A5 landscape, sign_receipt → A4 portrait.\n"
+        "* Packing list supports an A4 carrier mode via `paper=\"a4\"`: the A5 content is "
+        "rendered on an A4 portrait page (top region) and printed as A4, so it comes out "
+        "correctly on A5 paper loaded horizontally in an A4 tray.\n"
        "* A JSON line is appended to `logs/print.log` for every request."
    ),
    version="1.0.0",
@@ -83,6 +86,17 @@ class PrintRequest(BaseModel):
        description="Target printer name. Falls back to `printers.default` in settings.yaml when omitted.",
        examples=["Canon G1030 series (网络 USB1)"],
    )
+    paper: Optional[Literal["a4"]] = Field(
+        None,
+        description=(
+            "Paper carrier mode. Omit (null) for the default A5 landscape packing list. "
+            "Set to \"a4\" to render the packing list on an A4 portrait page with the A5 "
+            "content placed in the top region, so it prints correctly on A5 paper loaded "
+            "horizontally in an A4 tray (saves re-adjusting the paper clamps). Only "
+            "applies to `packing_list`; ignored for other report types."
+        ),
+        examples=["a4"],
+    )
    dry_run: bool = Field(
        False,
        description="When true, generate the PDF and build the print command but do NOT send it to the printer.",
@@ -140,8 +154,9 @@ def _log(result: dict) -> None:
        f.write(json.dumps(entry, ensure_ascii=False, default=str) + "\n")


-@api_router.post(
-    "/print",
+@app.post(
+    "/api/print",
+    tags=["print"],
    summary="Generate and print a shipping document",
    description=(
        "Generate the requested document as a PDF using the existing report "
@@ -154,7 +169,20 @@ def _log(result: dict) -> None:
        "(skipped when `dry_run=true`).\n"
        "4. Append a JSON line to `logs/print.log`.\n"
        "5. Return the job result.\n\n"
-        "Set `dry_run=true` to generate the PDF without consuming paper."
+        "Set `dry_run=true` to generate the PDF without consuming paper.\n\n"
+        "**A4 Carrier Mode (packing_list only)**\n"
+        "To avoid re-adjusting the printer's paper clamps, A5 paper can be loaded "
+        "**horizontally** in an A4 tray. But horizontal loading would otherwise print "
+        "the A5 content upside-down. This mode fixes it: pass `paper=\"a4\"` and the "
+        "A5 content is rendered into the **top 148mm region of an A4 portrait page**, "
+        "then printed as A4 — the horizontally loaded A5 sheet receives the top region "
+        "and comes out upright and complete. Verified on a real printer.\n\n"
+        "Both conditions are required:\n"
+        "1. Request carries `paper=\"a4\"` (only affects `packing_list`; ignored for others).\n"
+        "2. Physically, the A5 paper is loaded **horizontally** in the A4 tray.\n\n"
+        "For a standard A5 tray (vertical loading), omit `paper` to fall back to normal "
+        "A5 landscape direct print. The A4-carrier PDF is named with an `_a4` suffix; "
+        "always read the returned `pdf` field rather than hard-coding the path."
    ),
    response_description="Print job result, including the generated PDF path.",
    response_model=PrintResponse,
@@ -184,6 +212,7 @@ def print_endpoint(req: PrintRequest):
            params=req.params,
            printer=req.printer,
            dry_run=req.dry_run,
+            paper=req.paper,
        )
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
--- a/core/print_document.py
+++ b/core/print_document.py
@@ -26,6 +26,7 @@ def print_document(
    params: dict,
    printer: str | None = None,
    dry_run: bool = False,
+    paper: str | None = None,
 ) -> dict:
    """生成报表 PDF 并打印。

@@ -33,6 +34,8 @@ def print_document(
    :param params: 报表参数（如 paichan_no/box_no 或 receipt_no）
    :param printer: 指定打印机名；为 None 时用 settings.printers.default
    :param dry_run: True 时只构造打印命令不真正执行（用于验证链路）
+    :param paper: 可选纸张承载模式。packing_list 支持 "a4" —— 渲染到 A4 纵向页面顶部，
+                  配合横向装载的 A5 纸正常出纸；其余报表/取值忽略。
    :return: 结构化结果（含 pdf 路径、打印命令、ok 状态）
    """
    if report_type not in VALID_REPORTS:
@@ -40,13 +43,20 @@ def print_document(

    # 1. 生成 PDF（run.generate 内部已做 required 参数校验与 DB 查询）
    output = run._default_output(report_type, params)
-    out_path = run.generate(report_type, params, output)
+    # A4 承载模式的 PDF 用独立文件名，避免覆盖 A5 直打结果
+    if report_type == "packing_list" and paper == "a4":
+        output = output[:-4] + "_a4.pdf" if output.lower().endswith(".pdf") else output + "_a4"
+    out_path = run.generate(report_type, params, output, paper=paper)

    # 2. 选打印机与纸张（装箱单 A5 横向 / 签收单 A4 纵向）
    target_printer = printer or settings.printers.default
-    paper_settings = settings.print.settings_by_report.get(
-        report_type, settings.print.default_settings
-    )
+    if report_type == "packing_list" and paper == "a4":
+        # A4 承载：物理发送 A4 纵向指令，横向装载的 A5 纸自动承接页面顶部 148mm 内容区
+        paper_settings = "paper=A4,orientation=portrait,color=bw"
+    else:
+        paper_settings = settings.print.settings_by_report.get(
+            report_type, settings.print.default_settings
+        )

    # 3. 打印
    result = printing.print_pdf(
--- a/reports/packing_list/_build_template.py
+++ b/reports/packing_list/_build_template.py
@@ -124,10 +124,18 @@ def styles() -> list[dict]:
    ]


-def document_properties() -> dict:
+def document_properties(paper: str = "a5") -> dict:
    # 边距按 pt 给出（ReportBro 不换算 margin；pageFormat=A5 自动换算页面尺寸为 pt）。
+    # A4 承载模式：物理页面仍是 A4 纵向(210x297mm)，但内容按 A5 横向(210x148mm)设计、
+    # 自然落在页面顶部 148mm 区域。配合打印机把 A5 纸横向装载进 A4 纸盒，发送 A4 指令即可在
+    # 横向 A5 纸上正常出纸，省去反复调整不同幅面纸盒卡扣的过程。
+    # 因 A5 横向与 A4 纵向宽度同为 210mm，元素 x/宽度完全不变，仅画面高度由 148→297mm。
+    if paper == "a4":
+        fmt, orient = "A4", "portrait"
+    else:
+        fmt, orient = "A5", "landscape"
    return {
-        "pageFormat": "A5", "orientation": "landscape",
+        "pageFormat": fmt, "orientation": orient,
        "marginLeft": mm(MARGIN_L), "marginRight": mm(MARGIN_R),
        "marginTop": mm(10), "marginBottom": mm(10),
        "headerDisplay": "never", "headerSize": 0,
@@ -324,11 +332,14 @@ def build_doc_elements(context: dict[str, Any]) -> list[dict]:
    return els


-def build_report_definition(context: dict[str, Any]) -> dict:
-    """组装完整 report_definition（运行时调用，按数据动态布局）。"""
+def build_report_definition(context: dict[str, Any], paper: str = "a5") -> dict:
+    """组装完整 report_definition（运行时调用，按数据动态布局）。
+
+    :param paper: "a5"（默认，A5 横向直打）或 "a4"（A4 纵向承载模式）。
+    """
    return {
        "version": 6,
-        "documentProperties": document_properties(),
+        "documentProperties": document_properties(paper),
        "parameters": parameters(),
        "styles": styles(),
        "docElements": build_doc_elements(context),
--- a/run.py
+++ b/run.py
@@ -15,6 +15,7 @@ from __future__ import annotations

 import argparse
 import importlib
+import inspect
 import json
 import sys
 from datetime import datetime
@@ -80,8 +81,12 @@ def _default_output(report_name: str, params: dict) -> str:
    return f"out/{report_name}.pdf"


-def generate(report_name: str, params: dict, output: str) -> Path:
-    """生成指定报表的 PDF。"""
+def generate(report_name: str, params: dict, output: str, paper: str | None = None) -> Path:
+    """生成指定报表的 PDF。
+
+    :param paper: 可选纸张承载模式（如 "a4"）。透传给模板的 build_report_definition；
+                  模板不接收该参数时（如签收单）自动忽略，不影响原有渲染。
+    """
    from reportbro import Report  # 延迟导入，CLI 报错时信息更清晰

    report_dir = PROJECT_ROOT / "reports" / report_name
@@ -104,7 +109,10 @@ def generate(report_name: str, params: dict, output: str) -> Path:

    # 3. 渲染：模板元素按数据动态布局（明细行高度自适应）
    layout = importlib.import_module(f"reports.{report_name}._build_template")
-    report_def = layout.build_report_definition(context)
+    if "paper" in inspect.signature(layout.build_report_definition).parameters:
+        report_def = layout.build_report_definition(context, paper=paper)
+    else:
+        report_def = layout.build_report_definition(context)
    report = Report(
        report_definition=report_def,
        data=context,