diff --git a/README.md b/README.md index ded9310e..f70bea59 100644 --- a/README.md +++ b/README.md @@ -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

- PolyWeather Demo - Ankara Live Analysis + PolyWeather Demo - Ankara Live Analysis
- 📊 Live query: DEB Blended Forecast + Settlement Probability + Groq AI Decision + 📊 Deep Query View: DEB Blended Forecast + Settlement Probability + Groq AI Expert Advice

- PolyWeather Web Map + PolyWeather Web Map
- 🗺️ Interactive Web Map: Real-time global monitoring with rich data visualization + 🗺️ Omni-Dashboard: Real-time global heatmaps + array-style data visualization

-## 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 diff --git a/README_ZH.md b/README_ZH.md index 58d0b093..93f31acc 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -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/) + +--- + +## 🖼️ 预览与交互

- PolyWeather 效果展示 - 安卡拉实时分析 + PolyWeather 效果展示 - 安卡拉实时分析
- 📊 实时查询效果：DEB 融合预测 + 结算概率 + Groq AI 决策 + 📊 深度查询效果：DEB 融合预测 + 结算概率 + Groq AI 专家建议

- PolyWeather Web Map + PolyWeather Web Map
- 🗺️ 交互式网页地图：全球城市实时监控与丰富的数据可视化 + 🗺️ 全景仪表盘：全球站点实时热力场 + 阵列式数据展示

-## 当前功能 +--- -- 多源天气采集 - - 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 diff --git a/docs/COMMERCIALIZATION.md b/docs/COMMERCIALIZATION.md index ff509b37..30ced037 100644 --- a/docs/COMMERCIALIZATION.md +++ b/docs/COMMERCIALIZATION.md @@ -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 diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md index 61a1ad63..e9ebd2f1 100644 --- a/docs/TECH_DEBT.md +++ b/docs/TECH_DEBT.md @@ -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 diff --git a/src/utils/telegram_push.py b/src/utils/telegram_push.py index 5b1c2f8d..88205fdd 100644 --- a/src/utils/telegram_push.py +++ b/src/utils/telegram_push.py @@ -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)