Quickstart: 订单 ezPay 电子发票开立

Date: 2026-06-16

范围：客户端前端 UI 不在本期——开票/查询通过 curl/Postman 调 API（/system/userOrder/applyInvoice、/getInvoice）；查看/重试/作废通过平台后台 UI。客户端团队后续对接 UI。

手测验收步骤（项目无强制 TDD，按此手测 + 可选单测）。前置：009 已上线（门店 ezPay 已开通启用 + 凭证录入）。

0. 准备

执行 updatesql/sql.md 中 010 段落（建 pos_order_invoice 表 + 菜单权限）。
选一个已完成订单：pos_order.state=3、pay_status=1，其所属门店在 009 中 ezpay_status=2 且 is_enabled=1、invoice_exempt=0。
ezPay 测试环境 cinv.ezpay.com.tw 的商店代号/HashKey/HashIV 已通过 009 录入验证。

1. B2C 个人发票（邮箱）— US1 / SC-001 / SC-004

客户端调 POST /system/userOrder/applyInvoice：{orderId, category:"B2C", buyerName, buyerEmail}。
预期：返回 invoiceNumber + 凭证；DB pos_order_invoice.invoice_status=1、invoice_number 已填、total_amt/sales_amt/tax_amt 三栏自洽（sales+tax=total）。
重复开票：再调一次 → 拒绝（已开票），SC-004 通过。

2. B2B 公司发票（统编）— US2 / SC-003

applyInvoice：{orderId, category:"B2B", buyerName:"某公司", buyerUbn:"12345678"}。
预期：开立成功，发票记录买方统编。
非法统编：传 buyerUbn:"12A" → 提交前被拦截、不调 ezPay，SC-003 通过。

3. 载具（手机条码）— US3

applyInvoice：{orderId, category:"B2C", buyerName, carrierType:"0", carrierNum:"/AB1234+"}。
预期：校验条码后开立，发票存入载具（PrintFlag=N）。

4. 不可开票门店 — US1-场景2 / SC-002 / SC-006

对一个免用发票（invoice_exempt=1）或 ezPay 未开通/未启用的门店订单调 applyInvoice。
预期：拒绝并提示门店暂不支持开票；getInvoice 返回 invoiceStatus=null，前端不显示入口。SC-002、SC-006 通过。

5. 开票失败 + 重试 — US4 / SC-005

临时把门店 HashKey 改错 → applyInvoice → ezPay 回 Status≠SUCCESS。
预期：invoice_status=2 失败、fail_reason 记录原因、订单状态不变。
平台后台 PUT /system/orderInvoice/retry/{orderId}（先恢复正确凭证）→ 重试成功，状态变 1 已开。SC-005 通过。

6. 优惠/运费对账 — D1/D3

对一笔带优惠的外送订单开票。
预期：发票 total_amt = amount − freight（不含运费）；优惠按比例分摊到各商品明细，ΣItemAmt = total_amt；运费不出现。
自查：发票总额 < 订单 amount（差额 = 运费）。

7. 作废 + 重开 — US5

平台后台 PUT /system/orderInvoice/invalid/{orderId}（一张本月开具的发票）。
预期：ezPay invoice_invalid 成功 → invoice_status=3 作废、invalid_time 记录。
超期作废：对一张不可作废的发票 → 提示不可作废（以 ezPay 返回为准）。
重开：作废后客户重新 applyInvoice → 生成新 invoice_number。

8. 三端一致性 — SC-006

同一订单：客户端 getInvoice、商家端订单详情、平台后台 list/{orderId} 显示的发票号与状态一致。

验收核对（对照 spec Success Criteria）

SC-001 客户 1 分钟内 / 3 步完成开票拿到凭证
SC-002 不可开票门店 100% 无入口
SC-003 非法统编调用前拦截
SC-004 无重复发票
SC-005 失败可重试成功
SC-006 三端发票号/状态一致