Skip to content

feat(payment): add mobile Alipay precreate deep link#4734

Merged
Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
wjx2951874:feat/alipay-mobile-precreate-deep-link
Jul 23, 2026
Merged

feat(payment): add mobile Alipay precreate deep link#4734
Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
wjx2951874:feat/alipay-mobile-precreate-deep-link

Conversation

@wjx2951874

Copy link
Copy Markdown
Contributor

Summary

  • Add an opt-in ALIPAY_MOBILE_PRECREATE_DEEP_LINK setting for the official Alipay provider.
  • When enabled, mobile checkout creates each order with alipay.trade.precreate, launches the returned dynamic QR URL through the Alipay Scheme, and shows a QR fallback only when launch appears to fail.
  • Keep desktop Alipay QR checkout and the original mobile wap.pay behavior unchanged when the setting is disabled.
  • Expose the setting through the admin payment settings, database defaults, deployment examples, and payment documentation.

Mobile behavior

  • Build alipays://platformapi/startapp?saId=10000007&qrcode=<encoded qr_code> with exactly one encodeURIComponent pass.
  • Try window.location.assign immediately after order creation.
  • Treat visibilitychange, document.hidden, or pagehide as a successful handoff and suppress the failure fallback.
  • Show the fallback after 2200 ms while still visible; use 300 ms for WeChat/QQ embedded browsers that commonly block custom schemes.
  • The fallback includes amount, order number, remaining time, the per-order dynamic QR code, reopen/save actions, instructions, and a return action.
  • Continue server-side status polling every 3 seconds, route to the success page only after a confirmed paid status, and stop polling when the order expires.

Payment integrity

  • Client-side scheme or visibility results never credit an account.
  • Existing server-side signature verification, AppID verification, merchant order lookup, amount comparison, and idempotent fulfillment remain the authority for crediting.
  • Added regression coverage for duplicate completed notifications and mismatched payment/order data.
  • The feature is gated to an enabled, visible official Alipay provider so EasyPay and legacy forced-QR flows retain their prior behavior.

Risk

  • Custom-scheme behavior varies by browser and OS. The timed QR fallback remains available when the browser blocks the handoff.
  • Merchants need official Alipay face-to-face payment capability for alipay.trade.precreate.
  • Enabling the flag adds provider-resolution work while preparing the public checkout configuration.

Verification

  • go test -p=1 -tags=unit ./internal/payment/provider ./internal/handler ./internal/server
  • go test -p=1 -tags=unit ./internal/service -run 'Test(ShouldUseAlipayMobilePrecreate|IsOfficialAlipayProviderInstance|AlipayMobilePrecreateEnvironmentOverride|ParsePaymentConfig|DuplicatePaymentNotificationDoesNotReprocessCompletedBalanceOrder|PaymentNotificationRejectsAmountMismatchBeforeFulfillment)$'
  • go test ./migrations
  • go test -tags=integration ./internal/repository -run '^$' (applied migrations 185 and 186 against temporary PostgreSQL/Redis)
  • go vet ./internal/payment/provider ./internal/handler ./internal/service
  • pnpm vitest run alipayDeepLink.spec.ts PaymentStatusPanel.spec.ts paymentFlow.spec.ts PaymentView.spec.ts SettingsView.spec.ts (73 tests passed)
  • pnpm vue-tsc --noEmit
  • pnpm run build
  • Full frontend Vitest baseline: 1250 passed; 2 existing failures remain in src/api/__tests__/admin.system.rollback.spec.ts because that test expects two request arguments while the existing implementation supplies a timeout option as the third argument.

Rollback

  1. Set ALIPAY_MOBILE_PRECREATE_DEEP_LINK=false or disable the option in Admin Settings to restore the original mobile WAP flow immediately.
  2. No schema rollback is required; the added setting defaults to false.
  3. Revert this PR if code rollback is required.

No production deployment or production credential changes are included.

@github-actions

github-actions Bot commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

All contributors have signed the CLA. ✅
Posted by the CLA Assistant Lite bot.

@wjx2951874

Copy link
Copy Markdown
Contributor Author

I have read the CLA Document and I hereby sign the CLA

github-actions Bot added a commit that referenced this pull request Jul 22, 2026
@wjx2951874
wjx2951874 force-pushed the feat/alipay-mobile-precreate-deep-link branch from ac259dd to 7914433 Compare July 22, 2026 11:18
@wjx2951874

Copy link
Copy Markdown
Contributor Author

@Wei-Shaw 该 PR 已同步到最新 main,目前无冲突且 CLA 已通过,烦请有空时审核。功能默认关闭,仅在开启 ALIPAY_MOBILE_PRECREATE_DEEP_LINK 且实际路由到官方支付宝实例时,将移动端创建订单切换为 alipay.trade.precreate 并增加 Scheme/二维码降级交互;桌面端与服务端验签、金额/AppID/订单校验、幂等入账逻辑保持不变。相关 Go 单元/迁移测试、前端 73 项定向测试、类型检查和生产构建均已通过,风险与回滚步骤已写入 PR 描述。

@Wei-Shaw
Wei-Shaw merged commit 2c76506 into Wei-Shaw:main Jul 23, 2026
8 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Jul 23, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants