合格证模板打印指南¶

概述¶

本模块实现了基于 VBA 坐标转换的合格证模板打印功能，支持全中文、中英文、俄英文等多种合格证底板。

文件结构¶

config/templates/
└── coordinates.yaml          # 模板坐标配置文件

src/certflow/services/printer/
├── coordinate_converter.py   # VBA 坐标转换器（开发工具）
├── template_manager.py       # 模板管理器
└── printer_service.py        # 打印服务（已集成 print_by_template）

模板列表¶

模板键	名称	变体	说明
`full_chinese_1`	全中文合格证	检验5灰度	标准全中文底板
`full_chinese_2`	全中文合格证	红色质检章	红色印章版本
`full_chinese_3`	全中文合格证	印刷版品保章	印刷版底板
`bilingual_1`	中英文合格证	检5灰度	标准中英文底板
`bilingual_2`	中英文合格证	质检部手工印章	手工印章版本
`bilingual_4`	中英文合格证	检5彩色印章	彩色印章版本
`bilingual_5`	中英文合格证	印刷蓝OQC	OQC 印刷版
`russian`	俄英文合格证	无印章	俄英文底板

使用方式¶

1. 代码调用¶

from src.certflow.services.printer import PrinterService

service = PrinterService()

data = {
    "product_name": "高温高压截止阀",
    "product_model": "J41H-100",
    "dn": "DN200",
    "pn": "PN100",
    "temperature": "≤540℃",
    "medium": "蒸汽、水",
    "check_standard": "GB/T 12235-2007",
    "inspector_id": "质检002",
    "manufacture_date": "2025.06",
    "cert_number": "V2512002",
}

# 打印俄英文合格证
service.print_by_template("russian", data, copies=1)

2. 模板管理器¶

from src.certflow.services.printer.template_manager import TemplateManager

tm = TemplateManager()

# 列出所有模板
for key, name, variant in tm.list_templates():
    print(f"{key}: {name} - {variant}")

# 获取模板信息
template = tm.get_template("russian")

# 获取字段坐标
x = tm.get_field_x("russian", "product_name")
y = tm.get_field_y("russian", "product_name")

3. 命令行工具¶

# 测试模板加载
uv run tests/test_template_print.py --load

# 预览所有模板坐标
uv run tests/test_template_print.py --preview

# 打印偏移校准标尺
uv run tests/test_template_print.py --calibrate

# 执行模板打印测试
uv run tests/test_template_print.py --print

坐标转换说明¶

转换公式¶

actual_mm = (vba_pt * PT_TO_MM) * SCALE + OFFSET

参数	值	说明
PT_TO_MM	0.352777	1磅 = 0.3528 毫米
SCALE	0.75	80mm 底板 → 60mm 卡纸
X_OFFSET	14.0	X 轴打印机物理偏移（实测）
Y_OFFSET	0.0	Y 轴偏移（待实测）

俄英文模板坐标示例¶

字段	X (mm)	Y (mm)	宽度 (mm)	高度 (mm)	字号
product_name	42.18	23.68	32.35	12.30	10
product_model	42.18	33.64	30.23	4.94	10
dn	42.18	40.13	25.91	4.63	9
pn	42.18	46.30	25.91	4.63	9
temperature	42.18	52.39	25.91	4.39	9
medium	42.18	56.16	25.91	9.33	9
check_standard	42.18	63.70	25.91	4.39	8
inspector_id	42.18	70.00	25.91	4.39	9
manufacture_date	42.18	75.96	25.91	4.39	9
serial_number	42.18	81.91	25.91	4.39	9

配置文件格式¶

# config/templates/coordinates.yaml
templates:
  russian:
    name: "俄英文合格证"
    variant: "无印章"
    background: "resources/backgrounds/ru_en_bg.png"
    page_width: 60
    page_height: 100
    fields:
      product_name: {x: 42.18, y: 23.68, width: 32.35, height: 12.3, font_size: 10, align: left}
      product_model: {x: 42.18, y: 33.64, width: 30.23, height: 4.94, font_size: 10, align: left}
      # ... 其他字段

添加新模板¶

在 coordinate_converter.py 中添加 VBA 原始坐标数据
在 TEMPLATE_CONFIGS 中添加模板配置

运行生成 YAML：

uv run src/certflow/services/printer/coordinate_converter.py --yaml

将输出追加到 config/templates/coordinates.yaml

调试与校准¶

打印校准标尺¶

uv run tests/test_template_print.py --calibrate

标尺包含：

水平标尺（X轴，5-55mm）
垂直标尺（Y轴，10-90mm）
俄英文模板参考位置

调整偏移量¶

编辑 config/config.yaml：

certificate_print:
  layout:
    x_offset: 14    # X 轴偏移（mm）
    y_offset: 0     # Y 轴偏移（mm），根据实测调整

注意事项¶

X 轴已 +14mm 补偿：由于打印机物理起始位置有 14mm 左边距
Y 轴未补偿：Y 轴偏移需要根据实测调整
字体大小：使用打印机内置字库，实际大小可能与配置略有差异
底板图片：确保 resources/backgrounds/ 目录下有对应的底板图片

故障排除¶

问题	可能原因	解决方案
打印位置偏左	X 偏移不足	增加 `x_offset`
打印位置偏右	X 偏移过大	减少 `x_offset`
打印位置偏上	Y 偏移过小	增加 `y_offset`（正数向下）
打印位置偏下	Y 偏移过大	减少 `y_offset`
模板加载失败	YAML 文件路径错误	检查 `coordinates.yaml` 是否存在
字段值为空	数据字典缺少字段	检查 `data` 中的字段名是否匹配