feat: Introduce PolyWeather Pro commercialization, update project documentation, and add Telegram push utility.

2026-03-06 19:16:48 +08:00
parent 14838fde4d
commit 00f79139e1
5 changed files with 322 additions and 525 deletions
@@ -1,185 +1,141 @@
-# PolyWeather
+# 🌡️ PolyWeather Pro

-PolyWeather is a weather intelligence system built around live airport observations, multi-model forecasts, DEB blending, and Telegram alert delivery.
+> **Professional Weather Intelligence System** —— Specialized in edge data collection, DEB smart blending, and real-time decision alerts.

-Current production layout:
+---

- Frontend: Next.js on Vercel
- Backend API: FastAPI on VPS
- Bot / alert loop: Telegram bot on VPS
+## 💎 Project Vision

-The old FastAPI static web page has been removed. Vercel is the only web entry point.
+PolyWeather is a specialized intelligence system built for **Polymarket** high-stakes participants. We don't just provide weather forecasts; we aggregate data from top-tier global meteorological sources, apply our proprietary **DEB (Dynamic Error Balancing)** algorithm, and deliver **market-shifting alerts** at critical decision nodes.
+
+---
+
+## 🏗️ Production Architecture
+
+This project utilizes a production-grade decoupled architecture for high availability:
+
+- **Frontend**: A **Next.js** interactive dashboard deployed on **Vercel**.
+- **Backend API**: A **FastAPI** service running on a VPS, providing low-latency data access.
+- **Bot & Alert Heartbeat**: A **Telegram Bot** running on a VPS, executing minute-level global scans and push notifications.
+
+🔗 **Official Visit**: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)
+
+---
+
+## 🖼️ Preview & Interaction

 <p align="center">
-  <img src="docs/images/demo_ankara.png" alt="PolyWeather Demo - Ankara Live Analysis" width="420">
+  <img src="docs/images/demo_ankara.png" alt="PolyWeather Demo - Ankara Live Analysis" width="450">
  <br>
-  <em>📊 Live query: DEB Blended Forecast + Settlement Probability + Groq AI Decision</em>
+  <em>📊 <b>Deep Query View</b>: DEB Blended Forecast + Settlement Probability + Groq AI Expert Advice</em>
 </p>

 <p align="center">
-  <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="800">
+  <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
  <br>
-  <em>🗺️ Interactive Web Map: Real-time global monitoring with rich data visualization</em>
+  <em>🗺️ <b>Omni-Dashboard</b>: Real-time global heatmaps + array-style data visualization</em>
 </p>

-## Features
+---

- Multi-source weather aggregation
-  - Open-Meteo
-  - METAR live observations
-  - MGM official data for Ankara
-  - Multi-model highs such as ECMWF / GFS / ICON / GEM / JMA when available
- DEB blended forecast
-  - Dynamic weighting based on recent model error
- City dashboard
-  - Global city list
-  - City detail panel
-  - Nearby station map markers
-  - Trend chart
-  - Multi-model comparison
-  - Daily forecast table
- Telegram proactive alerts
-  - Ankara Center reached DEB
-  - Momentum spike
-  - Forecast breakthrough
-  - Advection / nearby lead station signal
- Late-day suppression
-  - If the local daily high has likely already passed and the market is cooling off, active alerts are downgraded to status only and are not pushed
+## 🚀 Core Features

-## Alert Rules
+- **📡 Full-Spectrum Collection**
+  - **Major Models**: Real-time sync for ECMWF, GFS, ICON, GEM, and JMA high temperatures.
+  - **Observed Data**: Global airport METAR reports + official Turkish MGM station-level data.
+  - **Centralized Correction**: Integrated `17130` (Center) official data specifically for Ankara.
+- **⚖️ DEB Smart Blending**
+  - Dynamic weighting of forecasts based on recent 7-day historical performance.
+- **🔔 Alert Engine**
+  - **Momentum Spike**: Captures rapid temperature changes within 30 minutes.
+  - **Forecast Breakthrough**: Fires when observations exceed all model predictions plus a safety margin.
+  - **Advection Monitoring**: Simulates warm/cold advection based on lead stations and wind currents.
+- **🛡️ Smart Suppression**
+  - **Peak Protection**: Automatically switches to snapshot mode when the daily high has likely passed.
+  - **Cooldown Management**: Global and city-level cooldowns to prevent notification fatigue.

-Implemented rules:
+---

