Engineering Case Study · RCA · Postmortem · Printer Integration · Template Engine
脱敏说明：文章隐藏真实商户、门店、SN、Key、AppID、账号和项目路径。保留品牌名、技术表关系、接口类型和故障机制。
一、背景：系统为什么会逐渐变成“多品牌打印平台”
餐饮系统的打印并不是单一设备能力：不同门店可能采购不同品牌云打印机，同一门店又可能配置顾客联、厨房联、标签打印、自动打印和手动补打。随着品牌增加，系统逐渐形成了“门店设备配置 + 打印规则 + 模板 + 第三方品牌接口”的多层结构。
图 1：多品牌打印体系总体架构
二、核心数据模型：打印机不是挂在小程序上，而是挂在门店上
打印机最终通过merchant_id绑定门店。一个小程序可以有多个门店，但门店之间不会自动共享打印设备。这样符合实际部署：同一品牌同一小程序下，不同物理门店仍然有各自的 SN、密钥、打印联数和业务规则。
图 2：打印配置逻辑 ERD
| 表 | 职责 |
|---|---|
| jy_merchant_printer | 打印机设备主表：门店、名称、SN、密钥、品牌、模式、内容类型、联数、状态等 |
| jy_merchant_printer_config | 打印业务规则：外卖/自取/堂食、顾客联/厨房联、打印份数等 |
| jy_printer_config | 打印机与打印规则的关联 |
| jy_merchant_printer_template | 门店/商家侧自定义打印模板 |
| jy_printer | 系统支持的打印平台及平台级配置 |
设备表中几个字段承担了运行时路由职责：printer_type决定走哪个品牌适配；printer_mode区分手动/自动；content_type区分小票/标签；custom_num、kitchen_num控制顾客联和厨房联数量。
三、品牌接入：一套业务动作，五套设备语义
图 3：品牌适配矩阵
| printer_type | 品牌 | 本次材料明确确认的删除能力 |
|---|---|---|
| 1 | 飞鹅云 | 调用 Open API，删除设备列表 |
| 2 | 易联云 | 通过 yly SDK 调 deleteprinter |
| 3 | 中午云 | 未发现第三方删除调用，仅本地删除 |
| 4 | 芯烨云 | 调用 XPrinter delPrinters |
| 5 | 优声云 | 未发现第三方删除调用，仅本地删除 |
本次材料没有完整给出五个品牌“打印下发”时各自的第三方 endpoint。因此本文只确认：系统运行时会按品牌做适配，而具体打印 endpoint 不做推测。删除接口则有明确源码证据。
四、调用链：客户端不直接对接打印云
平板端删除打印机时，只调用老系统自己的/canteen/printer/delPrinter，参数是本地打印机 ID。真正选择第三方接口的是后端打印服务。这个模式的好处是客户端不需要知道飞鹅、易联、芯烨各自的鉴权和 API 差异。
平板 / 商家端 ↓ POST /canteen/printer/delPrinter { "printer_id": "..." } ↓ PrinterService ↓ 读取 jy_merchant_printer.printer_type Provider-specific API ↓ 本地软删除 jy_merchant_printer ↓ 删除 jy_printer_config 关联五、模板体系：为什么模板和品牌适配必须分层
图 4：模板渲染链路
模板解决的是“订单数据如何排版”，品牌适配解决的是“渲染后的内容如何提交给某个云打印平台”。这两层如果混在一起，每新增一种打印机都会复制一套订单排版逻辑。
在此前实际调试芯烨云模板时，模板已经表现出明显的“打印 DSL”特征，例如居中、换行、表格列宽、行高以及循环占位符。
<C>--------------------------------<BR></C> <C>商品明细<BR></C> <C>--------------------------------<BR></C> <TABLE col="20,6,6" w=1 h=2 b=0 lh=120> <tr>品名<td>数量<td>金额</tr> {#items} <tr>{goodsName}[{goodsSpecName}] {#addons} [+{addonName}x{quantity}]{#endAddons} <td>X{quantity} <td>{totalPrice} </tr> {#endItems} </TABLE>其中，实际调试过的两个典型问题是：一，加料不能每个 addon 单独占一行，否则小票会非常长，所以把加料汇总到商品主行；二，lh是 TABLE 行高调节的重要参数，表头和商品区应分别选择更合适的行高。标题区域使用多个<BR>时，高度也会被默认换行撑大。
这部分模板语法来自此前对芯烨云实际模板的调试经验；本次附件只确认系统存在jy_merchant_printer_template，没有展开完整模板解析器实现。
六、Troubleshooting：删除打印机为什么是当前最明显的架构缺口
图 5：删除打印机的一致性问题
Symptoms
从用户视角看，删除打印机可能提示成功；但第三方平台上设备并不一定真的已经解绑。之后重新添加同一 SN 时，可能再次遇到“设备已绑定”等问题。
Investigation
不同品牌的删除路径不一致：部分品牌有第三方解绑 API，部分品牌源码中没有；更关键的是，即便第三方删除失败，当前后端仍可能继续把本地打印机标记为删除。
Root Cause
本地设备生命周期和第三方设备生命周期没有被当作一个需要收敛的一致性流程。当前逻辑更接近“尽力调用第三方，然后无条件收尾本地状态”。
Resolution / 建议
删除应改成显式状态机：ACTIVE → UNBINDING → UNBOUND → DELETED。只有第三方明确成功或确认“设备本就不存在”时，才进入本地 DELETED；网络错误、平台异常则保留为 UNBIND_FAILED，并提供重试。
Verification
删除成功的验收不应该只看本地del=1，还应验证第三方平台设备状态、规则关联是否清理、重新绑定是否成功，以及是否留下可审计的请求/响应证据。
七、另外两个需要优先修复的问题
| 问题 | 风险 | 建议 |
|---|---|---|
| 第三方响应未严格判断 | 第三方失败但本地显示删除成功，造成状态漂移 | 统一 ProviderResult，明确 success/code/message/requestId |
| 类型 3 / 5 无第三方解绑 | 本地删了但平台仍占用设备 SN | 确认平台是否支持解绑；不支持则明确标记 MANUAL_UNBIND |
| 删除缺少门店归属校验 | 知道 printer_id 可能操作其他门店设备 | 删除前校验当前用户/员工与 merchant_id 的关系 |
| 品牌逻辑散落在 if/switch | 品牌越多越难维护 | 建立 PrinterProviderAdapter 接口 |
八、目标架构：Provider Adapter + Template Engine
图 6：建议的目标打印架构
长期建议把系统拆成三个核心概念：Print Orchestrator、Template Engine、Printer Provider Adapter。业务层只提交统一的打印任务；模板引擎负责把统一订单模型渲染成品牌需要的内容；Provider Adapter 负责 add/delete/print/status 等品牌 API。
interface PrinterProvider { ProviderResult addDevice(DeviceConfig config); ProviderResult deleteDevice(DeviceConfig config); ProviderResult print(PrintPayload payload); ProviderResult queryStatus(DeviceConfig config); } PrintOrchestrator ├─ resolve store printers ├─ match print rules ├─ render template ├─ dispatch provider ├─ persist task result └─ retry / manual reprint九、为什么需要打印任务表，而不是只“调接口”
云打印最大的运维问题通常不是“接口完全失败”，而是调用结果处于灰色状态：超时不代表平台没有收到，平台收到也不代表设备实际出纸。如果没有打印任务记录，漏打和重复打印都很难还原。
| 建议字段 | 作用 |
|---|---|
| task_id / idempotency_key | 防止同一业务单被重复创建打印任务 |
| merchant_id / printer_id / provider | 明确打印目标和品牌 |
| template_id / template_version | 知道当时用了哪个模板 |
| request_payload_hash | 核对打印内容是否变化 |
| provider_request_id | 关联第三方平台日志 |
| status | PENDING / SENT / SUCCESS / FAILED / UNKNOWN |
| retry_count / last_error | 自动重试和人工排障 |
| created_at / printed_at | 审计与耗时分析 |
十、模板工程化建议
| 当前痛点 | 工程化改进 |
|---|---|
| 模板靠人工试行高、列宽 | 增加模板预览器和常用纸宽预设 |
| 中文商品名很长 | 模板渲染层提供自动换行和列裁剪 |
| addons 逐行导致票据过长 | 统一支持 addon inline / multiline 策略 |
| 标题区 BR 造成高度难控 | 提供 section spacing 配置，不直接依赖换行符堆叠 |
| 品牌模板语法不同 | 统一业务模板模型，品牌层负责转换 |
| 模板改动无法追溯 | template_version + 发布状态 + 回滚 |
| 线上调模板容易影响门店 | 增加测试打印机/测试订单预览模式 |
十一、5 Whys：为什么多品牌打印最后越来越难维护
| Why | 回答 |
|---|---|
| 为什么新增品牌越来越麻烦？ | 设备字段、API、模板语法、状态返回都不一样。 |
| 为什么业务代码会感知这些差异？ | 品牌适配没有完全封装，printer_type 判断容易散落。 |
| 为什么删除问题容易出现本地/第三方不一致？ | 缺少统一设备生命周期和 ProviderResult。 |
| 为什么模板调试成本高？ | 模板 DSL 缺少预览、版本和结构化校验。 |
| 根因 | 系统已经从“接一台云打印机”成长为“多 Provider 打印平台”，但抽象层仍停留在早期集成方式。 |
十二、Lessons Learned
1. 打印机应该绑定物理门店，而不是小程序。这是当前模型里合理的一点，符合真实设备部署边界。
2. 品牌差异必须关在 Adapter 里。业务层不应该知道飞鹅、易联、芯烨各自 endpoint。
3. 模板不是字符串配置，而是一套 DSL。既然已经出现循环、表格、行高、占位符，就应该有版本、预览和校验。
4. 第三方成功和本地成功是两个状态。删除、添加、打印都需要显式处理最终一致性。
5. “接口返回成功”不等于“纸已经打出来”。打印系统必须保留任务证据链，才能处理漏打和重复打印。
6. 权限校验不能只靠 printer_id。任何设备操作都必须验证当前操作人对目标门店的权限。
十三、后续改造优先级
| 优先级 | 事项 |
|---|---|
| P0 | 修复 delPrinter 的门店归属权限校验 |
| P0 | 第三方删除结果必须判断；失败时禁止直接本地软删除 |
| P0 | 确认中午云/优声云真实解绑能力，补齐或标记人工解绑 |
| P1 | 抽象 PrinterProviderAdapter，收口 printer_type 分支 |
| P1 | 建立 print_task / device_operation_log，保存请求、响应、状态和重试 |
| P1 | 模板版本化 + 预览器 + 测试打印 |
| P2 | 统一业务打印模型，减少品牌模板重复 |
| P2 | 建设设备健康巡检：在线状态、最后成功打印、连续失败次数 |
十四、总结
这套系统已经不再只是“支持几个打印机品牌”，而是具备了打印平台的雏形：设备按门店管理、规则控制打印场景、模板控制内容排版、品牌 API 负责设备和任务落地。真正需要补的，是把这些能力从“代码里能跑”提升到“架构上可维护、状态上可解释、故障后可恢复”。
未来新增第六、第七个品牌时，理想状态应该是：新增一个 Provider Adapter、配置品牌能力、必要时增加模板转换，而不是再次修改订单、门店、删除、补打等多个业务流程。
一句话总结：多品牌打印的核心不是“多写几个 API”，而是把设备生命周期、模板渲染和第三方调用拆成三个可独立演进的层。
