Implementation Plan: 订单 ezPay 电子发票开立

Branch: test（不新建分支，在当前分支开发） | Date: 2026-06-16 | Spec: spec.md

Input: Feature specification from specs/010-order-invoice/spec.md

Summary

订单完成后客户在客户端主动申请电子发票（B2C 个人邮箱 / B2B 公司统编 / 电子发票载具），系统读取门店 ezPay 凭证（来自 009 的 pos_store_ezpay），复用已实现的 EzPay.issueInvoice 即时开立，将发票号 / 防伪随机码落库到新表 pos_order_invoice（与订单 1:1），客户可查看发票；支持开票失败重试与发票作废。金额按订单商品实付（amount − freight，已扣全部优惠、不含运费）拆分为销售额 / 税额（台湾营业税 5% 内含），逐商品明细取自订单 food JSON，运费不计入发票。客户端开票/查询 API 供客户端团队对接（客户端 UI 不在本期）；商家端、平台后台管理端查看/重试/作废，新增文字四语言 i18n。

Technical Context

Language/Version: Java 17+（Spring Boot，若依 RuoYi 框架；jakarta.servlet、HexFormat 表明 JDK17+）

Primary Dependencies:

后端：Spring Boot、MyBatis-Plus（@TableName/@TableId/LambdaQueryWrapper）+ XML mapper、Apache HttpClient、fastjson2、hutool、若依通用（AjaxResult/TableDataInfo/BaseController/@PreAuthorize）
复用（不改内部）：com.ruoyi.app.utils.ezPay.EzPay（issueInvoice/doPost）、EzPayConfig、ezPayCrypto.EzPayEncryptUtil
复用 009：PosStoreEzpay（门店 ezPay 凭证：merchantId/hashKey/hashIv/companyId、ezpayStatus、isEnabled）、PosStoreEzpayMapper
复用订单：PosOrder（id/ddId/amount/foodAmount/state/payStatus/food 等）、UserOrderController（客户端订单 /system/userOrder）
前端：Vue.js + Element UI（平台后台 foodie-admin-vue、商家端 foodie-store，vue-i18n 四语言）；客户端前端 UI 不在本期，本期交付开票/查询后端 API 供客户端团队对接

Storage: MySQL（新增表 pos_order_invoice，与 pos_order 1:1）

Testing: 轻量单测（开票金额含税拆分 + ezPay 回应判读，mock EzPay.issueInvoice）+ 手测（cinv.ezpay.com.tw 测试环境真凭证开票 / 作废）

Target Platform: Windows 开发 / Linux 部署的 Spring Boot 服务 + Vue 后台/商家端 + 客户端

Project Type: web-service（Spring Boot 后端）+ 多个 Vue / 小程序前端

Performance Goals: 开票调用（含 ezPay 网络往返）< 10s 超时；订单详情接口携带发票状态无显著额外开销

Constraints: 复用 ezPay 工具类不改其内部；不改订单状态机（订单「完成」由现有 state=3 判定）；发票作废以 ezPay invoice_invalid 接口返回为准，不在本地做时限计算；本期不含折让 / 字轨 / 批次 / 中奖通知

Scale/Scope: 1 新表；后端 1 domain + 1 mapper(含XML) + 1 service + 2 controller 域（客户端开票 + 管理端查看/重试/作废）；管理端两前端（平台后台 + 商家端）最小入口；4 语言 i18n ×2 前端

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

.specify/memory/constitution.md 为未填充模板（占位符未替换），项目未定义具体宪法原则与门槛。无实质门槛需评估，设计遵循项目既有约定（若依分层、MyBatis-Plus、全栈字段清单、四语言 i18n、SQL 写 updatesql/sql.md）。Phase 1 后复核：无违反。

Project Structure

Documentation (this feature)

specs/010-order-invoice/
├── spec.md              # 需求规格
├── plan.md              # 本文件（技术方案）
├── research.md          # Phase 0：关键技术决策与依据
├── data-model.md        # Phase 1：表结构、字段、状态机
├── quickstart.md        # Phase 1：跑通验证步骤
├── contracts/
│   └── api.md           # Phase 1：REST 接口契约
├── checklists/
│   └── requirements.md  # spec 质量检查
└── tasks.md             # /speckit-tasks 生成（本期 plan 不创建）

Source Code (repository root)

# ===== 后端 foodie_server =====
ruoyi-system/src/main/java/com/ruoyi/system/
├── domain/
│   ├── PosOrderInvoice.java                 # 新增：订单发票实体（与 pos_order 1:1）
│   ├── dto/ApplyInvoiceDto.java             # 新增：客户申请开票入参
│   └── vo/PosOrderInvoiceVo.java            # 新增：发票列表/详情 VO
├── mapper/
│   └── PosOrderInvoiceMapper.java           # 新增
└── resources/mapper/chanting/
    └── PosOrderInvoiceMapper.xml            # 新增