- `ankara_center_deb_hit`
-  - Only uses `Ankara (Bolge/Center)` station / `istNo=17130`
-  - This is the official Ankara center station used for the Center signal
- `momentum_spike`
-  - 30-minute slope exceeds the configured threshold
- `forecast_breakthrough`
-  - Current observed temperature is above the highest available major model high by margin
- `advection`
-  - Nearby station leads the airport station and wind regime supports warm advection
+## 🔐 Alert Logic Details

-Suppression rule:
+| Trigger Name     | Core Logic                                    | Trading Value                                 |
+| :--------------- | :-------------------------------------------- | :-------------------------------------------- |
+| **Center Hit**   | Detects DEB trigger only at Ankara HQ `17130` | **Highest priority signal**, the "truth"      |
+| **Momentum**     | 30min temperature slope exceed threshold      | Captures sudden weather fronts                |
+| **Breakthrough** | Pierces all model highs + margin              | Captures high-volatility outlier events       |
+| **Advection**    | Lead station rise + Wind match                | Gain 20-40 minutes of lead time for execution |

- `peak_passed_guard`
-  - No active push if the city's local peak has already passed, enough time has elapsed, and the current temperature has materially rolled over from the day's high
+---

-Push dedupe rule:
-
- Same city + same trigger type only pushes once while still active
- It can push again only after the signal clears and re-arms
- Cooldown still applies at city level
-
-## Data Semantics
-
-Alert message fields:
-
- `实测 / Now`
-  - Uses `METAR current.temp` first
-  - Falls back to `MGM current.temp` if METAR current temperature is unavailable
- `时间 / Time`
-  - `local`: city local clock time
-  - `observed`: observation time attached to the current reading
-
-## Deployment
-
-### Backend / bot on VPS
-
-Requirements:
-
- Docker
- Docker Compose
- `.env`
-
-Deploy:
-
-```bash
-git pull
-docker-compose up -d --build
-```
-
-Main services:
-
- `polyweather_bot`
- `polyweather_web`
-
-The FastAPI service is now API-only. It does not serve a static website.
-
-### Frontend on Vercel
-
-The Vercel project uses the `frontend` directory as root.
-
-After pushing to Git, Vercel deploys automatically.
-
-## Environment Variables
-
-Minimum practical set:
-
-```env
-TELEGRAM_BOT_TOKEN=...
-TELEGRAM_CHAT_ID=...
-GROQ_API_KEY=...
-POLYWEATHER_MAP_URL=https://polyweather-pro.vercel.app/
-WEB_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,https://polyweather-pro.vercel.app
-```
-
-Push tuning:
-
-```env
-TELEGRAM_ALERT_PUSH_ENABLED=true
-TELEGRAM_ALERT_PUSH_INTERVAL_SEC=300
-TELEGRAM_ALERT_PUSH_COOLDOWN_SEC=3600
-TELEGRAM_ALERT_MIN_TRIGGER_COUNT=2
-TELEGRAM_ALERT_MIN_SEVERITY=medium
-TELEGRAM_ALERT_CITIES=ankara,london,paris,seoul,toronto,buenos aires,wellington,new york,chicago,dallas,miami,atlanta,seattle,lucknow,sao paulo,munich
-```
-
-Recommended:
-
- Use `3600` seconds cooldown for production paid groups unless you explicitly want more aggressive alerting
-
-## Bot Commands
-
-Supported user commands:
-
- `/city [city]`
- `/deb [city]`
- `/id`
- `/help`
-
-`/tradealert` has been removed. Alerts are proactive push only.
-
-## Architecture
+## 🏗️ System Architecture

 ```mermaid
 graph TD
-    User[Telegram User] --> Bot[bot_listener.py]
-    User2[Web User] --> Vercel[Next.js on Vercel]
-    Vercel --> API[FastAPI API on VPS]
-    Bot --> API
-    API --> Collector[WeatherDataCollector]
-    Collector --> OM[Open-Meteo]
-    Collector --> METAR[METAR]
-    Collector --> MGM[MGM]
-    Collector --> MM[Multi-model sources]
-    API --> DEB[DEB blending]
-    API --> Alerts[Alert engine]
-    Alerts --> Bot
+    subgraph "Client / Terminals"
+        Web[Next.js Web App]
+        TG[Telegram Client]
+    end
+
+    subgraph "Edge Deployment (Vercel)"
+        Web -.-> |Auth| Supa[(Supabase Auth/DB)]
+        Web --> |API| Fast[FastAPI API]
+    end
+
+    subgraph "Core Hub (VPS)"
+        Fast --- |Shared Logic| Worker[Alert Engine / Worker]
+        Bot[Telegram Bot] --- |Shared Logic| Worker
+        Worker --> |Cache/Sub| Supa
+    end
+
+    subgraph "External Sources"
+        Worker --> |Pull| MGM[MGM Weather]
+        Worker --> |Pull| METAR[Airport METAR]
+        Worker --> |Pull| OM[Open-Meteo]
+        Worker --> |Pull| MM[Multi-Model Integration]
+    end
+
+    Worker --> |Push Alert| TG
+    Bot --> |Query| Worker
 ```

