feat:打印优化

2026-09-22 13:29:10 +08:00
1 parent 22c4d4b9b9
commit 383ea2ad4b
@@ -0,0 +1,39 @@
+# 打印方式声明(终端固定图片打印)+ 服务端跳过 printCmd 生成
+
+## 背景结论(已探明)
+
+- 终端固定图片打印,`printCmd` 只落库不消费;服务端每次生成 ESC/POS Base64 指令流是纯浪费:`hard_invoice.print_cmd` mediumtext 写库 + MQTT 消息体膨胀(服务端每 10s 重发未确认消息,膨胀被放大,日志实测单条消息 2-4KB Base64)+ `/printer/tasks`、`/printer/records` 响应膨胀。
+- 服务端目前**没有**"打印方式"概念;`imageMode`(GS_V0/ESC_STAR)是图片栅格指令格式,不是打印方式开关。
+- 终端 printCmd 链路已全部可空安全(`_addTask` 归一 null、出纸只用 pic),服务端不生成对终端**零影响**;基线 biz_supermarket_cloud 同样只用 pic,无需改动。
+
+## 方案(已拍板:print_mode 默认 IMAGE,上线立即停止生成 printCmd)
+
+### A. 后端 biz-api-cloud-zax
+
+1. **迁移脚本** `db/20260922_add_hard_printer_config_print_mode.sql`(跟随 20260920 脚本的 plain ALTER 风格):
+   `ALTER TABLE hard_printer_config ADD COLUMN print_mode varchar(16) NOT NULL DEFAULT 'IMAGE' COMMENT '终端打印方式: IMAGE 图片打印(默认) / CMD 指令打印';`
+2. `HardPrinterConfigEntity`(+对应 mapper,按现有注解/XML 方式)加 `printMode`;`defaultConfig()` 补 IMAGE;bootstrap 返回自动带出。
+3. `HardPrinterInfoReportDto` 加可选 `printMode`(仅允许 IMAGE|CMD);`printerModel/usbVendorId/usbProductId` 放宽为可选(null=保持不变),要求至少一个字段非空——支持"仅上报模式"的部分更新,旧终端全量上报完全兼容。
+4. `HardPrinterServiceImpl.reportDeviceInfo` 改为按非空字段合并(现状只覆盖型号/VID/PID)。
+5. 管理端 `saveConfig` 校验并允许保存 printMode(IMAGE|CMD)。
+6. **生成门控**(核心):`HardInvoiceServiceImpl.generateTaskImage` 按 task 的 printerHardId 读打印机配置,`printMode == IMAGE`(缺失按默认 IMAGE)时只走 `ThermalReceiptImage` 图片通道、`printCmd` 落 null;CMD 才走现有 `CompositeRenderer` 双通道。`renderInvoice`/`renderVoucher` 增加渲染通道参数。
+7. MQTT 消息、`/printer/tasks`、`/printer/records` 的 printCmd 自动为 null,载荷变小的收益顺带缓解 10s 重发洪水。
+8. 存量 `hard_invoice.print_cmd` 数据不动(可选 DBA 后续清理,不在本次)。
+9. 测试:`HardInvoiceServiceImplTest`(IMAGE→printCmd 为 null、CMD→生成)、`HardPrinterServiceImplTest`(部分更新/取值校验);`mvn -pl pjcloud-hardware/pjcloud-hardware-biz -am test` 验证。
+
+### B. 终端 biz_xfj_cloud
+
+1. **设置→打印机**"后台打印配置"组新增"打印方式"行(复用 `SettingInfoRow` 风格 + 自定义选项芯片):`图片打印`(选中态)/`命令打印`(置灰 + "暂不支持"角标),**不可切换**;数据源 `SysSetting.printerOutputMode`(复用现有字段,`updatePrinterBinding` 从 bootstrap 的 `printerConfig.printMode` 解析,默认 IMAGE)。
+2. `PrinterInfoReportRequest` 加 `printMode`(默认 'IMAGE'),设置页"上报当前设备"时携带。
+3. **能力自动上报(自愈)**:`pullPendingTasks` 中 `updatePrinterBinding` 之后,若服务端 printMode ≠ IMAGE,`unawaited` 上报仅 `printMode:'IMAGE'`(部分更新)。当前构建固定图片打印是硬事实,可纠偏管理端误配;仅在不一致时触发,频率受补拉时机天然限流(登录/MQTT 重连/网络恢复/每 10 分钟/打印等待启动)。
+4. 更新 `SysSetting.printerOutputMode` 注释(从"兼容保留"改为"打印方式展示与服务端能力上报源,固定 IMAGE")。
+
+### C. 跨项目合规
+
+- 基线 biz_supermarket_cloud 同为图片打印且不消费 printCmd,服务端置空无影响,不改基线。
+- 表结构变更仅新增一列(用户已授权),不改任何现有列。
+
+## 验证
+
+- 后端:`mvn -pl pjcloud-hardware/pjcloud-hardware-biz -am test`(涉 mqtt-api 不改则不构建)。
+- 终端:`fvm flutter analyze` + 相关单测;构建装机后:设置页出现"打印方式=图片打印"行;支付一单,logcat 中 MQTT PRINT 消息体明显变短(无 printCmd 字段),发票照常打印。