feat(commerce): B1-2 恢复购买/退款拒付回收/对账真实比对 + Apple 端口预留

为什么:风险清单 R-03 把"票据校验 + 对账打通"列为上线阻塞项。勘察发现 ReconcileService 与
/admin/reconcile 两个接口 B1 之前就已实现,真缺口是:对账没跟商店比对、差额用 0 兜底(违反
"取不到就用 null"的契约)、退款回收只有人工入口且不幂等。按实际缺口做,不重复造。

- 恢复购买:补专项测试(换设备重提同一票据 → 同一订单、原交付时间不改写、不新增流水);
  补单能力沿用 B1-1 的服务端建单路径,恢复列表沿用 GET /app/orders,不新增接口
- 退款/拒付回收:GooglePlayPurchaseClient 增加 listVoidedPurchases(purchases.voidedpurchases,
  带分页);新增 StoreRefundService 拉取并按 (platform, orderId) 幂等回收,本地无单计入差异;
  OrderService 增加 refundByStoreCallback(已退款直接返回,不二次回收/不写第二条流水),
  人工 refund() 的既有契约(已退款报错)保持不变
- 对账:reconcile_task 增 store_amount_sum(可空)与 notes 两列(幂等 ALTER);
  run() 改为集合比对(本地缺票据 + 票据无本地单 + 商店已作废但本地无单),并在同一次 run 里
  顺带执行退款回收;storeAmountSum 恒为 null 并在 notes 说明需从 Play Console 财务报告获取;
  商店调用失败置 status=FAILED 且不写 SUCCESS+0
- Apple IAP:只留端口/枚举与明确提示,不实现真调用(B2 再实现)
- 契约同步 docs/api-phase1.md §1.8/§2.6;新增测试 17 条(commerce 14 + admin-api 3)
- 实测:mvn test 71 条全过(commerce 27 + admin-api 3 + app-api 41,B1-1 的 54 条未被打红);
  两个入口 package 通过;端到端手动对账返回 storeAmountSum=null + notes 说明缺什么
This commit is contained in:
jianghaifeng committed 2026-10-16 11:52:10 +08:00
1 parent db897d50d6
commit 1dc97b4bf6
17 files changed
+971 -21

No files matched your search

+11
View File
@@ -933,3 +933,14 @@ COMMENT ON COLUMN sys_admin_user.must_change_password IS '1 = 首登强制改密
-- 默认 1(超管照旧看到),置 0 表示"不给超管显示"。
ALTER TABLE sys_menu ADD COLUMN IF NOT EXISTS super_admin_visible SMALLINT NOT NULL DEFAULT 1;
COMMENT ON COLUMN sys_menu.super_admin_visible IS '0 = 不给超管显示(角色专属菜单用;超管的菜单是全量兜底,不走 sys_role_menu)';
-- ============================================================
-- 十、B1-2 对账:商店侧指标与说明
-- ============================================================
-- 对账要区分"本地口径"和"商店口径",而商店的结算金额/手续费/税只能从 Play Console 财务报告取,
-- Developer API 不提供。契约强制:**取不到的指标一律 null 并在 notes 说明缺什么,不许用 0 冒充**,
-- 所以这两列必须可空(0 与 null 在对账语境里含义完全不同:0 是"确实是 0",null 是"没有数据源")。
ALTER TABLE reconcile_task ADD COLUMN IF NOT EXISTS store_amount_sum NUMERIC(14,2);
ALTER TABLE reconcile_task ADD COLUMN IF NOT EXISTS notes TEXT;
COMMENT ON COLUMN reconcile_task.store_amount_sum IS '商店侧结算金额;无数据源时为 NULL(不要用 0 冒充)';
COMMENT ON COLUMN reconcile_task.notes IS '对账说明:差异构成、缺哪些数据源、本次退款回收情况';