foodie-server/specs/009-ezpay-invoice-onboarding/quickstart.md

Quickstart: 商家 ezPay 发票开通管理

Phase: Phase 1 — 跑通验证步骤 Date: 2026-06-15

1. 准备数据（手动执行 SQL）

到数据库执行 updatesql/sql.md 中 2026-06-15 段落：

• ALTER TABLE pos_store ADD COLUMN invoice_exempt TINYINT(1) DEFAULT 0 ...
• CREATE TABLE pos_store_ezpay (...)
• sys_menu 插入 chanting:storeEzpay:* 权限项

2. 拿 ezPay 测试凭证

在 ezPay 测试环境 https://cinv.ezpay.com.tw/ 申请一个测试商店，记录 MerchantID、HashKey（32 字节）、HashIV（16 字节）。（线下，人工）

3. 后端验证

1. 启动 foodie_server（ruoyi-admin）。
2. 平台后台登录，进入"ezPay 发票开通管理"。
3. 选一个测试门店（pos_store 里普通店铺或摊位）：
   • 点"发起申请" → 状态变 申请中。
   • 点"录入凭证"填入第 2 步的真凭证 → 点"验证并开通"：
     • 凭证正确 → 状态变 已开通、启用，approved_time 写入。
     • 故意填错 HashKey → 提示"ezPay 凭证无效"，状态保持 申请中，last_verify_result 记 KEY1xxxx。
4. 点"停用"/"恢复" → 启用开关翻转，状态仍 已开通。
5. 点"标记免用发票" → 该门店从"还要去开通/还没开通"过滤消失。

4. 商家端验证

1. 商家端登录，进门店设置，填"统一编号"保存。
2. 回平台后台该门店，确认 ubn 已显示。

5. 单元测试

PosStoreEzpayServiceImpl 验证判读逻辑（mock EzPay.doPost）：

• 回应 Status!=成功 且含 KEY1 → 返回"凭证无效"，status 不变。
• 回应业务错误（发票不存在）或成功 → 通过，status=2。

6. 验收对照

回到 spec.md 的 SC-001 ~ SC-006 与各 User Story 的 Acceptance Scenarios 逐条核对。