james
82c1e8e4bb
Sync the points-mall capability plus the frontend-mall and frontend-admin requirements into the main specs, and write the capability Purpose the archive leaves as a placeholder.
2.3 KiB
points-mall Specification
Purpose
Offer a platform-owned catalog of rewards a customer can redeem for loyalty points, with its own order lifecycle kept separate from cash orders and merchant SKU inventory. Redemption reserves product stock, debits the points ledger atomically with the order as reference, and snapshots the product and shipping address; platform operators publish the catalog and move redemptions to fulfilled or cancelled.
Requirements
Requirement: Platform points product catalog
Platform admins SHALL create, update, publish, unpublish, and list points products with localized user-facing content, integer points price, stock, images, and recommendation order. Customers SHALL discover only published products.
Scenario: unpublished product is unavailable
- WHEN an admin unpublishes a points product
- THEN customers cannot discover or redeem it
Requirement: Atomic points redemption
An authenticated customer SHALL redeem a published points product using a quantity and shipping address. The server SHALL atomically validate stock, debit points through customer accounts, create a redemption order with immutable product and address snapshots, and decrement stock.
Scenario: insufficient points
- WHEN a customer redeems a product costing more points than available
- THEN the API returns 409 and creates no redemption order or stock change
Scenario: final stock contention
- WHEN concurrent redemptions request the final product stock
- THEN only requests covered by stock succeed and no negative stock is stored
Requirement: Redemption history and fulfillment
Customers SHALL list only their redemption orders. Platform admins SHALL list redemption orders and transition pending fulfillment to fulfilled or cancelled with validated current status. Demo seed SHALL credit points through customer accounts so at least one published product can be redeemed in the live mall.
Scenario: fulfill redemption
- WHEN a platform admin fulfills a pending redemption order
- THEN its status becomes fulfilled and the customer sees that status in history
Scenario: seeded points are spendable
- WHEN a seeded demo customer with a seed ledger credit redeems an in-stock published product they can afford
- THEN the redemption succeeds and the points summary decreases by the product price