-## Testing
+---

-Quick checks used in development:
+## 🛠️ Deployment
+
+### 1. Backend / Bot (VPS)

 ```bash
-python -m py_compile src/analysis/market_alert_engine.py src/utils/telegram_push.py web/app.py bot_listener.py
-node --check frontend/public/static/app.js
-npm run build --prefix frontend
+# Pull Source
+git pull
+
+# Environment
+# Edit .env with TELEGRAM_BOT_TOKEN and other keys
+
+# Launch
+docker-compose up -d --build
 ```

-If you want to run pytest, install it first.
+### 2. Frontend (Vercel)

-## Status
+Associate the `frontend` directory as the project root on Vercel for automatic CI/CD.

-Last updated: 2026-03-06
+---
+
+## 💬 Bot Commands
+
+| Command   | Description                             | Example        |
+| :-------- | :-------------------------------------- | :------------- |
+| `/city`   | Query real-time analysis for a city     | `/city ankara` |
+| `/deb`    | View historical accuracy of DEB model   | `/deb london`  |
+| `/points` | View your activity points & leaderboard | `/points`      |
+| `/help`   | Get detailed instructions               | `/help`        |
+
+---
+
+> [!NOTE]
+> **Commercialization**: This project currently offers **Web Dashboard ($5/mo)** and **Telegram Signal Channel ($1/mo)** subscriptions.
+> Point-earning via group participation is active and points can be redeemed for access.
+
+---
+
+**📅 Last Updated**: 2026-03-06
@@ -1,185 +1,141 @@
-# PolyWeather
+# 🌡️ PolyWeather Pro

-PolyWeather 是一套围绕实时机场观测、多模型预报、DEB 融合和 Telegram 主动推送构建的天气情报系统。
+> **专业级博弈情报系统** —— 专注边缘气象数据采集、DEB 智能融合与实时决策预警。

-当前生产架构：
+---

- 前端：Vercel 上的 Next.js
- 后端 API：VPS 上的 FastAPI
- 机器人与预警循环：VPS 上的 Telegram Bot
+## 💎 项目愿景

-FastAPI 旧静态网页已经移除。Vercel 是唯一网页入口。
+PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报系统。我们不只是提供天气预报，而是通过聚合全球顶级气象源、应用自研的 **DEB (Dynamic Error Balancing)** 算法，并在关键时间节点提供**具有博弈预测价值**的异动预警。
+
+---
+
+## 🏗️ 生产架构
+
+本项目采用生产级解耦架构，确保高可用与实时性：
+
+- **前端**：部署在 **Vercel** 上的 **Next.js** 交互式仪表盘。
+- **后端 API**：运行在 VPS 上的 **FastAPI**，提供低延迟数据服务。
+- **机器人与预警心跳**：运行在 VPS 上的 **Telegram Bot**，执行每分钟级的全球扫描与推送。
+
+🔗 **官方访问地址**：[polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)
+
+---
+
+## 🖼️ 预览与交互

 <p align="center">
-  <img src="docs/images/demo_ankara.png" alt="PolyWeather 效果展示 - 安卡拉实时分析" width="420">
+  <img src="docs/images/demo_ankara.png" alt="PolyWeather 效果展示 - 安卡拉实时分析" width="450">
  <br>
-  <em>📊 实时查询效果：DEB 融合预测 + 结算概率 + Groq AI 决策</em>
+  <em>📊 <b>深度查询效果</b>：DEB 融合预测 + 结算概率 + Groq AI 专家建议</em>
 </p>

 <p align="center">
-  <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="800">
+  <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
  <br>
-  <em>🗺️ 交互式网页地图：全球城市实时监控与丰富的数据可视化</em>
+  <em>🗺️ <b>全景仪表盘</b>：全球站点实时热力场 + 阵列式数据展示</em>
 </p>

-## 当前功能
+---

- 多源天气采集
-  - Open-Meteo
-  - METAR 实时观测
-  - 安卡拉官方 MGM 数据
-  - ECMWF / GFS / ICON / GEM / JMA 等多模型最高温
- DEB 融合预报
-  - 基于近期误差动态调权
- 网页仪表盘
-  - 全球监控城市列表
-  - 城市详情面板
-  - 周边站点地图标记
-  - 今日趋势图
-  - 多模型对比
-  - 多日预报表
- Telegram 主动预警
-  - Ankara Center 达到 DEB
-  - 动量突变
-  - 预测突破
-  - 暖平流 / 周边站联动
- 晚盘压制逻辑
-  - 当地高温大概率已经兑现且开始回落时，预警降级为状态快照，不主动推送
+## 🚀 核心功能