ruoyi-admin/src/main/java/com/ruoyi/app/
├── order/
│   ├── OrderInvoiceService.java             # 新增：开票/作废/查询业务（注入 EzPay + 订单 + 009凭证）
│   └── UserOrderController.java             # 已有：新增客户端开票接口 /applyInvoice、/getInvoice
├── mendian/
│   └── PosOrderInvoiceController.java       # 新增：管理端（商家+平台）查看/重试/作废 /system/orderInvoice
└── utils/ezPay/                              # 已有，不改内部：EzPay/EzPayConfig/EzPayEncryptUtil

# ===== SQL =====
updatesql/sql.md                             # 追加建 pos_order_invoice 表

# ===== 平台后台前端 foodie-admin-vue =====
src/api/chanting/orderInvoice.js             # 新增：接口封装
src/views/mendian/orderInvoice/index.vue     # 新增：订单发票管理（查看/重试/作废）
src/api/language/{zh_CN,zh_TW,en_US,vi}.js   # 四语言加 orderInvoice:{} key

# ===== 商家端前端 foodie-store =====
门店订单详情                                 # 显示发票状态/号
src/lang/{zh,tw,en,vi}.js                    # 四语言加 key

Structure Decision:

后端遵循既有若依分层：domain/mapper 放 ruoyi-system（被各处依赖）；开票业务 service 放 ruoyi-admin.app.order.OrderInvoiceService，因为它要调用 EzPay（在 ruoyi-admin）+ 读订单 + 读 009 凭证——与 009「ezPay 联网放 Controller、Service 仅持久化」不同，本期开票业务较重，单独 service 更内聚，调用链：Controller → OrderInvoiceService → EzPay.issueInvoice。
客户端开票接口挂在既有 UserOrderController（/system/userOrder）下，与订单详情同域；管理端（商家+平台）查看/重试/作废用独立 PosOrderInvoiceController（/system/orderInvoice，权限键 chanting:orderInvoice:*）。
发票与订单 1:1：pos_order_invoice 当前态表（uk_order_id 唯一约束防重复开票），作废后状态置「作废」允许重开（不开历史明细表，作废记录保留在同一行）。
管理端两前端（平台后台 + 商家端）各自最小入口，严格四语言 i18n；客户端 UI 不在本期。

Complexity Tracking

无宪法违反项，无需填写。

Violation	Why Needed	Simpler Alternative Rejected Because
—	—	—

Enhancement: 发票凭证补全与平台后台展示 (2026-06-22)

背景：开票成功后 invoice_url 实际存的是 ezPay InvoiceTransNo（交易流水号），字段名误导（被当成查看链接）；且 research.md D9 原计划落库的 BarCode/QRcodeL/QRcodeR（发票码图凭证）代码漏存，平台后台详情看不到发票凭证。领域概念澄清见 memory reference-tw-einvoice-concepts。

设计决策（经多轮确认）：

字段改名：invoice_url → invoice_trans_no（语义=ezPay 交易流水号），新增 invoice_bar_code/invoice_qrcode_l/invoice_qrcode_r 三列存发票码值字符串。
开票落库：PrintFlag=Y（B2B / B2C无载具 / B2C邮箱）时 ezPay issue 回应含 BarCode/QRcodeL/QRcodeR，开票成功一并落库；PrintFlag=N（载具发票）这 3 字段为空（合规——载具发票法定不能索取纸本）。
search 对外接口不做：码值开票时已落库，平台后台直接读库；载具发票核对走文案提示（凭发票号+随机码在 ezPay/财政部平台核对）。
平台后台展示（foodie-admin-vue/views/mendian/orderInvoice/index.vue 详情弹窗）：
- 有码值：前端库（qrcode + jsbarcode）渲染左右二维码 + 条码，加「下载 PNG / 打印」按钮（html2canvas / window.print）
- 载具发票（码值为空）：展示结构化信息 + 「已存入买受人载具，无纸本凭证」提示
合规红线不动：不改 PrintFlag 规则、载具与纸本互斥、防一票两份；仅补落库字段与展示。

业务事实约束：ezPay 不返回查看 URL 也不返回图片，只给码值字符串；BarCode/QRcodeL/QRcodeR 仅 PrintFlag=Y 返回（手册 EZP_INVI 第828-850行）。

Enhancement: 捐赠发票(LoveCode) US6 (2026-07-20)

