# 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 逐条核对。