-## 预警规则
+- **📡 多源全量采集**
+  - **主流模型**：ECMWF, GFS, ICON, GEM, JMA 实时最高温同步。
+  - **实测数据**：全球机场 METAR 定时报文 + 土耳其 MGM 局点官方实测。
+  - **中心化纠偏**：针对安卡拉特别接入 `17130` (Center) 官方指挥中心数据。
+- **⚖️ DEB 智能融合**
+  - 基于近期 7 天历史表现，动态调整各模型权重的博弈预测。
+- **🔔 异动预警系统 (Alert Engine)**
+  - **动量突变**：捕捉 30 分钟内的急剧温变。
+  - **预测突破**：当实测击穿所有预报上限时触发告警。
+  - **平流监测**：基于周边前导站的风向流场模拟，预测冷/暖平流的到达。
+- **🛡️ 智能压制逻辑**
+  - **峰值保护**：当日高温峰值大概率已过时，自动转为静默/快照模式，拒绝骚扰。
+  - **冷却管理**：同一信号路径支持全局与城市级双重 CD。

-当前启用的规则：
+---

- `ankara_center_deb_hit`
-  - 只使用 `Ankara (Bolge/Center)` 站点，`istNo=17130`
-  - 这是安卡拉 Center 信号唯一认可的官方站点
- `momentum_spike`
-  - 30 分钟温度斜率超过阈值
- `forecast_breakthrough`
-  - 当前实测温度高于主流模型最高值，并超过安全边际
- `advection`
-  - 周边站领先升温，且风向与暖平流传播方向匹配
+## 🔐 预警逻辑深度说明

-压制规则：
+| 触发器名称       | 核心逻辑                                     | 博弈价值                           |
+| :--------------- | :------------------------------------------- | :--------------------------------- |
+| **Center Hit**   | 仅识别安卡拉总部 `17130` 站点的 DEB 触发信号 | **最高级信号**，定盘星             |
+| **Momentum**     | 30min 温度斜率超过                           | 捕捉突发天气系统（如锋面）         |
+| **Breakthrough** | 击穿所有预报上限 + 安全边际                  | 捕捉市场极少数情况下的暴利点       |
+| **Advection**    | 前导站温升 + 风向匹配                        | 获得 20-40 分钟的提前离场/建仓时间 |

- `peak_passed_guard`
-  - 当地高点已经过去、间隔足够长、且温度已从日内高点明显回落时，不再主动推送
+---

