34 lines
2.7 KiB
Markdown
34 lines
2.7 KiB
Markdown
## 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
|
|
|
|
1. Audit API adapters and all payment callers for hidden retries or merchant parameters.
|
|
2. Add/adjust terminal and unknown-result branches while retaining existing result handlers.
|
|
3. Verify read-only status refresh and submit guards across package and wallet flows.
|
|
4. 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?
|