gavindiaz/PolyWeather
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
2569718930@qq.com
2026-03-06 19:16:48 +08:00
parent 14838fde4d
commit 00f79139e1
5 changed files with 322 additions and 525 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+109 -153
View File
@@ -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 ## 💎 Project Vision
- Backend API: FastAPI on VPS
- Bot / alert loop: Telegram bot on VPS
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"> <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> <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>
<p align="center"> <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> <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> </p>
## Features ---
- Multi-source weather aggregation ## 🚀 Core Features
- 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
## 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` ## 🔐 Alert Logic Details
- 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
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: ## 🏗️ System Architecture
- 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
```mermaid ```mermaid
graph TD graph TD
User[Telegram User] --> Bot[bot_listener.py] subgraph "Client / Terminals"
User2[Web User] --> Vercel[Next.js on Vercel] Web[Next.js Web App]
Vercel --> API[FastAPI API on VPS] TG[Telegram Client]
Bot --> API end
API --> Collector[WeatherDataCollector]
Collector --> OM[Open-Meteo] subgraph "Edge Deployment (Vercel)"
Collector --> METAR[METAR] Web -.-> |Auth| Supa[(Supabase Auth/DB)]
Collector --> MGM[MGM] Web --> |API| Fast[FastAPI API]
Collector --> MM[Multi-model sources] end
API --> DEB[DEB blending]
API --> Alerts[Alert engine] subgraph "Core Hub (VPS)"
Alerts --> Bot 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 ```bash
python -m py_compile src/analysis/market_alert_engine.py src/utils/telegram_push.py web/app.py bot_listener.py # Pull Source
node --check frontend/public/static/app.js git pull
npm run build --prefix frontend
# 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
README_ZH.md
+109 -153
View File
@@ -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"> <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> <br>
<em>📊 实时查询效果：DEB 融合预测 + 结算概率 + Groq AI 决策</em> <em>📊 <b>深度查询效果</b>：DEB 融合预测 + 结算概率 + Groq AI 专家建议</em>
</p> </p>
<p align="center"> <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> <br>
<em>🗺️ 交互式网页地图：全球城市实时监控与丰富的数据可视化</em> <em>🗺️ <b>全景仪表盘</b>：全球站点实时热力场 + 阵列式数据展示</em>
</p> </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 ```mermaid
graph TD graph TD
User[Telegram 用户] --> Bot[bot_listener.py] subgraph "客户端 / 终端"
User2[网页用户] --> Vercel[Next.js on Vercel] Web[Next.js 网页端]
Vercel --> API[FastAPI API on VPS] TG[Telegram 客户端]
Bot --> API end
API --> Collector[WeatherDataCollector]
Collector --> OM[Open-Meteo] subgraph "云端部署 (Vercel)"
Collector --> METAR[METAR] Web -.-> |Auth| Supa[(Supabase Auth/DB)]
Collector --> MGM[MGM] Web --> |API| Fast[FastAPI API]
Collector --> MM[多模型数据源] end
API --> DEB[DEB 融合]
API --> Alerts[预警引擎] subgraph "核心引擎 (VPS)"
Alerts --> Bot 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 ```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 git pull
npm run build --prefix frontend
# 环境配置
# 编辑 .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
docs/COMMERCIALIZATION.md
+54 -116
View File
@@ -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: ## 🎯 Product Focus
- Web dashboard: $5 / month
- Telegram paid group: $1 / month
Current payment direction under discussion: 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**.
- Polygon / USDC
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 | Tier | Price | Primary Value Proposition |
- Next.js frontend on Vercel | :------------------- | :------------ | :------------------------------------------------------------ |
- Public URL: `https://polyweather-pro.vercel.app/` | **Telegram Channel** | **$1 / mo** | High-fidelity proactive alerts, low noise. |
- FastAPI backend serves API only | **Web Dashboard** | **$5 / mo** | Comprehensive multi-model view + historical MAE benchmarking. |
| **VIP Bundle** | **$5.5 / mo** | Full access to all intelligence streams. |
### Backend ### 🛠️ Payment Infrastructure
- FastAPI on VPS
- Shared analysis layer for web and bot
- City data cache in-process
### Telegram - **Currency**: Polygon / USDC.
- Bot runs on VPS - **Method**: Initially manual activation; migrating to automatic deposit detection (Phase 2).
- Paid group receives proactive alerts
- Push engine includes dedupe, cooldown, and late-day suppression
## Alert Product Strategy ---
Current alert strategy is weather-first: ## 🗺️ Execution Roadmap
- Ankara Center reached DEB
- Momentum spike
- Forecast breakthrough
- Advection / nearby lead station
Operational controls already implemented: ```mermaid
- Same city + same trigger type only pushes once while active graph LR
- City-level cooldown P1[Phase 1: Manual Beta] --> P2[Phase 2: USDC Automation]
- Peak-passed suppression for late-day rollover P2 --> P3[Phase 3: Scaling & Analytics]
Ankara special handling: subgraph P1_Detail [Manual Operations]
- Center signal only uses `Ankara (Bolge/Center)` / `17130` P1 -->|DM Bot| Pay[Manual Payment]
- This should remain a product differentiator and be documented clearly in sales copy 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 ### 📦 Phase 1: Manual Beta
- 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
### Tier B: Web Dashboard - **Goal**: Stabilize current alert quality and build core user group.
- Price: $5 / month - **Actions**:
- Value proposition: - Manual subscription activation via Telegram DM.
- Full city dashboard - Small, focused paid Telegram channel for signal tests.
- Trend and nearby-station visualization - Invitation-only Web Access (Vercel).
- Multi-model comparison
- Historical view
- Suggested restrictions:
- View-only unless future premium tools are added
### Bundle Option ### 🛠️ Phase 2: Automation (USDC)
- Optional future bundle: Web + Group
- Use only if conversion data shows users want both together
## 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 ### 🌐 Phase 3: Scaling & Analytics
- User pays manually
- Operator manually activates web access / Telegram access
- Lowest engineering cost, fastest launch
### Phase 2: Polygon / USDC Automation - **Goal**: Retention and expansion.
- Generate unique deposit address or payment intent - **Actions**:
- Confirm on-chain payment - **Accuracy Leaderboard**: Monthly reports of DEB vs Market outcomes.
- Activate subscription automatically - **Self-Serve Portal**: User dashboard for billing and alert settings.
- Telegram bot issues one-time group invite link
### 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 - **Weather-First**: We focus on the **physical variable changes** rather than exchange-side order book execution.
- Finish cleaning docs and deployment flow - **Quality > Quantity**: Alert fatigue will churn subscribers. We enforce a "True Probability Shift" rule for notifications.
- Keep Vercel as the only web entry point - **Local Niche**: Ankara is our flagship differentiator.
- Keep backend API-only
- Tune Telegram cooldown and trigger quality
### 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 **📅 Last Updated**: 2026-03-06
- 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
docs/TECH_DEBT.md
+44 -94
View File
@@ -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: ```mermaid
- Multi-source weather collection pie title System Health & Tech Debt
- DEB forecast blending "Stable Engine" : 75
- Web dashboard on Vercel "Centralized Logic Debt" : 10
- FastAPI API backend "Subscription DB Debt" : 10
- Telegram proactive push loop "Testing/Replay Debt" : 5
- Alert dedupe and cooldown ```
- Late-day peak suppression
Recently removed: The core engine is stable, but several infrastructure "shortcut" decisions remain.
- Old FastAPI static web page
- Polymarket market-price integration
- `/tradealert` preview command
## High-Priority Debt ### Current Stable Modules
### 1. Bot orchestration is still too centralized - [x] Multi-source Weather Aggregation
`bot_listener.py` is operational, but too much runtime behavior is still coordinated from a single entrypoint. - [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: ## 🔴 High Priority: Immediate Focus
- Keep moving push and analysis concerns into `src/utils` and `src/analysis`
### 2. Alert transparency needs better operator visibility | Debt Item | Impact | Suggested Fix |
The system now pushes the correct trigger types more conservatively, but group operators still need better evidence lines. | :--------------------- | :-------------------------------------------------- | :--------------------------------------------------------------- |
| **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: ## 🟡 Medium Priority: Quality of Life
- Add a compact `依据 / Evidence` line to alert messages
- Expose raw trigger metrics in a debug API or operator log
### 3. No persistent application store for subscriptions | Debt Item | Impact | Suggested Fix |
Current architecture is ready for commercialization planning, but there is no real subscription state model yet. | :------------------------ | :-------------------------------------------------- | :--------------------------------------------------------------------------- |
| **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: ## 🟢 Low Priority: Optimization
- Add a database-backed subscription table before automating billing
## 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: ## 🗓️ Next Milestones
- Rule changes are hard to evaluate objectively
- Alert tuning is still partly manual
Suggested direction: 1. **DB Integration**: Connect Supabase to `src/database/db_manager.py`.
- Build a replay harness from stored observations and forecasts 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: **📅 Last Updated**: 2026-03-06
- 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
src/utils/telegram_push.py
+6 -9
View File
@@ -256,14 +256,14 @@ def start_trade_alert_push_loop(bot: Any, config: Dict[str, Any]) -> Optional[th
def _runner() -> None: def _runner() -> None:
logger.info( logger.info(
f"telegram alert push loop started cities={len(cities)} interval={interval_sec}s " 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: while True:
cycle_started = time.time() cycle_started = time.time()
state = _load_state(state_path) state = _load_state(state_path)
_cleanup_state(state, int(cycle_started)) _cleanup_state(state, int(cycle_started))
changed = False
for city in cities: for city in cities:
try: try:
alert_payload = build_trade_alert_for_city(city, config) 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_severity=min_severity,
min_trigger_count=min_trigger_count, 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: except Exception:
logger.exception(f"telegram alert push loop failed for city={city}") logger.exception(f"telegram alert push loop failed for city={city}")
time.sleep(1) 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 elapsed = time.time() - cycle_started
sleep_sec = max(5, interval_sec - int(elapsed)) sleep_sec = max(5, interval_sec - int(elapsed))
time.sleep(sleep_sec) time.sleep(sleep_sec)