feat(aftersale): per-line refund/return flow with ledger-backed completion (add-aftersale-refunds)

2026-09-23 16:56:30 +08:00
parent 93e5a05d48
commit 2c2b54c21c
43 changed files with 4889 additions and 32 deletions
@@ -2,9 +2,7 @@

 ## Purpose
 Checkout splitting a cart into per-shop orders, plus order lifecycle and ownership.
-
 ## Requirements
-
 ### Requirement: Checkout splits by shop
 `POST /api/orders/checkout` SHALL create one order per distinct shop in the cart, in a single database transaction: stock decrement, order + item insert with price snapshots, cart clear, active flash-sale resolution when no group-buy intent applies to the SKU, requested group-buying intent validation, and requested coupon redemption when eligible. All amounts use the cart's SKU currencies converted into the buyer-chosen display currency at checkout time. A group-buy intent SHALL contain exactly one active activity SKU at quantity 1 and either an open group identifier or a request to open a group; the server SHALL snapshot the group price and group identity on the resulting pending-payment order. Group intent SHALL return 409 when that SKU is also eligible for an overlapping flash sale. For each remaining cart line without group intent the server SHALL resolve an eligible active flash-sale item as specified by flash-sales, snapshot the final unit price and activity identity, and charge standard price for ineligible quantity. The request MAY select at most one owned coupon per generated shop order; the server SHALL persist `coupon_id`, `discount_minor`, and post-discount `total_minor` only after ownership, shop, status, window, and threshold validation. The client SHALL NOT provide a discount amount. The server SHALL reject a coupon (409) for any shop order that applied flash-sale pricing or carries group-buy intent.

@@ -65,3 +63,30 @@ Customers SHALL see only their own orders; shop roles only their shop's orders;
 #### Scenario: cross-customer read denied
 - **WHEN** customer X requests customer Y's order id
 - **THEN** the API returns 404
+
+### Requirement: Order aftersale eligibility and refund summary
+Order and order-item responses SHALL expose the configured after-sale deadline after confirmation of delivery, whether each line has an active aftersale, its remaining refundable integer minor-unit amount, and the order's authoritative `refund_total_minor`. The API SHALL allow applications for paid or shipped orders while the configured window is open, and SHALL reject new applications after the deadline. The refund summary SHALL be sourced from completed `aftersales` records and updated only by a guarded refund-completion transaction.
+
+#### Scenario: confirmed order remains eligible during the window
+- **WHEN** a customer views a completed order before the configured N-day after-sale window expires
+- **THEN** the order detail includes an after-sale deadline and each refundable line exposes its remaining amount and application action
+
+#### Scenario: expired window hides the action
+- **WHEN** the configured after-sale deadline has passed
+- **THEN** the order and item responses mark after-sale unavailable and an application returns 409
+
+#### Scenario: order refund total is authoritative
+- **WHEN** an aftersale completes a refund
+- **THEN** the order response's `refund_total_minor` equals the sum of completed aftersale amounts and is not client-calculated
+
+### Requirement: Order item ownership and state safety
+After-sale eligibility SHALL resolve the order item through the authenticated customer's order ownership (or the owning shop's `own_shop` scope for merchant actions), and every refund total update SHALL use a conditional status/amount guard so concurrent completions cannot refund more than the paid order amount.
+
+#### Scenario: cross-customer item is hidden
+- **WHEN** a customer submits another customer's order item id
+- **THEN** the API returns 404 without disclosing order or refund data
+
+#### Scenario: concurrent refunds stay within paid amount
+- **WHEN** concurrent aftersales would make completed refunds exceed the line or order paid amount
+- **THEN** the guarded update rejects the excess completion and stored refund totals remain within the paid amount
+