foodie-server/specs/010-order-invoice/spec.md

Feature Specification: 订单 ezPay 电子发票开立

Feature Branch: 不新建分支（在当前 test 分支开发）

Created: 2026-06-16

Status: Draft

Input: User description: "订单完成后客户要开发票（ezPay 电子发票开票）。基于已完成的 009-ezpay-invoice-onboarding（门店 ezPay 开通管理 + 凭证录入），复用已有 EzPay 开票工具类，在订单完成时为已开通且启用的门店开立电子发票。不创建分支，在当前 test 分支开发。"

User Scenarios & Testing (mandatory)

User Story 1 - 客户在订单完成后申请个人电子发票 (Priority: P1)

客户下单并在订单完成后，可在订单详情发起开票，选择开立个人（B2C）电子发票并填写接收邮箱；系统通过门店已配置的 ezPay 凭证即时开立电子发票，返回发票号码与发票查看凭证，客户可查看/下载。仅「已开通且启用」的门店能为客户开票；免用发票门店不提供开票入口。

Why this priority: 这是「客户能开到发票」的核心价值，也是 ezPay 开通管理（009）真正落地的出口。没有它，门店开通 ezPay 没有任何意义。

Independent Test: 对一笔已完成订单（所属门店已开通且启用 ezPay）申请个人发票 → 系统开立成功 → 订单显示发票号、客户可查看发票。

Acceptance Scenarios:

1. Given 订单已完成且所属门店 ezPay 已开通且启用，When 客户在订单详情点「申请发票」、选个人发票并填接收邮箱，Then 系统调 ezPay 即时开立，订单记录发票号与防伪随机码，客户拿到发票查看凭证。
2. Given 订单所属门店为「免用发票」或 ezPay 未开通/未启用，When 客户查看订单，Then 不显示开票入口（或提示该门店暂不支持开票）。
3. Given 订单已成功开票，When 客户再次查看订单，Then 显示发票号与发票链接，且无法再次申请开票。

---

User Story 2 - 客户申请公司（B2B）电子发票并填写统一编号 (Priority: P1)

客户可选择开立公司（B2B）发票，填写公司名称与统一编号（统编，8 码）；系统校验统编格式后调 ezPay 开立三联式发票，发票上印有买方统编。

Why this priority: 外卖/餐饮场景下 B2B 报账是刚需（统编为标配），与个人开票同为核心开票路径。

Independent Test: 对一笔已完成订单选公司发票、填公司名 + 合法统编 → 开立成功 → 发票记录买方统编。

Acceptance Scenarios:

1. Given 订单已完成且门店可开票，When 客户选公司发票并填合法统编（8 码）与公司名，Then 开立成功，发票记录买方统编。
2. Given 客户填了格式非法的统编，When 提交申请，Then 校验失败并提示，不调用开票接口。

---

User Story 3 - 客户选择电子发票载具 (Priority: P2)

客户开立个人发票时，可选择将发票存入载具（手机条码 / 自然人凭证 / ezPay 会员载具）；不选则默认以邮箱接收。

Why this priority: 台湾电子发票的载具是常态体验，但并非「开到发票」的必要前提，属体验增强，故 P2。

Independent Test: 选手机条码载具开票 → 发票存入该载具，不另行印发邮箱 PDF。

Acceptance Scenarios:

1. Given 客户开个人发票，When 选手机条码载具并填条码，Then 校验条码合法后开立，发票存入该载具。
2. Given 客户开个人发票，When 选自然人凭证载具并填凭证，Then 校验后开立，发票存入该载具。

---

User Story 4 - 商家与平台查看订单发票、失败重试 (Priority: P2)

商家在商家端、运营在平台后台可查看订单的开票状态（未开 / 已开 / 失败 / 作废）与发票号；开票失败的订单可由运营重新触发开票。

Why this priority: 运营与商家需要掌握开票情况、处理失败单，但依赖开票主链路先打通，故 P2。

Independent Test: 一笔开票失败的订单，运营在后台点「重新开票」 → 成功后状态变已开。

Acceptance Scenarios:

1. Given 订单曾开票失败，When 运营/商家查看，Then 显示失败状态与失败原因。
2. Given 一笔开票失败的订单，When 运营点重新开票，Then 系统再次调 ezPay 开立，成功则更新发票号与状态。

---

User Story 5 - 商家作废已开立的发票 (Priority: P3)

商家/运营可对已开立的发票发起作废（受台湾法规「奇数月 14 日前可作废前两月发票」限制），作废成功后订单可重新开票。

Why this priority: 作废属售后补救，频率低且有严格时点限制，属辅助功能，故 P3。

Independent Test: 对一张本月开具的发票点作废 → 调 ezPay 作废成功 → 发票状态变作废、订单可重开。

Acceptance Scenarios:

1. Given 一张开立且在可作废期限内的发票，When 商家发起作废，Then 系统调 ezPay 作废，发票标记作废。
2. Given 已超过可作废期限的发票，When 商家发起作废，Then 提示不可作废并说明原因（以 ezPay 作废接口返回为准）。

---

Edge Cases

