2569718930@qq.com
211 lines
6.5 KiB
Markdown
211 lines
6.5 KiB
Markdown
# PolyWeather Pro
|
|
|
|
Production weather-intelligence stack for temperature settlement markets.
|
|
|
|
Official dashboard: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)
|
|
|
|
## Product Screenshots
|
|
|
|
### Global Dashboard
|
|
|
|
|
|
|
|
### City Analysis (Ankara)
|
|
|
|
|
|
|
|
## Core Capabilities
|
|
|
|
- Aggregates real-time observations and forecasts for 20 monitored cities.
|
|
- Uses DEB (Dynamic Error Balancing) to blend multi-model highs.
|
|
- Produces settlement-oriented probability buckets (`mu` + bucket distribution).
|
|
- Maps weather model view to Polymarket read-only quotes for mispricing scan.
|
|
- Serves the same analysis core to web dashboard and Telegram bot.
|
|
|
|
## Architecture (Current)
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
U["Users (Web / Telegram)"] --> FE["Next.js Frontend (Vercel)"]
|
|
U --> BOT["Telegram Bot (VPS)"]
|
|
FE --> API["FastAPI /web/app.py"]
|
|
BOT --> API
|
|
|
|
API --> WX["Weather Collector"]
|
|
WX --> METAR["Aviation Weather (METAR)"]
|
|
WX --> MGM["MGM (Turkey station network)"]
|
|
WX --> OM["Open-Meteo"]
|
|
WX --> NWS["weather.gov (US cities)"]
|
|
|
|
API --> ANALYSIS["DEB + Trend + Probability + Market Scan"]
|
|
ANALYSIS --> PM["Polymarket Read-only Layer"]
|
|
```
|
|
|
|
## Bot Runtime Layout
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
E["bot_listener.py"] --> O["src/bot/orchestrator.py"]
|
|
O --> H["src/bot/handlers/*"]
|
|
O --> S["src/bot/services/*"]
|
|
O --> A["src/bot/analysis/*"]
|
|
O --> G["src/bot/command_guard.py"]
|
|
O --> R["src/bot/runtime_coordinator.py"]
|
|
```
|
|
|
|
## Source Policy
|
|
|
|
| Domain | Current Policy |
|
|
| :-- | :-- |
|
|
| Primary observation | Aviation Weather / METAR |
|
|
| Ankara enhancement | MGM + nearby stations, lead station fixed to `17130` |
|
|
| Forecast baseline | Open-Meteo + multi-model (ECMWF/GFS/ICON/GEM/JMA) |
|
|
| US official context | weather.gov |
|
|
| Market layer | Polymarket P0 read-only discovery + quotes |
|
|
| Removed source | Meteoblue (fully removed from runtime and docs) |
|
|
|
|
## Monitored Cities (20)
|
|
|
|
- Europe / Middle East: Ankara, London, Paris, Munich
|
|
- APAC: Seoul, Hong Kong, Shanghai, Singapore, Tokyo, Wellington
|
|
- Americas: Toronto, New York, Chicago, Dallas, Miami, Atlanta, Seattle, Buenos Aires, Sao Paulo
|
|
- South Asia: Lucknow
|
|
|
|
## Major Updates (2026-03-12)
|
|
|
|
1. Bot architecture refactor completed:
|
|
- `bot_listener.py` is now a thin entrypoint.
|
|
- Core runtime moved to orchestrator + handlers/services/analysis layers.
|
|
- Startup loops managed by `StartupCoordinator`, with `/diag` diagnostics.
|
|
2. Mispricing radar hardened:
|
|
- Anchor changed from single Open-Meteo settlement to multi-model highest-high anchor.
|
|
- Skip non-tradable markets (`closed`, inactive, not accepting orders, or past end time).
|
|
- Future-date scan supported via `target_date` in detail aggregate endpoint.
|
|
3. Wallet activity watcher upgraded:
|
|
- Wallet aliases (`POLYMARKET_WALLET_ACTIVITY_USER_ALIASES`) supported.
|
|
- Telegram link preview toggle (`POLYMARKET_WALLET_ACTIVITY_LINK_PREVIEW`) supported.
|
|
- Debounce + immediate delta push controls reduce noisy spam bursts.
|
|
4. Frontend P0+P1 cache and UX improvements:
|
|
- BFF `ETag + 304` on `/api/cities`, `/api/city/{name}/summary`, `/api/history/{name}`.
|
|
- `force_refresh=true` on summary keeps `Cache-Control: no-store`.
|
|
- `sessionStorage` city-detail cache + background summary revision probe.
|
|
- `localStorage` persistence for selected city and risk-group collapse state.
|
|
- Detail panel accessibility fix (`inert` + active-element blur).
|
|
5. Observability:
|
|
- Vercel Speed Insights integrated.
|
|
- Telegram alert/watcher startup diagnostics exposed through `/diag`.
|
|
6. P1 contract checkout (new):
|
|
- New payment APIs: `/api/payments/config|wallets|intents/*`.
|
|
- MetaMask wallet binding via nonce challenge + `personal_sign`.
|
|
- Supports multi-token checkout on Polygon (USDC.e + Native USDC) via token whitelist config.
|
|
- Frontend receives contract `tx_payload` and calls `eth_sendTransaction`.
|
|
- Backend validates `OrderPaid(orderId,payer,planId,token,amount)` onchain event and auto-grants entitlement.
|
|
- Confirmation writes `payments/subscriptions/entitlement_events` and can notify Telegram.
|
|
- PolygonScan verification guide: `docs/payments/POLYGONSCAN_VERIFY.md`.
|
|
|
|
## Repository Layout
|
|
|
|
- Frontend: `frontend/`
|
|
- Backend API: `web/app.py`, `src/`
|
|
- Telegram bot runtime: `bot_listener.py`, `src/bot/*`
|
|
- Wallet watchers: `src/onchain/*`
|
|
- Ops scripts: `scripts/`
|
|
- Docs: `docs/`
|
|
|
|
## Quick Start
|
|
|
|
### Backend + Bot (Docker)
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
## Runtime Data (Recommended for VPS)
|
|
|
|
To avoid `git pull` conflicts and decouple code from runtime state, store SQLite and caches outside the repo:
|
|
|
|
1. Set in `.env`:
|
|
- `POLYWEATHER_RUNTIME_DATA_DIR=/var/lib/polyweather`
|
|
- `POLYWEATHER_DB_PATH=/var/lib/polyweather/polyweather.db`
|
|
2. Ensure host directory exists and has write permission for container user (`1000:1000`):
|
|
|
|
```bash
|
|
sudo mkdir -p /var/lib/polyweather
|
|
sudo chown -R 1000:1000 /var/lib/polyweather
|
|
sudo chmod 775 /var/lib/polyweather
|
|
```
|
|
|
|
3. Recreate services:
|
|
|
|
```bash
|
|
docker compose down
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### Frontend (local)
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
### Frontend production build
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run build
|
|
```
|
|
|
|
## Ops Verification
|
|
|
|
### Validate frontend cache headers (`ETag` / `304` / `force_refresh=no-store`)
|
|
|
|
```bash
|
|
./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
|
|
```
|
|
|
|
### Watch mispricing radar decisions
|
|
|
|
```bash
|
|
docker compose logs -f polyweather | egrep "market not tradable|trade alert pushed|mispricing cap"
|
|
```
|
|
|
|
### Watch wallet activity watcher startup and pushes
|
|
|
|
```bash
|
|
docker compose logs -f polyweather | egrep "wallet activity watcher started|wallet activity pushed|wallet activity cycle failed"
|
|
```
|
|
|
|
### Check bot startup diagnosis in Telegram
|
|
|
|
```text
|
|
/diag
|
|
```
|
|
|
|
## Telegram Command Surface
|
|
|
|
| Command | Purpose |
|
|
| :-- | :-- |
|
|
| `/city <name>` | City real-time analysis |
|
|
| `/deb <name>` | DEB historical reconciliation |
|
|
| `/top` | User leaderboard |
|
|
| `/id` | Show current chat ID |
|
|
| `/diag` | Bot startup diagnostics and loop status |
|
|
| `/help` | Help and usage |
|
|
|
|
## Documentation Index
|
|
|
|
- Chinese overview: `README_ZH.md`
|
|
- Chinese API guide: `docs/API_ZH.md`
|
|
- Commercial roadmap: `docs/COMMERCIALIZATION.md`
|
|
- Tech debt (EN): `docs/TECH_DEBT.md`
|
|
- Tech debt (ZH): `docs/TECH_DEBT_ZH.md`
|
|
- Frontend delivery report: `FRONTEND_REDESIGN_REPORT.md`
|
|
|
|
## Status
|
|
|
|
- Version: `v1.3`
|
|
- Test status: `31 passed` (`.\\venv\\Scripts\\python.exe -m pytest -q`)
|
|
- Last Updated: `2026-03-12`
|