-去重规则：
-
- 同一城市、同一 trigger type，只会在激活时推送一次
- 只有信号先解除，再重新触发，才允许再次推送
- 同时仍保留城市级 cooldown
-
-## 数据语义
-
-预警文案中的字段：
-
- `实测`
-  - 优先使用 `METAR current.temp`
-  - 如果 METAR 当前温度不可用，再退回 `MGM current.temp`
- `时间`
-  - `当地`：城市本地当前时间
-  - `观测`：这条实测温度对应的观测时间
-
-## 部署
-
-### VPS 后端 / 机器人
-
-要求：
-
- Docker
- Docker Compose
- `.env`
-
-部署命令：
-
-```bash
-git pull
-docker-compose up -d --build
-```
-
-主要服务：
-
- `polyweather_bot`
- `polyweather_web`
-
-现在的 FastAPI 只提供 API，不再承载网页静态资源。
-
-### Vercel 前端
-
-Vercel 项目根目录使用 `frontend`。
-
-代码推送后，Vercel 会自动部署。
-
-## 环境变量
-
-最小可用集合：
-
-```env
-TELEGRAM_BOT_TOKEN=...
-TELEGRAM_CHAT_ID=...
-GROQ_API_KEY=...
-POLYWEATHER_MAP_URL=https://polyweather-pro.vercel.app/
-WEB_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,https://polyweather-pro.vercel.app
-```
-
-预警推送调优：
-
-```env
-TELEGRAM_ALERT_PUSH_ENABLED=true
-TELEGRAM_ALERT_PUSH_INTERVAL_SEC=300
-TELEGRAM_ALERT_PUSH_COOLDOWN_SEC=3600
-TELEGRAM_ALERT_MIN_TRIGGER_COUNT=2
-TELEGRAM_ALERT_MIN_SEVERITY=medium
-TELEGRAM_ALERT_CITIES=ankara,london,paris,seoul,toronto,buenos aires,wellington,new york,chicago,dallas,miami,atlanta,seattle,lucknow,sao paulo,munich
-```
-
-生产环境建议：
-
- 付费群默认使用 `3600` 秒 cooldown，避免同一城市短时间内刷屏
-
-## 机器人命令
-
-当前保留的命令：
-
- `/city [city]`
- `/deb [city]`
- `/id`
- `/help`
-
-`/tradealert` 已移除。预警只支持主动推送。
-
-## 架构
+## 🏗️ 架构解析

 ```mermaid
 graph TD
-    User[Telegram 用户] --> Bot[bot_listener.py]
-    User2[网页用户] --> Vercel[Next.js on Vercel]
-    Vercel --> API[FastAPI API on VPS]
-    Bot --> API
-    API --> Collector[WeatherDataCollector]
-    Collector --> OM[Open-Meteo]
-    Collector --> METAR[METAR]
-    Collector --> MGM[MGM]
-    Collector --> MM[多模型数据源]
-    API --> DEB[DEB 融合]
-    API --> Alerts[预警引擎]
-    Alerts --> Bot
+    subgraph "客户端 / 终端"
+        Web[Next.js 网页端]
+        TG[Telegram 客户端]
+    end
+
+    subgraph "云端部署 (Vercel)"
+        Web -.-> |Auth| Supa[(Supabase Auth/DB)]
+        Web --> |API| Fast[FastAPI API]
+    end
+
+    subgraph "核心引擎 (VPS)"
+        Fast --- |Shared Logic| Worker[Alert Engine / Worker]
+        Bot[Telegram Bot] --- |Shared Logic| Worker
+        Worker --> |Cache/Sub| Supa
+    end
+
+    subgraph "外部数据源"
+        Worker --> |Pull| MGM[MGM 气象局]
+        Worker --> |Pull| METAR[机场实测]
+        Worker --> |Pull| OM[Open-Meteo]
+        Worker --> |Pull| MM[多模型集成]
+    end
+
+    Worker --> |Push Alert| TG
+    Bot --> |Query| Worker
 ```

-## 测试
+---

-开发时常用快速检查：
+## 🛠️ 部署指南
+
+### 1. 后端 / 机器人 (VPS)

 ```bash
-python -m py_compile src/analysis/market_alert_engine.py src/utils/telegram_push.py web/app.py bot_listener.py
-node --check frontend/public/static/app.js
-npm run build --prefix frontend
+# 获取源码
+git pull
+
+# 环境配置
+# 编辑 .env 文件，填入 TELEGRAM_BOT_TOKEN 等关键参数
+
+# 一键启动
+docker-compose up -d --build
 ```

-如果要跑 pytest，请先安装 pytest。
+### 2. 前端 (Vercel)

-## 状态
+直接关联本项目 `frontend` 目录作为根目录即可，享受自动 CI/CD。

-最后更新：2026-03-06
+---
+
+## 💬 机器人指令
+
+| 命令      | 说明                      | 示例           |
+| :-------- | :------------------------ | :------------- |
+| `/city`   | 查询指定城市实时分析      | `/city ankara` |
+| `/deb`    | 查看 DEB 模型的历史准确率 | `/deb london`  |
+| `/points` | 查看您的活跃积分与排行榜  | `/points`      |
+| `/help`   | 获取详细功能说明          | `/help`        |
+
+---
+
+> [!NOTE]
+> **商业化提示**：本项目目前提供 **Web 仪表盘 ($5/月)** 与 **Telegram 信号频道 ($1/月)** 订阅服务。
+> 发言获取积分逻辑已上线，活跃用户可兑换相应权限。
+
+---
+
+**📅 最后更新**：2026-03-06
@@ -1,141 +1,79 @@
-# Commercialization Plan
+# 📈 Commercialization Roadmap

-## Product Direction
+> **Target**: Transforming PolyWeather for paid weather intelligence delivery.

-PolyWeather is being positioned as a paid weather intelligence product built around:
- Web dashboard subscription
- Telegram paid group subscription
- Fast, rules-based weather alerting
- High-confidence Ankara specialization
+---

-Current pricing target:
- Web dashboard: $5 / month
- Telegram paid group: $1 / month
+## 🎯 Product Focus

-Current payment direction under discussion:
- Polygon / USDC
+PolyWeather is positioned as a **premium intelligence service** for weather-based prediction markets (**Polymarket**). The value proposition lies in **Ankara-specialization**, **advanced advection forecasting**, and **DEB-weighted consensus**.

