docs: architecture, guidelines, domain designs, progressive code index

2026-09-24 16:59:32 +08:00
parent c532f87b03
commit a968327b12
19 changed files with 728 additions and 0 deletions
@@ -0,0 +1,42 @@
+# Domain: Marketing (coupons, flash sales, group buying, points)
+
+Four activity systems, all shop-scoped where merchant-facing, all resolved
+server-side at checkout.
+
+## Coupons (`modules/coupon/`)
+
+Merchant templates (amount/threshold/window/stock) → customers claim →
+redeem at checkout. Locked in id order during checkout; the discount is
+computed server-side in the order currency. Coupons never combine with
+activity pricing (flash sale / group buying) on the same shop order.
+
+## Flash sales (`modules/flash_sale/`)
+
+Merchant sessions with per-SKU items (activity price + reserved stock).
+Checkout splits a line into activity-priced and normal-priced units; activity
+stock is consumed via guarded decrement. A SKU rejects overlapping
+flash-sale and group-buying activities.
+
+## Group buying (`modules/group_buying/`)
+
+Merchant activity (required members, window, group lifetime). Checkout with a
+group intent takes exactly one unit at the activity price; a seat is claimed
+at payment (`paid_member_count` guarded), groups open/succeed/expire.
+
+## Points mall (`modules/points/`)
+
+Platform-curated catalog; customers redeem with the points account
+(append-only ledger, guarded points decrement), fulfillment/cancellation by
+platform admins.
+
+## Shared rules
+
+- All money integer minor units; activity prices convert to the order
+  currency server-side.
+- All stock/seat counters use guarded `UPDATE … AND col >= $q`.
+- Mall exposes each domain as a mock-adapter-backed live domain
+  (`LIVE_PICKS`); consoles are live-only.
+
+## Key files
+
+See `docs/code_index/marketing.md`.