This commit is contained in:
33
openspec/changes/update-payment-routing-policy/design.md
Normal file
33
openspec/changes/update-payment-routing-policy/design.md
Normal file
@@ -0,0 +1,33 @@
|
||||
## 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?
|
||||
Reference in New Issue
Block a user