feat: Introduce open-core policy, commercialization, and payment verification documentation, and update README with new product status, payment architecture, and documentation index.

docs/API_ZH.md

@@ -1,21 +1,14 @@
-# PolyWeather API 文档（v1.3）
+# PolyWeather API 文档（v1.4）
 
-本文档基于当前代码（`web/app.py` + `frontend/app/api/*`）整理。  
-前端默认通过 Next.js BFF 路由访问后端。
+最后更新：`2026-03-14`
 
----
+本文档描述当前对外可用 API 口径（`web/app.py` + `frontend/app/api/*`）。
 
 ## 1. 基础信息
 
 - 后端直连：`http://127.0.0.1:8000`
 - 前端 BFF：`https://polyweather-pro.vercel.app/api/*`
 - 返回格式：`application/json`
-- 口径说明：
-  - 结算导向分析以温度最高值和温度桶概率为核心。
-  - Ankara 增强使用 MGM，主站固定 `17130`。
-  - Meteoblue 已移除，不再出现在任何有效字段中。
-
----
 
 ## 2. 请求链路
 
@@ -24,78 +17,21 @@ flowchart LR
     FE["Browser / Dashboard"] --> BFF["Next.js Route Handlers (/api/*)"]
     BFF --> API["FastAPI (/web/app.py)"]
     API --> WX["Weather Collector"]
-    API --> ANA["DEB + Trend + Probabilities + Market Scan"]
-    ANA --> PM["Polymarket Read-only Layer"]
+    API --> ANA["DEB + Trend + Probability + Market Scan"]
+    API --> PAY["Payment Intent + Event + Confirm Loops"]
 ```
 
----
-
-## 3. 接口总览
+## 3. 天气分析接口
 
 | 接口 | 方法 | 用途 |
 | :-- | :-- | :-- |
-| `/api/cities` | GET | 监控城市列表（地图/侧栏） |
-| `/api/city/{name}` | GET | 城市主分析（今日分析核心数据） |
-| `/api/city/{name}/summary` | GET | 轻量摘要（首屏预热/低成本轮询） |
-| `/api/city/{name}/detail` | GET | 聚合详情（含 `market_scan`） |
-| `/api/history/{name}` | GET | 历史对账数据 |
+| `/api/cities` | GET | 监控城市列表 |
+| `/api/city/{name}` | GET | 城市主分析 |
+| `/api/city/{name}/summary` | GET | 轻量摘要 |
+| `/api/city/{name}/detail` | GET | 聚合详情（含 market_scan） |
+| `/api/history/{name}` | GET | 历史对账 |
 
----
-
-## 4. 关键接口说明
-
-### 4.1 `GET /api/cities`
-
-返回监控城市清单。
-
-关键字段：
-
-- `name`, `display_name`
-- `lat`, `lon`
-- `risk_level`, `risk_emoji`
-- `airport`, `icao`
-- `temp_unit`（`celsius` / `fahrenheit`）
-
-### 4.2 `GET /api/city/{name}`
-
-主分析接口，返回当前实况、预报、概率、趋势、AI 分析等。
-
-可选参数：
-
-- `force_refresh=true|false`
-
-关键字段：
-
-- `current`（温度、今日最高、METAR 观测时间、原始 METAR）
-- `forecast`（今日及多日高温、日出日落、日照时长）
-- `mgm`, `mgm_nearby`
-- `multi_model`, `multi_model_daily`
-- `deb`, `ensemble`
-- `probabilities`（`mu` + `distribution`）
-- `trend`, `peak`
-- `hourly`, `hourly_next_48h`
-- `source_forecasts.weather_gov`
-
-### 4.3 `GET /api/city/{name}/summary`
-
-轻量摘要接口，适合高频刷新列表。
-
-可选参数：
-
-- `force_refresh=true|false`
-
-关键字段：
-
-- `name`, `display_name`, `icao`
-- `local_time`, `temp_symbol`
-- `current.temp`, `current.obs_time`
-- `deb.prediction`
-- `risk.level`, `risk.warning`
-- `updated_at`
-
-### 4.4 `GET /api/city/{name}/detail`
-
-聚合详情接口，市场分析与未来日期分析都依赖该接口。
+### `GET /api/city/{name}/detail`
 
 可选参数：
 
@@ -103,124 +39,78 @@ flowchart LR
 - `market_slug=<slug>`
 - `target_date=YYYY-MM-DD`
 
-关键返回块：
+重点字段：
 
-- `overview`
-- `official`
-- `timeseries`
-- `models`
-- `probabilities`
-- `market_scan`
-- `risk`
-- `ai_analysis`
+- `market_scan.available`
+- `market_scan.signal_label`
+- `market_scan.anchor_model / anchor_high / anchor_settlement`
+- `market_scan.yes_buy / no_buy`
+- `market_scan.primary_market.tradable`
 
-`market_scan` 重点字段：
+## 4. 鉴权与账户接口
 
-- `available`, `selected_date`, `selected_slug`, `signal_label`
-- `yes_buy`, `yes_sell`, `no_buy`, `no_sell`
-- `temperature_bucket`, `forecast_bucket`, `top_buckets`
-- `anchor_model`, `anchor_high`, `anchor_settlement`
-- `open_meteo_settlement`（兼容旧字段，当前与 `anchor_settlement` 同值）
-- `primary_market.tradable`, `primary_market.tradable_reason`
-- `primary_market.accepting_orders`, `primary_market.ended_at_utc`
+| 接口 | 方法 | 用途 |
+| :-- | :-- | :-- |
+| `/api/auth/me` | GET | 当前登录态、积分、订阅状态 |
 
-说明：
+`/api/auth/me` 关键字段：
 
-- 当前错价锚点不是单一 Open-Meteo，而是“多模型最高温锚点”。
-- 推送层会再次校验市场可交易性，不可交易市场会跳过。
+- `authenticated`
+- `user_id`, `email`
+- `points`, `weekly_points`, `weekly_rank`
+- `subscription_active`, `subscription_plan_code`, `subscription_expires_at`
 
-### 4.5 `GET /api/history/{name}`
+## 5. 支付接口（P1）
 
-历史对账接口。
+| 接口 | 方法 | 用途 |
+| :-- | :-- | :-- |
+| `/api/payments/config` | GET | 支付配置、代币列表、套餐、积分抵扣规则 |
+| `/api/payments/wallets` | GET | 当前用户已绑定钱包 |
+| `/api/payments/wallets/challenge` | POST | 获取绑定签名 challenge |
+| `/api/payments/wallets/verify` | POST | 提交签名并绑定钱包 |
+| `/api/payments/intents` | POST | 创建支付意图（intent） |
+| `/api/payments/intents/{intent_id}` | GET | 查询 intent 最新状态 |
+| `/api/payments/intents/{intent_id}/submit` | POST | 提交交易哈希 |
+| `/api/payments/intents/{intent_id}/confirm` | POST | 手动触发确认 |
 
-关键字段：
+### 支付状态建议
 
-- `date`
-- `actual`
-- `deb`
-- `mu`
-- `mgm`
+前端流程建议：
 
----
+1. `POST /intents`
+2. 钱包发链上交易
+3. `POST /submit`
+4. `POST /confirm`
+5. 若 pending，轮询 `GET /intents/{id}` 直到 `confirmed`
 
-## 5. 缓存与刷新策略（当前已实现）
+## 6. 缓存策略（当前）
 
-### 5.1 FastAPI 后端缓存
+- `cities` / `summary` / `history`：BFF 支持 `ETag + 304`
+- `summary?force_refresh=true`：`Cache-Control: no-store`
+- 详情接口与支付接口：`no-store`
 
-- `_analyze` 结果内存缓存：默认 5 分钟
-- Ankara 特例：60 秒
-- `force_refresh=true`：绕过后端缓存
+## 7. 调试示例
 
-### 5.2 Next.js BFF HTTP 缓存（Vercel）
-
-- `GET /api/cities`
-  - `ETag`
-  - `Cache-Control: public, max-age=0, s-maxage=300, stale-while-revalidate=1800`
-- `GET /api/city/{name}/summary`
-  - `ETag`
-  - `Cache-Control: public, max-age=0, s-maxage=20, stale-while-revalidate=60`
-- `GET /api/history/{name}`
-  - `ETag`
-  - `Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300`
-- `summary?force_refresh=true`
-  - `Cache-Control: no-store`
-
-### 5.3 前端本地缓存
-
-- `sessionStorage`
-  - 城市详情缓存（5 分钟 TTL + revision 探测）
-- `localStorage`
-  - 上次选中城市
-  - 侧栏风险分组折叠状态
-
-### 5.4 尚未引入（当前明确未做）
-
-- Service Worker Cache API
-- IndexedDB
-
----
-
-## 6. 常用调试示例
-
-### 6.1 查询未来日期 `market_scan`
+### 查询未来日期 market_scan
 
 ```bash