• 同一订单重复申请开票：已成功开票的订单不允许再次开票（除非先作废）；需防止并发点击产生重复发票。
• ezPay 开票接口网络异常：不开立、订单标记失败、不产生半成品发票；提示稍后重试。
• ezPay 回应业务错误（金额不平、字轨用尽等）：记录错误码与信息，订单标记失败、可重试。
• 客户邮箱/载具填错导致发票无法送达：发票在 ezPay 侧已开立成功，记录发票号，提示客户联系商家；本期不做载体自动更正。
• 订单退款/取消后已开发票：本期不自动作废，由商家按需手动作废（US5）。
• 夜市（userType=3）门店与免用发票门店：不提供开票入口（与 009 一致）。
• 门店 ezPay 被停用（009 toggleEnable 关）：开票时识别为不可开票，提示门店发票功能暂停。

Requirements (mandatory)

Functional Requirements

• FR-001: 系统必须能在订单完成后，允许客户为该订单申请电子发票（仅当订单所属门店 ezPay 已开通且启用）。
• FR-002: 系统必须支持客户开立个人（B2C）电子发票，含接收邮箱，并通过 ezPay 即时开立接口完成开立。
• FR-003: 系统必须支持客户开立公司（B2B）电子发票，含买方名称与统一编号（统编，8 码），并在提交前校验统编格式。
• FR-004: 系统必须在开票成功后记录发票号码、防伪随机码等 ezPay 回应信息并关联到订单，供客户与商家查看。
• FR-005: 系统必须避免同一订单重复开票——已成功开票的订单不允许再次开票，除非该发票已作废。
• FR-006: 系统必须在门店为「免用发票」或 ezPay 未开通/未启用时，不向客户提供开票入口。
• FR-007: 开票失败（网络异常或 ezPay 业务错误）时，系统必须标记订单开票失败并记录原因，不改变订单本身状态，并允许后续重新开票。
• FR-008: 系统必须支持客户选择电子发票载具（手机条码 / 自然人凭证 / ezPay 会员载具）；不选则以邮箱接收。
• FR-009: 商家端与平台后台必须能查看订单开票状态（未开 / 已开 / 失败 / 作废）与发票号；运营可对失败订单重新开票。
• FR-010: 商家/运营必须能对已开立且在可作废期限内的发票发起作废，作废成功后订单可重新开票。
• FR-011: 系统必须复用已实现的 ezPay 开票工具类（开立 / 查询 / 作废），不在本期改动其内部实现。
• FR-012: 商家端、平台后台新增的面向用户文字必须实现四语言（vi / zh / tw / en）国际化；客户端 UI 的 i18n 由客户端团队另行实现，不在本期。

Key Entities (include if feature involves data)

• 订单发票（新增，与订单 1:1）：记录一笔订单的电子发票信息：发票类型（B2C/B2B）、买方名称、买方统编、接收邮箱、载具类型与号码、发票号码、防伪随机码、发票查看凭证、开票状态（未开 / 已开 / 失败 / 作废）、失败原因、申请时间、开立时间、作废时间。
• 订单（已有）：开票的来源；订单完成后可发起开票；一笔订单对应一张有效发票（作废后可重开）。
• 门店 ezPay 配置（009 已有）：开票时读取门店的 ezPay 凭证（商店代号 / HashKey / HashIV），并判断门店是否可开票（已开通且启用）。
• ezPay 加值服务平台（外部）：实际开立 / 作废发票的外部系统，本期通过其开立 / 作废接口与之交互。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 客户对一笔已完成订单，能在 1 分钟内、3 次操作内完成发票申请并拿到发票查看凭证。
• SC-002: 门店为「免用发票」或 ezPay 未开通/未启用时，客户 100% 看不到开票入口（无法发起开票）。
• SC-003: 客户填错统编格式时，系统 100% 在调用开票接口前拦截并提示。
• SC-004: 同一订单不会因重复点击或并发申请产生 2 张及以上发票。
• SC-005: 开票失败（网络或业务错误）的订单，客户/运营可在不改动订单状态的前提下重新开票成功。
• SC-006: 客户、商家、运营三方都能在各自入口查看到同一订单的发票号与开票状态，且一致。

Assumptions

• 「订单完成」由现有订单状态机判定（订单到达可开票的终态），本期不改订单状态机；具体终态口径在实现阶段对齐现有逻辑。
• 开票凭证（商店代号 / HashKey / HashIV）由 009 的门店 ezPay 配置提供；仅「已开通（status=2）且启用（enabled=1）」的门店可开票。
• 复用已实现的 ezPay 工具类（EzPay / EzPayConfig / EzPayEncryptUtil），本期不改其内部。
• 餐饮主走 B2C 即时开立（Status=1）；B2B 需统编；载具为 P2 体验增强。
• 发票作废受台湾法规时点限制，系统以 ezPay 作废接口返回为准判定是否可作废，不在本地做时限计算。
• 客户端前端 UI（订单详情开票入口、发票查看）不在本期实现范围：本期交付后端开票/查询 API（供客户端调用）+ 管理端（商家/平台后台）查看/重试/作废；客户端 UI 及其 i18n 由客户端团队后续对接。
• 本期不含：发票折让、字轨管理、批次开立、发票中奖通知——这些属后续独立功能。
• 捐赠码（LoveCode）不在本期范围：客户开票仅支持载具或邮箱接收，不做捐赠。
• 发票金额不含运费：运费由用户承担（付给配送方），非商家商品收入；商家发票仅就商品销售开立。订单构成 amount = 商品 − 各项优惠 + 运费，故发票金额 = amount − 运费，各类优惠已含在 amount 内无需逐项区分。
• 四语言 i18n 覆盖所有新增面向用户文字，遵循项目既有 i18n 规范。