-Important current state:
- Polymarket market-price integration has been removed from the codebase
- The current product focuses on weather intelligence, not exchange/orderbook execution data
+---

-## Production Architecture
+## 💰 Pricing & Monetization

-### Web
- Next.js frontend on Vercel
- Public URL: `https://polyweather-pro.vercel.app/`
- FastAPI backend serves API only
+| Tier                 | Price         | Primary Value Proposition                                     |
+| :------------------- | :------------ | :------------------------------------------------------------ |
+| **Telegram Channel** | **$1 / mo**   | High-fidelity proactive alerts, low noise.                    |
+| **Web Dashboard**    | **$5 / mo**   | Comprehensive multi-model view + historical MAE benchmarking. |
+| **VIP Bundle**       | **$5.5 / mo** | Full access to all intelligence streams.                      |

-### Backend
- FastAPI on VPS
- Shared analysis layer for web and bot
- City data cache in-process
+### 🛠️ Payment Infrastructure

-### Telegram
- Bot runs on VPS
- Paid group receives proactive alerts
- Push engine includes dedupe, cooldown, and late-day suppression
+- **Currency**: Polygon / USDC.
+- **Method**: Initially manual activation; migrating to automatic deposit detection (Phase 2).

-## Alert Product Strategy
+---

-Current alert strategy is weather-first:
- Ankara Center reached DEB
- Momentum spike
- Forecast breakthrough
- Advection / nearby lead station
+## 🗺️ Execution Roadmap

-Operational controls already implemented:
- Same city + same trigger type only pushes once while active
- City-level cooldown
- Peak-passed suppression for late-day rollover
+```mermaid
+graph LR
+    P1[Phase 1: Manual Beta] --> P2[Phase 2: USDC Automation]
+    P2 --> P3[Phase 3: Scaling & Analytics]

-Ankara special handling:
- Center signal only uses `Ankara (Bolge/Center)` / `17130`
- This should remain a product differentiator and be documented clearly in sales copy
+    subgraph P1_Detail [Manual Operations]
+        P1 -->|DM Bot| Pay[Manual Payment]
+        Pay -->|Invite| Link[One-time Link]
+    end

-## Recommended Subscription Structure
+    subgraph P2_Detail [Smart Automation]
+        P2 -->|Monitor| Chain[Polygon/USDC]
+        Chain -->|Auto| Access[JWT/Sub Activation]
+    end
+```

-### Tier A: Telegram Group
- Price: $1 / month
- Value proposition:
-  - Real-time proactive weather alerts
-  - Fast anomaly delivery
-  - Focused operational signal, minimal clutter
- Suggested restrictions:
-  - No raw API access
-  - No historical analytics export
-  - No advanced chart controls
+### 📦 Phase 1: Manual Beta

-### Tier B: Web Dashboard
- Price: $5 / month
- Value proposition:
-  - Full city dashboard
-  - Trend and nearby-station visualization
-  - Multi-model comparison
-  - Historical view
- Suggested restrictions:
-  - View-only unless future premium tools are added
+- **Goal**: Stabilize current alert quality and build core user group.
+- **Actions**:
+  - Manual subscription activation via Telegram DM.
+  - Small, focused paid Telegram channel for signal tests.
+  - Invitation-only Web Access (Vercel).

-### Bundle Option
- Optional future bundle: Web + Group
- Use only if conversion data shows users want both together
+### 🛠️ Phase 2: Automation (USDC)

-## Payment Roadmap
+- **Goal**: Reduce operational friction.
+- **Actions**:
+  - **On-chain monitoring**: Detect USDC deposits to unique addresses.
+  - **One-time Links**: Telegram bot automatically generates invite links with `member_limit=1`.
+  - **JWT Auth**: Securing the Next.js frontend with subscriber-only tokens.

-### Phase 1: Manual Ops
- User pays manually
- Operator manually activates web access / Telegram access
- Lowest engineering cost, fastest launch
+### 🌐 Phase 3: Scaling & Analytics

-### Phase 2: Polygon / USDC Automation
- Generate unique deposit address or payment intent
- Confirm on-chain payment
- Activate subscription automatically
- Telegram bot issues one-time group invite link
+- **Goal**: Retention and expansion.
+- **Actions**:
+  - **Accuracy Leaderboard**: Monthly reports of DEB vs Market outcomes.
+  - **Self-Serve Portal**: User dashboard for billing and alert settings.

-### Phase 3: Full Subscription Management
- Renewal reminders
- Grace period handling
- Automatic expiry / revocation
- Self-serve billing status page
+---

