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
@@ -20,6 +20,7 @@ PolyWeather 是面向温度结算场景的气象决策层，不是通用天气
 | 登录注册（Google + 邮箱） | 已上线 | Supabase 鉴权 |
 | 订阅套餐（Pro 月付 / 季度） | 已上线 | `29.9 USDC / 30天`；`79.9 USDC / 90天` |
 | 邀请积分 | 已上线 | 被邀请人首月 `20U`；邀请人每个有效付费邀请 `+3500` 积分 |
+| 用户增长奖励 | 已上线 | 按已验证用户里程碑，为当前有效且有 confirmed 入账记录的付费会员延长 Pro |
 | 积分抵扣 | 已上线 | `500分=1U`，最多 `3U`；邀请首月价不叠加积分抵扣 |
 | 合约支付 | 已上线 | Polygon，USDC + USDC.e |
 | 多链直转支付 | 已上线 | Ethereum 主网 USDC 直转确认 |
@@ -46,6 +47,7 @@ PolyWeather 是面向温度结算场景的气象决策层，不是通用天气
 - 套餐：`pro_monthly`（29.9 USDC / 30 天）、`pro_quarterly`（79.9 USDC / 90 天）
 - 邀请首月：被邀请人首次月付 20 USDC
 - 邀请奖励：邀请人 +3500 积分，每月最多 10 个有效付费邀请
+- 用户增长奖励：600 已验证用户 `+1天`、750 `+2天`、1000 `+3天`，此后每增长 100 人 `+3天`
 - 抵扣：500 积分抵 1 USDC；月付最高抵 3 USDC，季度最高抵 8 USDC
 - 积分来源：仅通过有效付费邀请和后台人工补发，不再通过 Telegram 群发言发放

@@ -0,0 +1,10 @@
+[
+  {
+    "recorded_at": "2026-06-12T23:32:49+08:00",
+    "total_registered_users": 588,
+    "verified_users": 573,
+    "ever_signed_in_users": 561,
+    "source": "supabase_auth_admin",
+    "note": "Baseline recorded before verified-user growth milestone rewards launched."
+  }
+]
@@ -0,0 +1,32 @@
+# PolyWeather Growth Rewards
+
+PolyWeather has reached **588 registered users**.
+
+That number matters because every new user helps us improve the product: more
+feedback, more real-world usage, and more pressure to make weather observations
+faster, clearer, and more reliable for prediction-market decisions.
+
+We are introducing **PolyWeather Growth Rewards**.
+
+From now on, verified-user milestones will unlock additional Pro time for every
+active paid member:
+
+- 600 verified users: **+1 Pro day**
+- 750 verified users: **+2 Pro days**
+- 1,000 verified users: **+3 Pro days**
+- Every additional 100 verified users after 1,000: **+3 Pro days**
+
+Rewards are issued automatically to active paid members when each milestone is
+reached. Every milestone can only be claimed once.
+
+This is separate from our referral program. Referrals still reward the people
+who directly help PolyWeather grow, while Growth Rewards let all paying members
+share in the progress of the community.
+
+We currently have **588 registered users**, including **573 verified users**.
+The first Growth Reward unlocks at 600 verified users.
+
+Grow together. Earn more Pro time.
+
+https://polyweather.top
+
@@ -0,0 +1,68 @@
+# Growth Milestone Pro Rewards Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Automatically extend active paid Pro memberships when verified-user growth milestones are reached.
+
+**Architecture:** A low-frequency Bot-owned loop reads Supabase Auth and payment data, stores daily growth history in SQLite, and grants idempotent milestone-specific bonus subscriptions. SQLite settlement and payout records prevent duplicate processing and support retries.
+
+**Tech Stack:** Python, SQLite, Supabase REST/Auth Admin API, Telegram Bot runtime, pytest
+
+---
+
+### Task 1: Define milestone and eligibility policy
+
+**Files:**
+- Create: `src/bot/growth_milestone_reward_loop.py`
+- Test: `tests/test_growth_milestone_reward_loop.py`
+
+- [ ] Write failing tests for the 600/750/1000/100-step milestone schedule and paid-member eligibility intersection.
+- [ ] Run `python -m pytest tests/test_growth_milestone_reward_loop.py -q` and confirm failure because the module is missing.
+- [ ] Implement pure policy helpers and Supabase query helpers.
+- [ ] Re-run the focused tests and confirm they pass.
+
+### Task 2: Persist history and settlement state
+
+**Files:**
+- Modify: `src/database/db_manager.py`
+- Test: `tests/test_growth_milestone_reward_loop.py`
+
+- [ ] Write failing tests for daily snapshot upsert, payout idempotency, and milestone settlement.
+- [ ] Run the focused tests and confirm the new DB methods are missing.
+- [ ] Add `user_growth_snapshots`, `growth_milestone_runs`, and `growth_milestone_payouts`.
+- [ ] Re-run the focused tests and confirm they pass.
+
+### Task 3: Run and announce automatic settlement
+
+**Files:**
+- Modify: `src/bot/growth_milestone_reward_loop.py`
+- Modify: `src/bot/runtime_coordinator.py`
+- Modify: `src/utils/config_validation.py`
+- Modify: `.env.example`
+- Test: `tests/test_growth_milestone_reward_loop.py`
+- Test: `tests/test_bot_runtime_coordinator.py`
+
+- [ ] Write failing tests for idempotent bonus grants and runtime-loop registration.
+- [ ] Run focused tests and confirm the expected failures.
+- [ ] Implement the settlement loop, retry behavior, and bilingual announcement.
+- [ ] Re-run focused tests and confirm they pass.
+
+### Task 4: Record baseline and publishable announcement
+
+**Files:**
+- Create: `docs/operations/user-growth-history.json`
+- Create: `docs/social/2026-06-12-growth-rewards-x-post.md`
+- Create: `docs/social/assets/polyweather-588-growth-rewards.png`
+
+- [ ] Record the verified 2026-06-12 baseline.
+- [ ] Write the English X announcement with accurate total-user and verified-user wording.
+- [ ] Save the generated social image in the repository.
+
+### Task 5: Verify and deploy
+
+- [ ] Run focused backend tests.
+- [ ] Run `python -m ruff check src/bot/growth_milestone_reward_loop.py src/bot/runtime_coordinator.py src/database/db_manager.py tests/test_growth_milestone_reward_loop.py tests/test_bot_runtime_coordinator.py`.
+- [ ] Run the broader relevant test suite.
+- [ ] Commit and push to `main`.
+- [ ] Check GitHub Actions and production health.
+
@@ -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.
+