记录商家代客下单推送与小票打印规则

specs/039-merchant-order-receipt/frontend-app-integration.md

@@ -67,3 +67,21 @@
 - 商品或地址快照损坏会返回业务错误，App 提示错误，不打印空白小票。
 - 本轮未接入自动打印、设备绑定、打印状态回执、去重或补打记录。App 不应把每一次推送都直接当作可重复出纸的命令；新订单触发、重试与设备能力需要后续单独完成。
 - 这里是订单小票，不是电子发票证明联；不返回发票防伪码或打印发票凭证。
+
+## 商家代客下单自动打印触发（2026-11-03 已确认，后端待实现）
+
+| 代客订单支付方式 | 新订单通知与打印时机 |
+|---|---|
+| 现金 `payType=4` | 订单创建事务提交成功后；不用等待确认收款 |
+| 信用卡 `2`、LINE Pay `3`、Apple Pay `5` | 服务端确认支付成功后；创建时不打印 |
+
+以上是本轮新增规则，不代表后端或 App 已上线。到付 `1` 和线下转账 `6` 不纳入本轮现金/线上规则变更。
+
+接入步骤：
+
+1. 监听商家新订单通知。沿用业务内容中的 `ddId`、`type=0`、`pushType=1`；原生新单通知按订单类型附带 `NEW_ORDER_DELIVERY`、`NEW_ORDER_PICKUP` 或 `NEW_ORDER_DINE_IN` 的 `eventScene`。不要把所有 `type=0` 消息都当新单，应结合商家新单消息场景识别，支付成功提示等其他消息不能再次打印。
+2. 用完整 `ddId` 请求本页小票接口，按返回的订单类型、真实付款状态、商品、金额和备注排版。
+3. 按完整订单号协调打印任务并持久化已打印记录；推送重复、消息列表刷新、通知点击，以及创建页本地触发与推送同时到达，都不能重复出纸。多设备需明确由哪个打印终端执行，单设备本地去重不能保证跨设备只打印一次。
+4. 打印失败保留可重试任务，不把收到通知或取到小票数据当作打印成功。用户明确补打与首次自动打印分开处理。
+
+现金创建时 `payStatus=0` 仍可能尚未收款，不能在小票上自动标为“已付款”。通知可能延迟或丢失，App 应保留订单页手动打印入口；本轮后端不提供物理打印成功回执或跨设备打印锁。

specs/039-merchant-order-receipt/plan.md

@@ -16,3 +16,15 @@
 ## 2026-10-30 支付方式文字
 
 小票响应保留支付方式原始码值，新增 `payTypeName`，根据订单已保存的 `payType` 映射为台湾繁体名称。未知或空码值给出「未知付款方式」，不改变支付流程。
+
+## 2026-11-03 商家代客新单推送与小票触发计划
+
+状态：未开始（规则与代码现状已核对，生产代码尚未修改）。规格以同目录 `spec.md` 的本日追加规则为准。
+
+1. `PosOrderShOprateController.createOrder/createOrderChild`：仅对成功保存的商家现金单注册事务提交后通知，复用 `runNotificationAfterCommit` 和 `MerchantNotificationRouter.sendStoreNewOrder`。通知异常不得把已提交订单返回为创建失败；不改变支付或履约状态。
+2. 核对 `LinePayOrderNotificationService`、`OmgPaymentNotifyService` 的首次支付成功路径：商家代客外送、自取、堂食均能收到一次新单；创建未付款不提前通知。现有外送分流优先按 `type=0` 处理，而商家创建单初始 `state=1`，需避免因此漏掉商家提醒。自配送已有商家通知的路径不得再重复发送。
+3. 保持普通用户外送单在骑手接单后通知商家的规则，保留多店批次的统一通知入口；不改骑手派单、取消、退款或开票逻辑。
+4. 先补可复现测试，再完成最小代码改动及注释；覆盖现金提交/回滚、线上创建无推送、首次支付/重复支付和普通订单路由。统一执行 JDK21 定向测试、受影响模块构建和差异检查。
+5. 更新 App 接入说明：通知中的完整 `ddId` 用于读取小票，App 管理打印去重与失败恢复；后端测试不宣称已验证真机打印。
+
+不新增分支、数据库字段、SQL、字典或用户可见文案；复用现有消息国际化和声音场景。当前工作区 `specs/010-order-invoice` 的既有变更与本任务分开保留。

