Research: 商家 ezPay 发票开通管理

Phase: Phase 0 — 关键技术决策与依据 Date: 2026-06-15

spec 无 NEEDS CLARIFICATION 标记（brainstorming 阶段已与用户确认全部决策）。本文档固化这些决策的"为什么"，供 plan/tasks 与实现阶段参考。

决策 1：ezPay 商店注册不做 API 对接，走线下人工

Decision: 平台不在系统内调用任何"注册新商家/申请商店"接口；运营到 ezPay 官网（测试 cinv.ezpay.com.tw / 正式 inv.ezpay.com.tw）人工完成注册申请，拿到 MerchantID/HashKey/HashIV 后回平台后台录入。
Rationale: ezPay 官方 API（INVI 发票 / 字轨 / BDV 验证 / 批次）不提供注册类接口（见 [[reference-ezpay-invoice-api]]）。注册涉及工商凭证、人工审核，本就不是 API 能完成的。
Alternatives: ①商家自助注册后录入凭证——被否，用户明确"平台代申请（线下）"；②对接 ezPay 开放注册 API——不存在，否。

Decision: 新增表 pos_store_ezpay，与 pos_store 1:1，按门店存一组 ezPay 凭证。不把凭证字段塞进 pos_store。
Rationale: 用户选择"独立关联表"。凭证（HashKey/HashIV）是敏感金钥，独立表便于权限收敛与将来扩展；夜市（userType=3）本身不开票、夜市下摊位门店需开票，门店是正确的开票主体单位。
Alternatives: ①凭证字段直接加到 pos_store——被否，污染主表且金钥混在通用字段中；②按商家账号（InfoUser）绑定——被否，用户明确按门店。

Decision: ezpay_status 0未申请 / 1申请中 / 2已开通；另设 is_enabled 0停用 / 1启用（仅 status=2 有意义）。
Rationale: 用户选"三态+启用开关（推荐）"。"还没开通"= status∈{0,1}；"还要去开通"= status=0；启用开关满足"已开通后临时停用"无需重走申请。
Alternatives: ①只两态——缺"申请中"过程态，运营无法区分已提交待审 vs 未提交；②五态含"已拒绝"——被否，用户选三态，拒绝的门店回归申请中即可。

Decision: 录入凭证点"验证并开通"时，后端用 EzPayConfig(merchantId, hashKey, hashIV) 调 EzPay.doPost(BASE_TEST + URL_SEARCH, ...)，传测试用假发票号+随机码。回应含 KEY1xxxx（加解密/金钥错误）→ 凭证无效、拒绝；回应是业务错误（如发票不存在 INVxxxxx）或成功 → 加密链路通、凭证有效 → 标记已开通。
Rationale: 发票接口（issue/search/invalid）请求只发 MerchantID_+PostData_，不带 CheckValue（见 [[reference-ezpay-invoice-api]] 文档勘误）。而 BDV（checkBarCode/checkLoveCode）需 CheckValue，且其公式官方示例存疑（"接入若校验失败→改 HashIV 在前重试"）。用 invoice_search 能干净地只测金钥对错，不受 CheckValue 不确定性影响，且只读不产生真实发票。业务错误（查不到发票）恰恰证明凭证可解密=有效。
Alternatives: ①checkLoveCode 测试——需 CheckValue，公式不确定，否；②不验证——用户体验差（录错到开票才暴露），用户选"录入时验证"，否。

Decision: pos_store 加 invoice_exempt（0需开票/1免用发票）。该属性决定门店是否纳入 ezPay 流程，并供将来自动开票判断"开票 vs 只开收据"。
Rationale: "免用发票"是门店的通用税务属性（小规模商家/部分摊位），非 ezPay 专属。免用门店根本不需要 ezPay 行，放 ezPay 表语义不通。将来订单完成开票也需读此字段，pos_store 是正确归属（与"凭证放独立表"不冲突——那是 ezPay 专属数据）。
Alternatives: ①放 pos_store_ezpay.need_invoice——免用门店不需 ezPay 行却要建行表达"不需要"，语义别扭；②新建门店税务表——过度设计，YAGNI。

复用现有：EzPay/EzPayConfig/EzPayEncryptUtil（2026-06-15 已实现并经官方数据验证），本期不改其内部，仅业务层调用 EzPay.doPost + EzPayConfig 构造。
若依框架：BaseController/AjaxResult/TableDataInfo/@PreAuthorize/startPage() 分页、@Log 审计、MessageUtils.message() 国际化消息。
前端：Element UI 表格 + 弹窗；vue-i18n 四语言（vi/zh/tw/en），新 key 加到 storeEzpay:{} 对象层级（遵循 [[feedback-i18n-key-naming]]）。