-## Recommended Near-Term Roadmap
+## 🚧 Critical Constraints

-### Step 1: Stabilize Current Product
- Finish cleaning docs and deployment flow
- Keep Vercel as the only web entry point
- Keep backend API-only
- Tune Telegram cooldown and trigger quality
+- **Weather-First**: We focus on the **physical variable changes** rather than exchange-side order book execution.
+- **Quality > Quantity**: Alert fatigue will churn subscribers. We enforce a "True Probability Shift" rule for notifications.
+- **Local Niche**: Ankara is our flagship differentiator.

-### Step 2: Launch Manual Paid Beta
- Start with a small paid Telegram group
- Start web dashboard on invite basis
- Track which alert types users actually value
+---

-### Step 3: Add Access Control
- Web login and session layer
- Subscription table in backend
- Telegram membership verification
-
-### Step 4: Add Polygon / USDC Collection
- Payment detection
- Subscription activation
- One-time Telegram invite issuance
-
-## Metrics To Track
-
-Minimum metrics before scaling:
- Alert-to-action usefulness feedback
- Daily active dashboard users
- Telegram retention after first payment cycle
- Most valuable cities by engagement
- False-positive complaint rate for alerts
-
-## Constraints To Keep In Mind
-
- The current system is strongest in weather intelligence, not execution plumbing
- Ankara is a differentiated niche and should be treated as premium signal inventory
- Over-pushing alerts will destroy paid-group value faster than under-pushing
- Payment automation should come after alert quality is operationally stable
-
-Last updated: 2026-03-06
+**📅 Last Updated**: 2026-03-06
@@ -1,115 +1,65 @@
-# Technical Debt
+# 🛠️ Technical Debt & Engineering Backlog

-Last updated: 2026-03-06
+> **Vision**: Moving from a research script to a production SaaS.

-## Current State
+---

-Overall system status: usable and deployable.
+## 🏛️ System Health: 75%

-Stable pieces:
- Multi-source weather collection
- DEB forecast blending
- Web dashboard on Vercel
- FastAPI API backend
- Telegram proactive push loop
- Alert dedupe and cooldown
- Late-day peak suppression
+```mermaid
+pie title System Health & Tech Debt
+    "Stable Engine" : 75
+    "Centralized Logic Debt" : 10
+    "Subscription DB Debt" : 10
+    "Testing/Replay Debt" : 5
+```

-Recently removed:
- Old FastAPI static web page
- Polymarket market-price integration
- `/tradealert` preview command
+The core engine is stable, but several infrastructure "shortcut" decisions remain.

-## High-Priority Debt
+### Current Stable Modules

-### 1. Bot orchestration is still too centralized
-`bot_listener.py` is operational, but too much runtime behavior is still coordinated from a single entrypoint.
+- [x] Multi-source Weather Aggregation
+- [x] DEB Blending Algorithm
+- [x] Proactive Telegram Alert Engine
+- [x] Vercel Dashboard Infrastructure

-Impact:
- Harder to test
- Harder to evolve subscription logic
- Harder to isolate push bugs
+---

-Suggested direction:
- Keep moving push and analysis concerns into `src/utils` and `src/analysis`
+## 🔴 High Priority: Immediate Focus

-### 2. Alert transparency needs better operator visibility
-The system now pushes the correct trigger types more conservatively, but group operators still need better evidence lines.
+| Debt Item              | Impact                                              | Suggested Fix                                                    |
+| :--------------------- | :-------------------------------------------------- | :--------------------------------------------------------------- |
+| **Monolithic Bot**     | `bot_listener.py` is hard to test and evolve.       | Isolate UI interaction from business logic into `src/analysis`.  |
+| **Subscription Store** | No persistent record of who has paid.               | Migrate from in-memory user checks to **Supabase/PostgreSQL**.   |
+| **Alert Transparency** | Operators cannot easily audit "why" an alert fired. | Add an `Evidence` metadata block to all internal alert payloads. |

-Impact:
- Hard to audit why a message fired
- Hard to distinguish strong vs weak advection calls
+---

-Suggested direction:
- Add a compact `依据 / Evidence` line to alert messages
- Expose raw trigger metrics in a debug API or operator log
+## 🟡 Medium Priority: Quality of Life

-### 3. No persistent application store for subscriptions
-Current architecture is ready for commercialization planning, but there is no real subscription state model yet.
+| Debt Item                 | Impact                                              | Suggested Fix                                                                |
+| :------------------------ | :-------------------------------------------------- | :--------------------------------------------------------------------------- |
+| **Hard-coded Thresholds** | Modification requires code changes (e.g., 5s CD).   | Extract all business constants into a structured `config.yaml`.              |
+| **Simulation Harness**    | No way to "replay" a rainy day to test alert logic. | Build a `ReplayEngine` using `data/daily_records.json`.                      |
+| **Backend Naming**        | Artifacts of "market price" logic remain in naming. | Systematic refactor of variable names to reflect weather-intelligence focus. |

