2.7 KiB
2.7 KiB
Context
The August backend change is intentionally compatible at the HTTP surface: the two C端 payment creation paths remain unchanged, while merchant selection and retry semantics move to a stricter merchant-pool policy. The H5 client already has separate WeChat, Alipay, and wallet result handling, submit guards, and post-payment status refreshes; this change must tighten creation-attempt boundaries without changing those payment contracts.
Goals / Non-Goals
- Goals: make one accepted user submission correspond to one payment-creation attempt; prevent client-side merchant failover and duplicate creation; preserve backend error semantics; keep status reconciliation read-only.
- Goals: make the attempt-count implication explicit so UI retries and polling do not silently exceed payment limits.
- Non-Goals: changing endpoint paths, adding merchant credentials/IDs to the client, redesigning payment pages, or changing WeChat/Alipay payment invocation contracts.
Decisions
- Decision: merchant selection is opaque to the client. The client sends the documented request payload and never chooses or rotates a merchant.
- Decision: classify an API-declared pre-order failure as terminal for that attempt. The UI reports the backend error and exits the submit flow.
- Decision: classify timeout/network interruption as unknown rather than failed-success. The client does not create a replacement payment automatically; it refreshes status where supported and leaves any retry to an explicit user action.
- Decision: status polling and page refresh use read-only order/recharge queries. They must not call either payment creation endpoint.
- Decision: treat every invocation of a payment creation endpoint as an attempt for quota/count semantics, regardless of the eventual payment result.
Risks / Trade-offs
- A user may need to retry manually after a transient network problem. This is intentional to avoid duplicate payment creation; provide clear “check status/retry” feedback.
- A delayed backend result can leave the UI temporarily indeterminate. Reconciliation through existing status APIs reduces this risk without creating another payment.
Migration Plan
- Audit API adapters and all payment callers for hidden retries or merchant parameters.
- Add/adjust terminal and unknown-result branches while retaining existing result handlers.
- Verify read-only status refresh and submit guards across package and wallet flows.
- Roll back the client branch if backend rollout is delayed; endpoint contracts remain backward compatible.
Open Questions
- Which order/recharge status endpoint and polling window should be used for an unknown creation result in each deployment environment?