specs/039-merchant-order-receipt/spec.md

@@ -20,3 +20,24 @@
 ## 验收
 
 小票功能无需开关；有效商家可读取授权订单；跨店、普通用户和骑手被拒；普通/多店快照规格保留；无地址、旧运费、免运、积分及其他优惠可正确展示；不产生订单写入或真实打印。
+
+## 2026-11-03 商家代客下单的新单通知与小票触发（已确认，待实现）
+
+本节追加商家代客下单的新单通知范围；原小票数据接口、权限及字段契约保持不变。
+
+### 已确认规则
+
+- 商家代客现金单（`orderSource=MERCHANT`、`payType=4`）：订单创建事务提交成功后发送商家新订单通知，App 收到后获取小票数据并打印。不等待确认现金收款；小票仍按真实 `payStatus` 展示，不把创建成功当成已经收款。
+- 商家代客线上支付单（信用卡 `2`、LINE Pay `3`、Apple Pay `5`）：创建时不发送可触发打印的新单通知；服务端确认支付成功并提交事务后，再通知商家并由 App 打印。不能依据前端支付页面返回认定付款成功。
+- 现金确认收款及线上重复支付回调不重复触发新单打印；事务回滚、支付失败或已取消且进入退款处理的订单不触发新单打印。
+- 通知复用现有门店收件人路由和新单声音规则，覆盖店主、摊主与有权限的分管账号；携带完整子订单号 `ddId`，不使用父单号代替。
+- 外送、自取、堂食按订单类型使用现有新单场景；普通用户创建订单的支付、骑手接单和通知时机不变，多店批次通知规则不变。
+- 本次不新增或改写到付 `payType=1`、线下转账 `payType=6` 的触发规则，不把它们混同于现金 `payType=4`。
+
+### 后端与 App 边界
+
+后端负责符合条件的新单通知及现有 `/getOrderPrintInfo?ddId=...` 小票数据。App 负责接收通知、按订单号防重复、获取数据及驱动已绑定的打印机。仅改后端不代表已经实现真机自动出纸；不修改 App，不新增打印状态表或打印机绑定功能。
+
+### 验收
+
+现金创建提交后通知、提交前不通知、回滚不通知；三类线上支付创建不通知，付款成功后通知；现金确认及重复支付不重复发新单；商家代客外送单不能被普通用户单“等骑手接单”的通知分支漏掉；普通订单和多店通知无回归。App 需另行验证重复通知、创建页本地打印与推送同时到达、打印失败重试及实际出纸。

specs/039-merchant-order-receipt/tasks.md

@@ -28,3 +28,14 @@
 - [x] 小票保留 `payType`，新增台湾繁体 `payTypeName`，覆盖现有六种码值及未知码值。
 - [x] 更新 App 接入说明与规格。
 - [x] JDK21 定向运行 12 项测试，0 失败/错误/跳过；`ruoyi-admin` 模块打包成功。
+
+## 2026-11-03 商家代客下单通知与打印触发
+
+状态：未开始（本轮已记录规格与实现计划，代码及验证待后续执行）。
+
+- [x] T005 记录用户确认的现金创建后打印、线上支付成功后打印规则，并核对当前创建及支付通知入口。
+- [x] T006 更新 App 接入说明，明确后端推送、App 获取小票/去重/驱动打印机的职责。
+- [ ] T007 补充现金创建成功提交后通知；回滚不通知、通知异常不影响已提交订单，添加代码注释。
+- [ ] T008 核对并补齐 LINE Pay/OMG 商家代客订单支付成功的新单通知，避免外送分流漏通知或自配送重复通知，保留普通用户/多店路径。
+- [ ] T009 补充现金提交/回滚、线上创建无通知、付款成功及重复回调、普通订单路由回归测试；运行 JDK21 定向测试、模块构建与差异检查。
+- [ ] T010 前端人员接入 App 自动打印和去重；使用商家 App 与打印设备完成联调和实际出纸验收（非后端代码交付范围）。