商仓科技-美国标签条码PDF生成

概述

美国标签条码 PDF 生成器

给定一个条码值、需要打印的张数、标签格式，生成一份 US Letter（美国信纸 8.5"×11"）的标签 PDF，可直接打印，或上传海外仓/亚马逊系统批量作业。

触发场景

• "帮我生成 XX 条码的标签，打 30 张"
• "这个 FNSKU 要打 3×10 格式的标签"
• "产品要贴标，条码 XXXXX，2×3 格式，出个 PDF"
• "亚马逊标签 / 美国标签 / 条码标签 PDF"

核心规则（已查证权威来源）

纸张与格式

纸张统一 US Letter = 8.5" × 11"（不是 A4）。

条码类型（自动识别，无需用户指定）

打印硬要求

• 黑白实线、白底非反光标签纸，≥ 300 DPI
• 打印缩放必须 100% / 实际大小，禁止"适合页面"（缩放会让标签尺寸掉出合规范围、静区不够而扫不出）
• 条码静区：左右 ≥ 0.25"、上下 ≥ 0.125" 留白（脚本已内置 6pt quiet zone + 标签内自动居中缩排）
• FNSKU 标签可选附加：产品名称（title）、状态（condition，如 New）

执行步骤

1. 确认三要素：条码值、总张数 qty、格式 layout（3×10 / 2×3）。用户没给格式时，问一句再跑（2×3 是大标、3×10 是小标，用途不同，别乱猜）。
2. 调用 scripts/gen_label_pdf.py：

   python3 gen_label_pdf.py --code "X001FH8K2N" --qty 30 --layout 3x10 
       --title "产品名" --condition "New" --out 输出路径.pdf

1. 参数说明：
   • --code（必填）条码值，≤ 48 个字符，只支持英文字母、数字及常见符号（-/./空格等），不支持中文/全角
   • --qty（必填）总张数，1 ~ 10000 张，脚本自动算页数（ceil(qty/每页张数)）
   • --layout：3x10（默认，30张/页）或 2x3（6张/页）
   • --title / --condition：可选，FNSKU 标签附加的产品名/状态
   • --out：输出路径；不填默认写 ~/WorkBuddy/Claw/generated-images/labels_{code}_{layout}_x{qty}.pdf
2. 把生成的 PDF 交给用户（present_files），说明页数与单张尺寸、以及"打印选 100% 缩放"。

输入校验与错误提示（v1.1 新增）

脚本内置统一校验，输入有误时给出明确中文提示、退出码 1，不会报错退出、也不会静默生成废文件。会拦截的情况：

硬限制（对外明确告知）：条码最长 48 字符，单次最多 10000 张。超长条码即使能生成，3×10 小标签上也会被压到扫不出，应改用 2×3 大格式或拆分批。

输出内容

每个标签单元格包含（从上到下）：

1. 条码图片（自动居中、超宽自动缩到标签内）
2. 条码值文字（加粗，人眼可读）
3. 产品名称（标题，可选，超长自动截断加…）
4. 状态（condition，可选）

四周灰色虚线裁剪参考线。

依赖

pip install python-barcode pillow reportlab

venv 路径（本项目）：/Users/abner/.workbuddy/binaries/python/envs/default/bin/python

边界与陷阱

1. 纸张是美国信纸不是 A4——用 A4 打会错位，务必 US Letter。
2. 2×3 是大标签（4"×3.33"），3×10 是小标签（2.625"×1"）——用途不同：FNSKU 贴单品用 3×10 省纸，箱贴/大件用 2×3。别用错。
3. 纯数字条码会走 UPC/EAN 而不是 Code128——如果用户明确要 Code128（如某些海外仓系统强制），跟他说清数字会被识别成 UPC；真需要强制 Code128，改脚本用 --force-code128（当前版未提供，按需加）。
4. 条码超宽自动缩：极长 FNSKU 条码会缩到标签内，但缩太多会扫不出，此时应换 2×3 大格式而非硬塞 3×10。
5. 静区不可省：不要把条码顶满标签边缘，脚本已自动居中留边。
6. 打印时提醒用户：缩放设 100%，不要"适合页面"。
7. ⛔ 排版 bug 修复记录（勿回退）：
   • 只用 reportlab 自带 barcode widget（createBarcodeDrawing），不要走 python-barcode+Pillow 转图路线——那个路线 set_options 会静默忽略旧参数名（新版是 module_height 不是 height），且 dpi 不一致导致条码错位。
   • Code128 必须 humanReadable=False（开自动文字会和条码条重叠），条码值文字自己用 drawCentredString 画。
   • getAscentDescent() 返回的是字体设计值，比 drawCentredString 实际渲染的字形顶小约 1.5 倍（bold 9pt 设计 ascent 6.46 / 实测 9.63）。文字基线定位必须用实测度量（见脚本 FONT_METRICS），否则文字顶会插进条码或贴边。
   • drawOn(c, x, y) 的 y 是条码底部基准，条码向上长。
   • 改完排版必须跑几何审计：用 pymupdf get_drawings 取黑条 rect + get_text('dict') 取文字 span，验证「条码越界=0、文字越界=0、文字顶距条码底≥gap」。本 skill 的审计脚本内联在测试里。