背景：spec.md 新增 US6——客户开票可选「捐赠发票」捐给社福机构。约束详见 memory reference-lovecode-donation：ezPay LoveCode 限 3-7 位（Int(7)，8 位被 CLC10002 拒）、checkLoveCode 只回 IsExist Y/N 不回机构名、捐赠 PrintFlag=N 无码图、载具与捐赠互斥。机构清单来自财政部 CSV（已转 updatesql/pos_love_org.sql，2016 行）。

设计决策：

机构清单 = 手动执行 SQL（不做上传接口/定时拉取）：pos_love_org 表 DDL + 2016 行 INSERT 在 updatesql/pos_love_org.sql，开发者直接 MySQL 执行；CSV 更新后重跑 specs/010-order-invoice/gen_love_org_sql.py 重新生成。>7 位码导入时 enabled=0（本期数据无此类）。
pos_order_invoice 扩展两列（ALTER 写 updatesql/sql.md）：love_code VARCHAR(10)（捐赠码，开捐赠发票时填）、love_org_name VARCHAR(255)（捐赠机构名，开票时从 pos_love_org 快照，便于历史展示）。捐赠发票 invoice_category 仍为 B2C（ezPay 捐赠 = B2C + LoveCode），靠 love_code 非空区分捐赠与普通 B2C。
捐赠机构列表接口（客户端）：GET /system/userOrder/loveOrg/list?keyword=&pageNum=&pageSize= → TableDataInfo of {loveCode, orgName, orgShortName}，仅返回 enabled=1，按 org_name/org_short_name 模糊搜索。挂 UserOrderController（客户端 JWT 鉴权）。客户端据此渲染选择器、选中回填 loveCode。
applyInvoice 捐赠分支：ApplyInvoiceDto 加 loveCode 字段。当 category=B2C 且 loveCode 非空 → 捐赠分支：
- 校验：loveCode 3-7 位数字；carrierType/carrierNum/buyerUbn 必须空（互斥）。
- 机构解析（local-first）：先查 pos_love_org(love_code, enabled=1) → 命中取 org_name 作 love_org_name；未命中 → 调 EzPay.checkLoveCode 验真（IsExist=Y 继续、love_org_name="未知"；IsExist=N 拒「捐赠码无效」）。
- 组装 issue：Category=B2C、LoveCode=码、CarrierType=""、PrintFlag=N、BuyerName=orgName 或「愛心捐贈」、不传 BuyerEmail。
- 开票成功落库：love_code+love_org_name+发票号；码图三列（bar_code/qrcode_l/r）为空（PrintFlag=N）。
checkLoveCode 接入：新增 EzPay.checkLoveCode(baseUrl, cfg, loveCode) 封装 BDV /Api_inv_application/checkLoveCode。已知坑：BDV 请求需 CheckValue，官方手册 CheckValue 公式有勘误（附件三把回应 CheckCode 误标成 CheckValue），按「HashKey 在前」实现，测试环境若校验失败改「HashIV 在前」重试（见 memory reference-ezpay-invoice-api）。仅作 local 未命中的兜底；MVP 可先只走本地清单（2016 家覆盖绝大多数），checkLoveCode 作 P2 兜底。
捐赠发票展示（管理端 + 客户端，客户端 UI 由客户端团队）：捐赠发票码图为空（PrintFlag=N），不能复用个人发票条码模板；详情展示结构化信息 + 「已捐赠给 {love_org_name}」+ 捐赠码。管理端 orderInvoice/index.vue 详情对捐赠发票走「无码图」分支（复用已有载具发票的同类分支）。

范围边界（同 010 既有约定）：交付后端（机构列表接口 + applyInvoice 捐赠分支 + checkLoveCode）+ 管理端展示；客户端选择器 UI 由客户端团队消费接口实现。

文件改动：

后端 entity：PosLoveOrg（新）、PosOrderInvoice 加 loveCode/loveOrgName、ApplyInvoiceDto 加 loveCode、PosOrderInvoiceVo 加 loveCode/loveOrgName
后端 mapper：PosLoveOrgMapper(+XML)、PosOrderInvoiceMapper.xml 加两列
后端 service/controller：OrderInvoiceService（捐赠分支 + loveOrg 列表 + checkLoveCode 接入）、UserOrderController 加 /loveOrg/list、EzPay.checkLoveCode
SQL：updatesql/sql.md 加 pos_order_invoice ALTER 两列（pos_love_org 已在 pos_love_org.sql）
前端：平台后台 orderInvoice/index.vue 捐赠展示 + i18n；商家端订单详情捐赠标识 + i18n

plan.md 13 KB Постоянная ссылка История Исходник