@sunmi/m-receipt

票据 RECEIPT

维护负责人：胡云波 Allen Hu

商米餐饮模版的小票/票据模板资产包（@sunmi/m-receipt），以纯 JSON schema 的形式沉淀各类票据的版式、字段、多语言文案与示例数据。本包不含运行时逻辑，仅作为模板数据源被渲染与打印链路消费。

职责与边界

职责

• 维护各业务票据的 schema 模板（版式结构、可配置组件、字段映射、多语言文案、示例数据）。
• 提供一套可被商户二次定制、按地区扩展的默认模板集合。

边界（不负责）

• 不负责模板渲染——由 @sunmi/max-receipt-viewer 将 schema 渲染为画布/预览。
• 不负责打印输出与指令转换——由 @sunmi/max-print / @sunmi/max-print-bus 处理。
• 不负责业务数据填充——运行时由各业务模块把真实订单数据注入 schema 的占位符。

与其它模块的关系

模块	关系
@sunmi/max-receipt-viewer	消费本包 schema，渲染票据预览/编辑画布
@sunmi/max-print	将渲染结果转换为打印指令并输出到打印机
@sunmi/max-print-bus	打印任务调度/总线，衔接业务侧打印请求与 max-print
各业务模块（m-checkout 等）	运行时按 bizKey 选取对应模板，并填充占位符数据后触发打印

目录结构

默认以 templates/ 内的 schema 集合作为初始模板：

templates
├─ kiosk
│  └─ kioskPickUp.json          # 自助取餐小票
├─ labels
│  └─ labelProductionOrder.json # 标签制作单
└─ tickets
   ├─ bill.json            # 结账单
   ├─ cancellation.json    # 订单取消单
   ├─ customerView.json    # 客看单
   ├─ dailySettlement.json # 日结单
   ├─ preliminary.json     # 预结单
   ├─ productionOrder.json # 制作单
   ├─ takeoutOrder.json    # 外卖单
   ├─ topup.json           # 储值小票
   ├─ transferTable.json   # 转台单
   ├─ turnover.json        # 交接班小票
   └─ voidOrder.json       # 退餐单

地区定制

若某地区模板定制项较多，可在默认集合基础上复制新模板目录，以 templates_【语言标】 命名，作为该地区专属的票据模板。例如：templates_th（泰国）。运行时优先匹配地区目录，未命中则回退到默认 templates/。

Schema 结构说明

每个票据 JSON 是一份自描述模板，核心字段如下：

字段	说明
name	模板名称的多语言映射（zh / en / id / es 等）
version	模板版本号
schemaVersion	schema 结构版本，用于渲染端兼容判断
bizKey	业务标识（如 bill），业务侧据此选取模板
list	模板实际渲染的组件有序列表（页面真实版式）
types	可配置组件目录——编辑器中可增删的组件项，按 groups 分组
template	各组件的模板原型，types / list 通过 typeId 引用
groups	编辑器分组（基础信息 / 菜品 / 费用 / 支付 / 会员 / 页脚等）
data	预览用的示例数据，用于占位符回填演示
lang	各语言（zh-CN / en-US / th / my / id / it / es）的文案字典
defaultLang	默认语言
supported	支持的纸张宽度（80 / 58，单位 mm）

version字段补充说明： 主线从2.15.0版本开始正式启用，对齐应用版本（其他地区模板逐步对齐）。按以下约定维护：

• 模板内容有改动时，跟应用版本保持一致。
• 模板内容无改动时，version不动。 目的：
• 识别某版应用里模板有无改动
• 追溯某版应用其模板版本来源

占位符约定

模板文本通过 {{...}} 占位符表达动态内容：

• {{key|l}} —— 从 lang 字典按当前语言取多语言文案（如 {{ticketName|l}}）。
• {{field}} —— 运行时由业务数据回填的动态字段（如 {{tableName}}、{{orderId}}）。

组件类型

list / template 中常见的组件 type：

• config —— 全局渲染配置（如整行铺满、行号显示）。
• text —— 文本行（含字号 size、对齐 align、加粗 bold）。
• image —— 图片（如门店 logo、自定义图片），可编辑。
• staticImage —— 静态图片，不可编辑。
• divider —— 分割线。
• column —— 多列（菜品明细、费用明细、支付明细等），通过 dataKey 绑定 data 中的数组可实现表格效果。
• brcode —— 条码。
• qr —— 二维码。
• columnInColumn —— 多列嵌套，实现复杂的。

hideFields 用于声明：当某数据字段为空时隐藏该组件。

格式约定

本目录配有 .prettierrc，对 JSON 采用 2 空格缩进并强制数组/对象每元素独占一行（JSON.stringify(obj, null, 2) 风格）。修改模板后建议执行：

pnpm prettier --write "templates/**/*.json"

package.json version

package.json 的 version 供 GitHub CI（Publish package）消费，每次模板改动都需递增。

已自动化：仓库配置了 git pre-commit 钩子（.githooks/pre-commit → scripts/bump-receipt-version.mjs），当提交中包含 templates/ 或 templates_*/ 下的改动时，会自动把本包 package.json 的 patch 版本 +1 并加入本次提交。

• 钩子路径由根 package.json 的 prepare 脚本（git config core.hooksPath .githooks）在安装依赖时自动启用；也可手动执行该命令启用。
• 若你在同一次提交里已手动改了 version，钩子会跳过，不会重复递增。
• 该自动化仅处理 package.json 版本；模板 JSON 内的 version（对齐应用版本）仍按上文约定手动维护。