feat: reward paid members at user growth milestones

2026-06-12 23:52:56 +08:00
parent 33fbf17c18
commit cf35e55da4
13 changed files with 1021 additions and 1 deletions
@@ -0,0 +1,51 @@
+# Growth Milestone Pro Rewards Design
+
+## Goal
+
+Reward active paid Pro members with additional membership time when PolyWeather
+reaches verified-user growth milestones.
+
+## Confirmed Rules
+
+- Growth is measured using verified Supabase Auth users.
+- The historical launch baseline is:
+  - 588 total registered users
+  - 573 verified users
+  - recorded on 2026-06-12
+- Milestones and rewards:
+  - 600 verified users: +1 Pro day
+  - 750 verified users: +2 Pro days
+  - 1000 verified users: +3 Pro days
+  - every additional 100 verified users after 1000: +3 Pro days
+- Each milestone settles at most once.
+- Only users who currently have active membership access and have at least one
+  confirmed real payment are eligible.
+- Trial-only, manual-grant-only, and reward-only users are excluded.
+
+## Architecture
+
+The Telegram Bot process already acts as the single background-job owner. A new
+growth milestone loop runs there on a low-frequency interval. It reads verified
+Auth-user counts, writes one daily growth snapshot, checks unsettled milestones,
+selects eligible paid members, and grants an append-only bonus subscription
+window.
+
+SQLite stores daily snapshots, milestone settlement summaries, and per-user
+payout records. Supabase stores the actual bonus subscription. The bonus source
+contains the milestone number so a retry can detect an already-issued reward.
+
+## Failure Handling
+
+- Supabase read failures do not advance or settle a milestone.
+- Successful user payouts are recorded individually.
+- Failed payouts are retried on the next loop run.
+- A milestone is marked settled only when all eligible payouts succeed.
+- Bonus subscription writes use a milestone-specific source as an additional
+  idempotency guard.
+
+## Notification
+
+After a milestone settles, the Bot posts one concise bilingual group
+announcement when announcements are enabled. It includes the milestone, reward
+days, and rewarded member count.
+