API Contracts: 商家 ezPay 发票开通管理

Phase: Phase 1 — REST 接口契约 Date: 2026-06-15

平台后台接口走若依鉴权 @PreAuthorize("@ss.hasPermi('chanting:storeEzpay:*')")；商家端接口走 @Auth+JWT。返回统一 AjaxResult/TableDataInfo。

一、平台后台（PosStoreEzpayController，`/system/storeEzpay`）

1. 列表（分页 + 筛选）

GET /system/storeEzpay/list

参数	类型	说明
pageNum / pageSize	int	分页
ezpayStatus	int	可选：0未申请/1申请中/2已开通；不传=全部（含免用）
invoiceExempt	int	可选：0需开票/1免用发票
quickFilter	string	可选：`notEnabled`=还没开通、`needApply`=还要去开通
posName	string	可选：门店名模糊
isStall	int	可选：0店铺/1摊位

返回 TableDataInfo，每行含：门店基础信息（id/posName/userId/userName/isStall/invoiceExempt）+ ezPay 信息（ezpayStatus/isEnabled/ubn/merchantId 是否已填/applyTime/approvedTime/lastVerifyResult）。无 ezPay 行的门店 ezpayStatus 视为 0。

2. 详情

GET /system/storeEzpay/{storeId} → AjaxResult，门店 + ezPay 配置（凭证字段是否回显由权限决定，建议列表/详情回显，敏感字段不下发商家端）。

3. 发起申请（0→1）

PUT /system/storeEzpay/apply/{storeId}

前置：ezpay_status=0；建议校验 ubn 已填（未填则提示商家先补统编）。
效果：ezpay_status=1、apply_time=now。

4. 录入凭证并验证（→2）

PUT /system/storeEzpay/saveCredentials

{ "storeId": 123, "merchantId": "3482911", "hashKey": "...", "hashIv": "...", "companyId": null }

后端：构造 EzPayConfig → 调 EzPay.doPost(BASE_TEST + URL_SEARCH, cfg, {假发票号+随机码})。
判读：回应含 KEY1xxxx → 凭证无效，保持 status 不变，last_verify_result 记错误码，返回 error（含中文说明）。回应业务错误或成功 → ezpay_status=2、is_enabled=1、approved_time=now、保存凭证、last_verify_result 记通过。
网络异常：返回 error 可重试，不改状态。

5. 切换启用开关

PUT /system/storeEzpay/toggleEnable/{storeId}

前置：ezpay_status=2。翻转 is_enabled（1↔0）。返回新状态。

6. 标记/恢复免用发票

PUT /system/storeEzpay/markExempt/{storeId}

{ "invoiceExempt": 1 }   // 1=免用发票, 0=恢复需开票

效果：更新 pos_store.invoice_exempt。免用后该门店退出待办过滤（已有 ezPay 行保留）。

7. 重置状态（可选）

PUT /system/storeEzpay/reset/{storeId}

将 ezpay_status 回退到 0 或 1（凭证作废/重新申请场景），清 approved_time。

二、商家端（上传统编）

挂在门店设置流程。两种实现选一（实现时定）：

方案 A（推荐，最少改动）：复用 POST /chanting/store/addmendian（已 saveOrUpdate 整个 PosStore）——前端门店表单加"统一编号"字段，提交时一并写入 pos_store_ezpay.ubn（后端在保存门店时 upsert ezPay 行的 ubn）。

方案 B：新增 POST /chanting/store/saveUbn { storeId, ubn }，仅商家本人门店（JWT 校验 storeId 归属）。

无论哪种：商家端只能写 ubn，不能改 ezPay 状态/凭证/免用标记。

三、权限菜单

新增菜单/权限键（写入 sys_menu，SQL 进 updatesql/sql.md）：

chanting:storeEzpay:list / :query / :apply / :saveCredentials / :toggleEnable / :markExempt / :reset

四、错误约定

场景	HTTP	业务码/消息
凭证金钥错误	200	error，`last_verify_result` 记 KEY1xxxx，消息"ezPay 凭证无效，请检查 HashKey/HashIV"
验证网络超时	200	error，"ezPay 验证服务暂不可用，请稍后重试"，状态不变
非法状态迁移	200	error，"当前状态不允许此操作"
商家越权改门店	200	error，"无权操作该门店"

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