vmall/openspec/changes/add-shop-coupons/proposal.md

Why

The mall displays fixed coupon fixtures although checkout has no promotion boundary. Shop-issued coupons are the smallest marketing capability that can use the existing per-shop checkout split without introducing a generic promotion engine.

What Changes

• Add shop-scoped coupon templates with localized content, fixed minor-unit discount, threshold, currency, claim stock, active window, and lifecycle controls.
• Add customer coupon claiming, listing, and a user-held coupon snapshot with claimed/redeemed/expired state and order binding.
• Extend checkout to select at most one eligible coupon for each generated shop order; calculate and persist a server-authoritative discount.
• Record exclusive composition with later activity pricing: a shop order that applies flash-sale or group-buy prices MUST reject a coupon. Later order changes that rewrite checkout SHALL restate coupon redemption, cancellation restore, and this exclusion.
• Add shop-admin template management and replace the mall coupon fixtures with live data, checkout selection, and order-surface discount display.

Capabilities

New Capabilities

• shop-coupons: Shop coupon issuance, customer claims, eligibility, redemption, and cancellation restoration.

Modified Capabilities

• order: Checkout accepts per-shop coupon selections and persists the resulting discount.
• frontend-mall: Coupon surfaces and checkout use the shared live contract.
• frontend-shop-admin: Merchants manage coupons only within their own shop.

Non-goals

Threshold reductions, stacking rules across promotion types, platform coupons, campaign targeting, and voucher transfers are excluded. Activity-priced checkout (flash sales, group buying) is out of this change; those later changes must reject coupons on activity-priced shop orders rather than leave stacking undefined.

Impact

Adds Rust coupon module and migrations, shared types/API/locales, mall and shop-admin screens, and a checkout request/response contract change.