-curl -s "http://127.0.0.1:8000/api/city/ankara/detail?force_refresh=true&target_date=2026-03-12" \
-| python3 -c "import sys,json; m=json.load(sys.stdin).get('market_scan',{}); print({k:m.get(k) for k in ['available','selected_date','anchor_model','anchor_high','anchor_settlement','yes_buy','no_buy']})"
+curl -s "http://127.0.0.1:8000/api/city/ankara/detail?force_refresh=true&target_date=2026-03-12"
 ```
 
-### 6.2 验证前端缓存头
+### 校验支付配置
 
 ```bash
-./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
+curl -s http://127.0.0.1:8000/api/payments/config | python3 -m json.tool
 ```
 
-### 6.3 观察错价雷达跳过原因
+### 观察支付自动补单
 
 ```bash
-docker compose logs -f polyweather | egrep "market not tradable|trade alert pushed|mispricing cap"
+docker compose logs -f polyweather | egrep "payment event loop started|payment confirm loop started|payment auto-confirmed"
 ```
 
----
+## 8. 开源口径说明
 
-## 7. 常见问题
+对外公开文档仅覆盖通用 API 契约。生产商业策略参数不在公开文档披露。
 
-### 7.1 VPS `:8000` 为什么看不到 `ETag`？
-
-- `:8000` 是 FastAPI 直连层，主要负责聚合分析。
-- `ETag/304` 在前端 BFF（Vercel 的 `/api/*`）侧实现。
-
-### 7.2 为什么 `target_date` 有时没有市场价格？
-
-- 该日期可能没有可交易市场。
-- 或目标桶在市场里无可用报价（`yes_buy/no_buy` 缺失）。
-- 可先看 `market_scan.available` 与 `primary_market.tradable`。
-
-### 7.3 如何确认 Bot 后台循环是否启动？
-
-- Telegram 里发送 `/diag`。
-- 查看三类循环状态：错价雷达、Polygon 钱包监听、Polymarket 钱包异动监听。
-
----
-
-最后更新：`2026-03-12`
+详见：[Open-Core 与商用边界](OPEN_CORE_POLICY.md)

docs/COMMERCIALIZATION.md

@@ -1,118 +1,66 @@
-# Commercialization Roadmap
+# 商业化说明（Production）
 
-Target: make PolyWeather a sustainable paid weather-intelligence product.
+最后更新：`2026-03-14`
 
----
+## 1. 定位
 
-## 1. Product Positioning
+PolyWeather 是面向温度结算场景的气象决策层，不是通用天气应用。
 
-PolyWeather is not a generic weather app. It is a settlement decision layer for temperature markets:
+核心价值：
 
-- observation-first (METAR/MGM),
-- settlement-aware modeling (DEB + mu/buckets),
-- market mapping (Polymarket read-only) for actionable mispricing checks.
+- 观测优先（METAR/MGM）
+- 结算导向（DEB + 概率桶）
+- 市场映射（行情对照 + 错价雷达）
 
----
+## 2. 当前收费能力状态
 
-## 2. Current Monetization Readiness (2026-03-12)
-
-| Capability | Status | Notes |
+| 能力 | 状态 | 备注 |
 | :-- | :-- | :-- |
-| Frontend entitlement gate | Implemented | Next middleware supports token gate + session cookie |
-| Backend entitlement guard | Implemented | `POLYWEATHER_REQUIRE_ENTITLEMENT` + backend token header |
-| Bot command entitlement pre-hook | Implemented | `/city` and `/deb` can be protected (`POLYWEATHER_BOT_REQUIRE_ENTITLEMENT`) |
-| Payment event ingestion | Not implemented | No automated USDC payment reconciliation yet |
-| Subscriber persistence | Not implemented | Still missing managed subscriber DB |
-| Self-serve billing UI | Not implemented | No user billing center yet |
+| 登录注册（Google + 邮箱） | 已上线 | Supabase 鉴权 |
+| 订阅套餐（Pro 月付） | 已上线 | `5 USDC / 30天` |
+| 积分抵扣 | 已上线 | `500分=1U`，最多 `3U` |
+| 合约支付 | 已上线 | Polygon，USDC + USDC.e |
+| 支付自动确认 | 已上线 | Event Loop + Confirm Loop |
+| 钱包绑定 | 已上线 | 浏览器钱包 + WalletConnect |
+| 私有频道推送 | 已上线 | 可拆分业务频道 |
 
----
+## 3. 权限模型（当前）
 
-## 3. Access Model
+- 游客：可查看基础看板与简版信息。
+- 登录用户：账户中心、钱包绑定、积分同步。
+- Pro 用户：
+  - 今日日内深度分析（含高温时段）
+  - 历史对账 + 未来日期分析
+  - 全平台智能气象推送
 
-```mermaid
-flowchart LR
-    U["User"] --> FE["Frontend (Vercel)"]
-    FE --> MW["Entitlement Middleware"]
-    MW --> BFF["BFF /api/*"]
-    BFF --> API["FastAPI"]
-    API --> G["Backend Entitlement Guard"]
+## 4. 收费与积分规则（默认）
 
-    P["Payment Source (USDC / Wallet)"] --> S["Subscriber State (to build)"]
-    S --> MW
-    S --> API
-```
+- 套餐：`pro_monthly`（5 USDC / 30 天）
+- 抵扣：500 积分抵 1 USDC，最高抵 3 USDC
+- 实付下限：2 USDC（当积分满额时）
 
-### Do we need login/register to start charging?
+> 说明：具体运营策略可按阶段调整，生产参数建议放私有仓库。
 
-Short answer: **no for phase 1, yes for scale**.
+## 5. 建议的开源边界
 
-- Phase 1 can run with token/wallet-based entitlement and manual ops.
-- For scale (self-serve renewals, refunds, support, analytics), account identity and subscriber DB become mandatory.
+请按 Open-Core 执行：
 
----
+- 开源：基础能力与通用支付流程。
+- 私有：商业风控、营销策略、关键运营参数、内部审计策略。
 
-## 4. Packaging and Pricing (Draft)
+详见：[Open-Core 与商用边界](OPEN_CORE_POLICY.md)
 
-| Tier | Price | Value |
-| :-- | :-- | :-- |
-| Telegram Signal Channel | $1 / month | Low-noise proactive signal stream |
-| Web Dashboard | $5 / month | Full model context + historical reconciliation |
-| VIP Bundle | $5.5 / month | Dashboard + signal stream |
+## 6. 上线检查清单（收费前）
 
-Payment direction:
+1. 支付链路：创建 intent、提交 tx、确认入账、订阅开通全链路可回放。
+2. 权限链路：前端/后端/Bot 对 Pro 权限判定一致。
+3. 审计能力：支付日志、订阅变更、异常重试可追溯。
+4. 通知策略：支付成功私发、群内通知降噪。
+5. 安全边界：敏感配置不进仓库。
 
-- Settlement/network: Polygon USDC
-- Rollout: manual confirmation first, then automated entitlement sync
+## 7. 后续路线
 
----
-
-## 5. Execution Phases
-
-### Phase 1: Manual Paid Beta
-
-- Keep user set small and quality-focused.
-- Manual payment confirmation + manual entitlement issue.
-- Weekly accuracy report as trust anchor.
-
-### Phase 2: Payment Automation
-
-- Ingest payment events (wallet/tx).
-- Auto-issue and auto-expire entitlement.
-- Full parity across frontend middleware, backend API, and bot command guard.
-
-### Phase 3: Growth and B2B
-
-- Self-serve billing and subscriber console.
-- Retention analytics and feature usage telemetry.
-- Optional B2B/API package.
-
----
-
-## 6. P0/P1 Commercial Engineering Backlog
-
-### P0 (before public paid launch)
-
-1. Subscriber store (managed PostgreSQL/Supabase) with entitlement expiry.
-2. Payment event pipeline (idempotent ingest + reconciliation + retry).
-3. Unified entitlement policy matrix (frontend/backend/bot).
-4. Ops audit trail for alerts and entitlement changes.
-
-### P1 (after initial paid users)
-
-1. Billing/entitlement admin console.
-2. User-level support tooling (manual override, extension, refund notes).
-3. Conversion and retention dashboards.
-4. Churn diagnostics linked to alert quality and latency.
-
----
-
-## 7. Commercial Risk Controls
-
-- Revenue leakage: deny by default when entitlement token/state is missing.
-- Signal quality drift: publish monthly transparent accuracy summary.
-- Support load: keep alert evidence standardized in push payloads.
-- Compliance/ops: preserve immutable entitlement and push logs.
-
----
-
-Last Updated: `2026-03-12`
+- 支持更多链和稳定币。
+- 引入退款与工单后台。
+- 建立周/月留存与付费转化看板。
+- 打通渠道分销与邀请码返利系统。

docs/OPEN_CORE_POLICY.md

@@ -0,0 +1,63 @@
+# Open-Core 与商用边界
+
+最后更新：`2026-03-14`
+
+## 1. 目标
+
+在保持社区可用性的前提下，保护商业化阶段的核心经营资产。
+
+## 2. 仓库公开范围（可开源）
+
+- 天气数据采集与标准化（METAR / Open-Meteo / MGM 接口层）。
+- DEB 与基础趋势分析、概率桶计算。
+- Dashboard 基础体验与 API/BFF 结构。
+- Telegram Bot 基础命令与基础积分机制。
+- 合约支付标准流程（钱包绑定、intent、提交、确认、补单）。
+
+## 3. 生产私有范围（建议不公开）
+
+- 商业风控参数与规则库：
+  - 错价信号阈值组合、推送阈值、异常检测策略。
+- 运营策略资产：
+  - 用户分层规则、促销规则、留存策略、活动模板。
+- 付费系统敏感细节：
+  - 实时对账容错阈值、退款审计策略、内部财务映射规则。
+- 私有运维资产：
+  - 生产告警路由、内部频道映射、应急脚本与排障手册。
+
+## 4. 配置与数据安全红线
+
+- 不提交：`.env`、私钥、API key、机器人 token。
+- 不提交：生产数据库、运行时状态文件、支付流水快照。
+- 不提交：用户身份信息、钱包映射、订阅原始审计日志。
+
+## 5. 推荐发布模式
+
+### 5.1 Community Edition（开源）
+
+- 提供基础分析与基础看板。
+- 可选保留只读市场扫描。
+- 默认关闭商业化运营规则。
+
+### 5.2 Production Edition（私有）
+
+- 启用收费、订阅、积分抵扣、风控、私有监控。
+- 仅在私有仓库维护运营策略与敏感参数。
+
+## 6. 文档口径规范
+
+对外文档仅描述：
+
+- 能力边界与使用方式。
+- 可公开的技术架构。
+- 不包含可被直接复刻的商业参数。
+
+不对外文档描述：
+
+- 具体策略阈值、用户分层细则、收益归因规则。
+
+## 7. 许可证与法务建议（简版）
+
+- 建议保持仓库代码许可证与商标/品牌授权分离。
+- 若提供商业服务，建议在官网补充服务条款与隐私政策。
+- 对“订阅权益”与“可用性”做明确 SLA 与免责边界。

docs/SUPABASE_SETUP_ZH.md

@@ -1,28 +1,30 @@
-# Supabase + Google 登录 + 合约支付接入说明（P1）
+# Supabase + 登录 + 支付接入说明（v1.4）
+
+最后更新：`2026-03-14`
 
 ## 1. 目标
 
-- 前端支持 `Google 一键登录`（优先）与 `邮箱注册/登录`（并列）。
-- 后端 API 支持 Supabase JWT 鉴权。
-- entitlement 检查可选：仅登录放行，或要求有效订阅。
+- 前端支持 Google 一键登录 + 邮箱注册/登录。
+- 后端支持 Supabase JWT 鉴权。
+- 支持 Polygon 合约支付（USDC / USDC.e）并自动确认开通订阅。
 
 ## 2. Supabase 控制台配置
 
-1. Auth -> Providers -> 打开 `Google`。
-2. Auth -> Providers -> `Email` 保持开启。
-3. 在 Google Cloud Console 配置 OAuth 回调地址：
-   - `https://<your-project-ref>.supabase.co/auth/v1/callback`
-4. 在 Auth -> URL Configuration 添加站点 URL（你的前端域名）。
+1. `Auth -> Providers` 打开 `Google` 与 `Email`。
+2. Google Cloud OAuth 回调配置：
+   - `https://<project-ref>.supabase.co/auth/v1/callback`
+3. `Auth -> URL Configuration` 添加：
+   - 站点 URL（生产域名）
+   - 回调 URL（例如 `https://polyweather-pro.vercel.app/auth/callback`）
 
-## 3. 执行数据库脚本
+## 3. 数据库脚本
 
-在 Supabase SQL Editor 运行：
+在 Supabase SQL Editor 执行：
 
 - `scripts/supabase/schema.sql`
 
-该脚本会创建：
+会创建支付与订阅相关表：
 
-- `profiles`
 - `subscriptions`
 - `payments`
 - `entitlement_events`
@@ -31,8 +33,6 @@
 - `payment_intents`
 - `payment_transactions`
 
-并建立 `auth.users -> profiles` 同步触发器。
-
 ## 4. 环境变量
 
 ### 4.1 前端（Vercel / frontend/.env.local）
@@ -41,86 +41,82 @@
 NEXT_PUBLIC_SUPABASE_URL=
 NEXT_PUBLIC_SUPABASE_ANON_KEY=
 POLYWEATHER_AUTH_ENABLED=true
-# true: 强制登录；false: 游客可用（可选登录）
 POLYWEATHER_AUTH_REQUIRED=false
 POLYWEATHER_API_BASE_URL=http://<backend-host>:8000
 POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN=
+
+# WalletConnect（支持手机钱包扫码）
+NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
+NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com
+
+# Overlay 跳转
+NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/<your_group>
 ```
 
 ### 4.2 后端 / Bot（.env）
 
 ```env
 POLYWEATHER_AUTH_ENABLED=true
-# true: 后端 API 强制鉴权；false: 游客可访问，若带会话则自动识别用户
 POLYWEATHER_AUTH_REQUIRED=false
 POLYWEATHER_AUTH_REQUIRE_SUBSCRIPTION=false
+
 SUPABASE_URL=
 SUPABASE_ANON_KEY=
 SUPABASE_SERVICE_ROLE_KEY=
 SUPABASE_HTTP_TIMEOUT_SEC=8
-SUPABASE_AUTH_CACHE_TTL_SEC=30
-SUPABASE_SUB_CACHE_TTL_SEC=60
 
-# P1 合约支付（MetaMask + Polygon USDC）
 POLYWEATHER_PAYMENT_ENABLED=true
 POLYWEATHER_PAYMENT_CHAIN_ID=137
-POLYWEATHER_PAYMENT_RPC_URL=https://polygon-rpc.com
-POLYWEATHER_PAYMENT_RECEIVER_CONTRACT=0x<your_payment_contract>
-POLYWEATHER_PAYMENT_TOKEN_ADDRESS=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
-POLYWEATHER_PAYMENT_TOKEN_DECIMALS=6
+POLYWEATHER_PAYMENT_RPC_URL=https://polygon-bor-rpc.publicnode.com
+POLYWEATHER_PAYMENT_RECEIVER_CONTRACT=0x<receiver_contract>
 POLYWEATHER_PAYMENT_CONFIRMATIONS=2
 POLYWEATHER_PAYMENT_INTENT_TTL_SEC=1800
 POLYWEATHER_PAYMENT_WALLET_CHALLENGE_TTL_SEC=600
-POLYWEATHER_PAYMENT_HTTP_TIMEOUT_SEC=10
 POLYWEATHER_PAYMENT_POLL_INTERVAL_SEC=4
 POLYWEATHER_PAYMENT_MAX_WAIT_SEC=50
-POLYWEATHER_PAYMENT_TELEGRAM_NOTIFY_ENABLED=true
-# 支付积分抵扣（500 积分 = 1 USDC，最高抵扣 3 USDC）
+
+# 支持双币种（示例）
+POLYWEATHER_PAYMENT_ACCEPTED_TOKENS_JSON=[{"code":"usdc_e","symbol":"USDC.e","name":"USDC.e (PoS)","address":"0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174","decimals":6,"receiver_contract":"0x<receiver>","is_default":true},{"code":"usdc","symbol":"USDC","name":"Native USDC","address":"0x3c499c542cef5e3811e1192ce70d8cc03d5c3359","decimals":6,"receiver_contract":"0x<receiver>"}]
+
+# 套餐（当前只保留月付）
+POLYWEATHER_PAYMENT_PLAN_CATALOG_JSON={"pro_monthly":{"plan_id":101,"amount_usdc":"5","duration_days":30}}
+POLYWEATHER_PAYMENT_ALLOWED_PLAN_CODES=pro_monthly
+
+# 积分抵扣
 POLYWEATHER_PAYMENT_POINTS_ENABLED=true
 POLYWEATHER_PAYMENT_POINTS_PER_USDC=500
 POLYWEATHER_PAYMENT_POINTS_MAX_DISCOUNT_USDC=3
-# JSON 示例:
-# {"pro_monthly":{"plan_id":101,"amount_usdc":"5","duration_days":30}}
-POLYWEATHER_PAYMENT_PLAN_CATALOG_JSON=
+
+# 支付自动补单
+POLYWEATHER_PAYMENT_EVENT_LOOP_ENABLED=true
+POLYWEATHER_PAYMENT_CONFIRM_LOOP_ENABLED=true
 ```
 
-可选（Bot 也走 Supabase 订阅）：
+## 5. 钱包异动频道拆分（推荐）
+
+如果要把“钱包异动监控”发到独立频道：
 
 ```env
-POLYWEATHER_BOT_REQUIRE_ENTITLEMENT=true
-POLYWEATHER_BOT_USE_SUPABASE_ENTITLEMENT=true
+POLYMARKET_WALLET_ACTIVITY_CHAT_ID=-1003821482461
 ```
 
-## 5. entitlement 策略
+说明：
 
-- `POLYWEATHER_AUTH_ENABLED=true`：启用 Supabase 登录能力（Google/邮箱）。
-- `POLYWEATHER_AUTH_REQUIRED=true`：网站与后端 API 强制登录。
-- `POLYWEATHER_AUTH_REQUIRED=false`：游客可访问全部功能，用户可主动登录。
-- `POLYWEATHER_AUTH_REQUIRE_SUBSCRIPTION=true`：在强制鉴权模式下，额外要求 `subscriptions` 表里存在有效 `active` 记录。
+- 设置了 `POLYMARKET_WALLET_ACTIVITY_CHAT_ID(S)` 后，钱包异动推送优先发该频道。
+- 未设置时，回退到全局 `TELEGRAM_CHAT_IDS/TELEGRAM_CHAT_ID`。
 
-## 6. 验证
+## 6. 验证步骤
 
-1. 访问 `/auth/login`，测试 Google 一键登录。
-2. `POLYWEATHER_AUTH_REQUIRED=false` 时，未登录访问首页与 `/api/cities` 应返回 200。
-3. 登录后访问 `/api/auth/me`，应返回 `authenticated=true` 与 `user_id`。
-4. `POLYWEATHER_AUTH_REQUIRED=true` 时，未登录访问受保护接口应返回 401 或跳转登录页。
-
-## 7. P1 支付链路验证
-
-1. 登录后访问 `GET /api/payments/config`，应看到 `enabled=true`、`configured=true`。
-2. 账户页点击“连接并绑定 MetaMask”，完成签名后 `GET /api/payments/wallets` 可看到地址。
-3. 点击“创建订单并支付”：
+1. 登录后请求 `/api/auth/me`，确认 `authenticated=true`。
+2. 请求 `/api/payments/config`，确认 `enabled=true`、`configured=true`。
+3. 钱包绑定：
+   - `POST /api/payments/wallets/challenge`
+   - `POST /api/payments/wallets/verify`
+4. 支付流程：
    - `POST /api/payments/intents`
-   - MetaMask 发交易到 `POLYWEATHER_PAYMENT_RECEIVER_CONTRACT`
-   - `POST /api/payments/intents/{intent_id}/submit`
-   - `POST /api/payments/intents/{intent_id}/confirm`
-4. 确认后应自动写入：
-   - `payments`（`status=confirmed`）
-   - `subscriptions`（新增 `active` 记录）
-   - `entitlement_events`（`subscription_granted`）
-
-合约事件要求：
-
-- 合约需在 `pay(orderId, planId, amount, token)` 成功后发出  
-  `OrderPaid(bytes32 orderId, address payer, uint256 planId, address token, uint256 amount)`  
-  （字段顺序和类型需一致）。
+   - 发链上交易
+   - `POST /api/payments/intents/{id}/submit`
+   - `POST /api/payments/intents/{id}/confirm`
+5. 若前端显示 pending，轮询：
+   - `GET /api/payments/intents/{id}`
+6. 确认订阅：`/api/auth/me` 返回 `subscription_active=true`。

docs/TECH_DEBT.md

@@ -1,94 +1,73 @@
-# Technical Debt Backlog
+# Technical Debt Backlog (v1.4)
 
-Purpose: keep engineering debt explicit while shipping production features.
+Last Updated: `2026-03-14`
 
----
+Focus after paid launch: payment reliability, entitlement parity, and auditability.
 
-## 1. Debt Snapshot
+## 1. Snapshot
 
-Current estimate: **90% stable / 10% debt**.
+Current estimate: **93% stable / 7% debt**.
 
 ```mermaid
 flowchart TD
     A["Tech Debt"]
 
-    subgraph PI["Payment Infra"]
-        PI1["Payment event ingestion"]
-        PI2["Subscriber persistence"]
-        PI3["Entitlement parity"]
+    subgraph P["Payments & Subscriptions"]
+        P1["Automatic replay for failed confirmations"]
+        P2["Refund and support workflow"]
+        P3["Multi-chain settlement reconciliation"]
     end
 
-    subgraph Q["Quality"]
-        Q1["Replay harness"]
-        Q2["Mixed integration tests"]
+    subgraph E["Entitlement & Ops"]
+        E1["Frontend/backend/bot entitlement regression matrix"]
+        E2["Points vs subscription conflict policy"]
     end
 
     subgraph O["Observability"]
-        O1["Alert evidence schema"]
-        O2["Ops dashboards"]
+        O1["Layered metrics for payment failures"]
+        O2["Business operations dashboards"]
     end
 
-    A --> PI
-    A --> Q
+    A --> P
+    A --> E
     A --> O
 ```
 
----
+## 2. Recently Closed
 
-## 2. Recently Closed (2026-03-12)
+- P1 checkout flow live (intent -> submit -> confirm).
+- Automatic reconciliation live (event loop + confirm loop).
+- Wallet binding supports extension wallets + WalletConnect.
+- Account center entitlement rendering is wired end-to-end.
+- Wallet activity watcher supports dedicated channel routing.
 
-- Bot entry refactor completed:
-  - `bot_listener.py` simplified to thin entrypoint.
-  - Runtime split into orchestrator/handlers/services/analysis/guard/coordinator layers.
-- Startup diagnostics landed:
-  - `/diag` command
-  - loop-level startup status reporting (trade alerts, polygon watcher, polymarket watcher)
-- Multi-model anchor migration completed for mispricing radar (replaced single Open-Meteo anchor).
-- Non-tradable market hard-skip guard completed (closed/inactive/not accepting orders/past end time).
-- Wallet activity watcher upgraded with alias parsing, link preview switch, and anti-spam debounce/immediate controls.
-- Frontend BFF HTTP caching (`ETag`/`304`) completed for cities/summary/history.
-- Meteoblue fully removed from runtime paths and docs.
-
----
-
-## 3. Active High-Priority Debt
+## 3. High-Priority Debt
 
 | Item | Impact | Suggested Work |
 | :-- | :-- | :-- |
-| Payment event ingestion pipeline | Cannot automate paid access reliably | Build idempotent onchain payment ingest + reconciliation worker |
-| Subscriber persistence model | Manual entitlement ops do not scale | Add managed PostgreSQL/Supabase subscriber state |
-| Entitlement parity matrix | Access leaks/false denies across channels | Unify policy across frontend middleware, backend API, and bot guard |
-| Alert evidence contract | Harder to debug false positives quickly | Standardize machine-readable evidence schema for each push |
+| Automatic replay strategy for transient tx failures | Manual intervention still needed in some edge cases | Standardize tx replay + fallback paths |
+| Refund/support workflow | Commercial loop incomplete | Add refund state machine + support tooling |
+| Subscription audit visualization | Slower incident triage | Build timeline view for entitlement events |
+| Multi-email same-Telegram binding policy | Points ownership confusion | Add primary-account binding and migration utilities |
 
----
-
-## 4. Active Medium-Priority Debt
+## 4. Medium-Priority Debt
 
 | Item | Impact | Suggested Work |
 | :-- | :-- | :-- |
-| Replay simulation harness | Edge-case regressions hard to reproduce | Deterministic replay from stored weather + market snapshots |
-| End-to-end integration coverage | Runtime regressions can slip | Add integration tests for `/api/city/{name}/detail` + push decisions |
-| Config sprawl | Tuning is error-prone | Consolidate env knobs into structured config groups |
-| Naming and data contracts | Boundary confusion persists | Normalize model/market field naming and compatibility aliases |
+| Points transparency | User confusion | Expose points breakdown by source |
+| Payment error copy consistency | Conversion impact | Build error-code to UX-copy mapping table |
+| Config sprawl | Ops mistakes | Consolidate payment/push configs into grouped schemas |
 
----
-
-## 5. Active Low-Priority Debt
+## 5. Low-Priority Debt
 
 | Item | Impact | Suggested Work |
 | :-- | :-- | :-- |
-| Cold-start variance | First request latency jitter | Add prewarm strategy for top city routes |
-| Local state files | Harder multi-instance scaling | Continue migration to managed storage |
-
----
+| Offline cache support | Non-core | Evaluate SW + IndexedDB |
+| Cold-start variance | First-load jitter | Add route prewarming for hot cities |
 
 ## 6. Next Milestones
 
-1. Land subscriber DB + entitlement expiry model.
-2. Ship payment ingest + automatic entitlement sync.
-3. Add replay harness for weather/market mixed scenarios.
-4. Publish alert evidence schema and operator tooling.
-
----
-
-Last Updated: `2026-03-12`
+1. Ship automatic replay and alert stratification for payment anomalies.
+2. Launch minimal refund/support admin flow.
+3. Add business dashboards for payments, renewals, and retention.
+4. Complete entitlement parity regression suite.

docs/TECH_DEBT_ZH.md

@@ -1,94 +1,73 @@
-# 技术债与工程待办
+# 技术债与工程待办（v1.4）
 
-目标：在持续交付的同时，让技术债可见、可追踪、可关闭。
+最后更新：`2026-03-14`
 
----
+目标：在收费上线后，优先保证支付可靠性、权限一致性和运营可追溯性。
 
 ## 1. 债务快照
 
-当前估计：**90% 稳定 / 10% 技术债**。
+当前估计：**93% 稳定 / 7% 技术债**。
 
 ```mermaid
 flowchart TD
     A["技术债"]
 
-    subgraph PI["支付基础设施"]
-        PI1["支付事件入库与对账"]
-        PI2["订阅用户持久化"]
-        PI3["权限策略一致化"]
+    subgraph P["支付与订阅"]
+        P1["异常交易自动重放策略"]
+        P2["退款与工单流程"]
+        P3["多链结算对账"]
     end
 
-    subgraph Q["质量保障"]
-        Q1["回放仿真能力"]
-        Q2["端到端集成覆盖"]
+    subgraph E["权限与运营"]
+        E1["前后端/Bot 权限矩阵回归"]
+        E2["积分与订阅冲突策略"]
     end
 
     subgraph O["可观测性"]
-        O1["告警证据标准"]
-        O2["运维看板"]
+        O1["支付失败原因分层指标"]
+        O2["业务监控看板"]
     end
 
-    A --> PI
-    A --> Q
+    A --> P
+    A --> E
     A --> O
 ```
 
----
+## 2. 近期已关闭
 
-## 2. 近期已关闭（2026-03-12）
+- P1 支付主链路已上线（intent -> submit -> confirm）。
+- 支付自动补单已上线（Event Loop + Confirm Loop）。
+- 钱包绑定支持浏览器钱包 + WalletConnect。
+- 账户中心与 Pro 权限展示链路打通。
+- 钱包异动支持独立频道路由。
 
-- Bot 入口重构完成：
-  - `bot_listener.py` 已收敛为薄入口。
-  - 运行时拆分为编排层/处理层/服务层/分析层/守卫层/协调层。
-- 启动诊断完成：
-  - 新增 `/diag` 指令
-  - 后台循环启动状态可视化（错价雷达、Polygon 钱包、Polymarket 异动）
-- 错价锚点完成升级：从单一 Open-Meteo 改为多模型最高温锚点。
-- 不可交易市场硬拦截完成：`closed`/inactive/不接单/超结束时间全部跳过。
-- 钱包异动监听增强完成：昵称映射、链接预览开关、去抖与即时推送控制。
-- 前端 BFF `ETag/304` 缓存完成（cities/summary/history）。
-- Meteoblue 已从运行链路与文档中彻底移除。
-
----
-
-## 3. 当前高优先级技术债
+## 3. 高优先级技术债
 
 | 项目 | 影响 | 建议动作 |
 | :-- | :-- | :-- |
-| 支付事件采集与对账流水线 | 无法稳定自动开通付费权限 | 构建幂等 payment ingest + reconciliation worker |
-| 订阅用户持久化模型 | 人工开通不可扩展 | 落地 PostgreSQL/Supabase 订阅状态 |
-| 权限策略一致性矩阵 | 存在漏放行/误拦截风险 | 统一前端中间件、后端 API、Bot 守卫策略 |
-| 告警证据协议 | 假阳性排障成本高 | 统一机器可读 Evidence Schema |
+| 支付异常重放策略标准化 | 偶发确认失败需人工介入 | 建立 tx hash 自动回放 + 降级路径 |
+| 退款与售后链路 | 商业闭环不完整 | 增加退款状态机与工单系统 |
+| 订阅审计可视化 | 排障效率受限 | 建立订阅事件时间线视图 |
+| 多邮箱绑定同 TG 账户策略 | 积分归属易混淆 | 引入主账号绑定策略与迁移工具 |
 
----
-
-## 4. 当前中优先级技术债
+## 4. 中优先级技术债
 
 | 项目 | 影响 | 建议动作 |
 | :-- | :-- | :-- |
-| 回放仿真能力不足 | 边缘场景回归难复现 | 基于天气+市场快照构建确定性 Replay |
-| 端到端集成覆盖不足 | 运行时回归难提前发现 | 增加 `/api/city/{name}/detail` 与推送链路集成测试 |
-| 配置项分散 | 阈值调优易出错 | 将关键 env 聚合为结构化配置分组 |
-| 命名与字段兼容历史包袱 | 认知与维护成本高 | 统一模型/市场字段命名与兼容层 |
+| 积分发放可解释性 | 用户理解成本高 | 输出积分来源明细（发言/签到/奖励） |
+| 支付失败文案标准化 | 转化率受影响 | 建立错误码 -> 文案映射表 |
+| 配置收敛 | 运维出错概率高 | 将支付/推送配置集中分组管理 |
 
----
-
-## 5. 当前低优先级技术债
+## 5. 低优先级技术债
 
 | 项目 | 影响 | 建议动作 |
 | :-- | :-- | :-- |
-| 冷启动波动 | 首次请求延迟抖动 | 对热点城市路由做预热 |
-| 本地文件状态依赖 | 多实例扩展受限 | 继续迁移到托管存储 |
-
----
+| 前端离线缓存能力 | 非核心 | 评估 Service Worker + IndexedDB |
+| 冷启动波动 | 首屏抖动 | 热点城市预热 |
 
 ## 6. 下阶段里程碑
 
-1. 上线订阅用户 DB 与权限过期模型。
-2. 完成支付事件入库与自动授权同步。
-3. 落地天气+市场混合回放回归。
-4. 发布告警证据标准与运维排障工具。
-
----
-
-最后更新：`2026-03-12`
+1. 完成支付异常自动重放与告警分层。
+2. 上线退款/售后后台最小版。
+3. 建立商业化运营看板（支付、续费、留存）。
+4. 完成权限矩阵自动化回归测试。

docs/payments/POLYGONSCAN_VERIFY.md

@@ -1,25 +1,23 @@
-# PolyWeatherCheckout PolygonScan 验证
+# PolyWeatherCheckout PolygonScan 验证（v1.4）
 
-目标合约地址：`0xD8101B3cA351fD7a9c00d2eBF226f6461Af33F10`  
-链：Polygon Mainnet (`chainId=137`)
+最后更新：`2026-03-14`
 
-## 1. 准备参数
+## 1. 目标
 
-- 编译器版本：`v0.8.24+commit.e11b9ed9`
-- 优化器：`Enabled`
-- Runs：`200`
-- 许可证：`MIT`
-- 合约路径：`contracts/PolyWeatherCheckout.sol`
-- 合约名：`PolyWeatherCheckout`
+对生产收款合约完成源码验证，降低钱包风控误报并提升用户信任。
 
-构造参数顺序（新版多代币合约）：
+## 2. 当前部署参数（示例）
 
-1. `_token` = `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`（初始允许代币）
-2. `_treasury` = `0xe581D578EF101c80e3F32263e97E6eA28A0B170e`
+- 链：Polygon Mainnet（`chainId=137`）
+- 合约：`PolyWeatherCheckout`
+- 编译器：`v0.8.24+commit.e11b9ed9`
+- 优化器：`Enabled`，`runs=200`
 
-## 2. 构造参数编码
+> 实际地址以线上配置为准：`POLYWEATHER_PAYMENT_RECEIVER_CONTRACT`。
 
-可直接用本仓库脚本：
+## 3. 构造参数编码
+
+使用仓库脚本生成构造参数：
 
 ```bash
 python scripts/encode_checkout_constructor.py \
@@ -27,35 +25,30 @@ python scripts/encode_checkout_constructor.py \
   --treasury 0xe581D578EF101c80e3F32263e97E6eA28A0B170e
 ```
 
-输出应为：
+将输出填入 PolygonScan 的 `Constructor Arguments ABI-encoded`。
 
-```text
-0000000000000000000000002791bca1f2de4661ed88a30c99a7a9449aa84174000000000000000000000000e581d578ef101c80e3f32263e97e6ea28a0b170e
-```
+## 4. PolygonScan 操作步骤
 
-把这串填到 PolygonScan 的 `Constructor Arguments ABI-encoded`。
-
-## 3. PolygonScan 页面操作
-
-1. 打开合约页面 -> `Contract` -> `Verify and Publish`.
+1. 打开合约页 -> `Contract` -> `Verify and Publish`。
 2. 选择 `Solidity (Single file)`。
-3. 粘贴 `contracts/PolyWeatherCheckout.sol` 全部源码。
-4. 按上面参数填写编译器和优化器。
-5. 粘贴编码后的构造参数，提交验证。
+3. 粘贴 `contracts/PolyWeatherCheckout.sol` 源码。
+4. 填写编译器/优化器参数。
+5. 粘贴构造参数并提交。
 
-## 4. 验证后检查
+## 5. 验证后检查
 
-验证成功后确认：
+- `Read Contract`：可见 `owner / treasury / allowedToken / paidOrder`
+- `Write Contract`：可见 `pay / setTreasury / setTokenAllowed`
+- 标签显示 `Contract Source Code Verified`
 
-- `Read Contract` 有 `owner / treasury / allowedToken / paidOrder`
-- `Write Contract` 有 `pay / setTreasury / setTokenAllowed`
-- `Contract` 标签显示 `Contract Source Code Verified`
+## 6. 双币种开启（USDC + USDC.e）
 
-## 5. 同时开启 USDC.e + Native USDC
+验证后可通过 `setTokenAllowed` 开启两种代币：
 
-验证后在 `Write Contract` 调用：
+- USDC.e: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
+- Native USDC: `0x3c499c542cef5e3811e1192ce70d8cc03d5c3359`
 
-- `setTokenAllowed(0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174, true)`  // USDC.e
-- `setTokenAllowed(0x3c499c542cef5e3811e1192ce70d8cc03d5c3359, true)`  // Native USDC
+## 7. 说明
 
-> 说明：钱包风控中的“欺诈/不可信”提示来自钱包安全引擎（如 Blockaid），源码验证能显著降低误报频率，但不保证 100% 立刻消失，通常需一段时间同步信誉缓存。
+- 源码验证能显著降低“欺诈/不可信”误报，但钱包风险缓存更新存在延迟。
+- 生产商用环境可使用私有升级版合约；公开仓库保留标准实现与验证流程。