-Impact:
- No paid access enforcement
- No renewal logic
- No expiry / access revocation
+---

-Suggested direction:
- Add a database-backed subscription table before automating billing
+## 🟢 Low Priority: Optimization

-## Medium-Priority Debt
+| Debt Item                  | Impact                                          | Suggested Fix                                                  |
+| :------------------------- | :---------------------------------------------- | :------------------------------------------------------------- |
+| **Serverless Cold Starts** | Initial Vercel API calls can be slow.           | Implement edge-cache or warming cron for major city endpoints. |
+| **Local SQLite Files**     | Not compatible with Vercel's ephemeral storage. | Full transition to a remote DB (Supabase/Redis).               |

-### 4. Backtesting is still missing
-The system has live rules, but no proper replay framework for validating whether rule changes improve quality.
+---

-Impact:
- Rule changes are hard to evaluate objectively
- Alert tuning is still partly manual
+## 🗓️ Next Milestones

-Suggested direction:
- Build a replay harness from stored observations and forecasts
+1.  **DB Integration**: Connect Supabase to `src/database/db_manager.py`.
+2.  **Alert Transparency**: Append logic metrics (slope, lead delta) to push messages.
+3.  **Authentication**: Secure `/api/city` on Vercel with subscription keys.

-### 5. Thresholds remain code-defined
-Important thresholds are still embedded in Python.
+---

-Examples:
- Momentum slope threshold
- Peak-passed rollback threshold
- Advection lead delta threshold
- Cooldown defaults
-
-Suggested direction:
- Extract to constants or structured config
-
-### 6. Frontend still uses a legacy shell inside Next
-The production frontend is on Vercel, but the page is still driven by `public/legacy/index.html` plus static scripts.
-
-Impact:
- Slower UI evolution
- Harder component-level reuse
- Harder design-system integration
-
-Suggested direction:
- Migrate the legacy dashboard into native Next components incrementally
-
-## Low-Priority Debt
-
-### 7. Caching is simple in-process cache only
-Current cache is sufficient for the current deployment size, but not ideal long term.
-
-Suggested direction:
- Move to Redis or another shared cache if multi-instance deployment is needed
-
-### 8. Test tooling is not fully provisioned everywhere
-The repository has tests, but some environments still do not have `pytest` installed.
-
-Impact:
- Harder to run full verification on every host
-
-Suggested direction:
- Standardize test dependencies in deployment and CI environments
-
-## Immediate Next Steps
-
-1. Add evidence lines to Telegram alerts
-2. Finish cleaning backend naming after removal of old static web flow
-3. Design subscription storage for commercialization
-4. Start replay/backtest tooling for alert-quality tuning
+**📅 Last Updated**: 2026-03-06
@@ -256,14 +256,14 @@ def start_trade_alert_push_loop(bot: Any, config: Dict[str, Any]) -> Optional[th
    def _runner() -> None:
        logger.info(
            f"telegram alert push loop started cities={len(cities)} interval={interval_sec}s "
-            f"cooldown={cooldown_sec}s min_triggers={min_trigger_count} min_severity={min_severity}"
+            f"cooldown={cooldown_sec}s min_triggers={min_trigger_count} min_severity={min_severity} "
+            f"state_path={state_path}"
        )
        while True:
            cycle_started = time.time()
            state = _load_state(state_path)
            _cleanup_state(state, int(cycle_started))

-            changed = False
            for city in cities:
                try:
                    alert_payload = build_trade_alert_for_city(city, config)
@@ -277,17 +277,14 @@ def start_trade_alert_push_loop(bot: Any, config: Dict[str, Any]) -> Optional[th
                        min_severity=min_severity,
                        min_trigger_count=min_trigger_count,
                    ):
-                        changed = True
+                        try:
+                            _save_state(state_path, state)
+                        except Exception:
+                            logger.exception(f"failed to save telegram push state city={city}")
                except Exception:
                    logger.exception(f"telegram alert push loop failed for city={city}")
                time.sleep(1)

-            if changed:
-                try:
-                    _save_state(state_path, state)
-                except Exception:
-                    logger.exception("failed to save telegram push state")
-
            elapsed = time.time() - cycle_started
            sleep_sec = max(5, interval_sec - int(elapsed))
            time.sleep(sleep_sec)