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

docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.

Browse Source
This commit is contained in:
2569718930@qq.com
2026-03-11 11:18:48 +08:00
parent 3cbef28b13
commit 44af26da70
6 changed files with 573 additions and 619 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+107 -143
View File
@@ -1,172 +1,136 @@
# 🌡️ PolyWeather Pro
# PolyWeather Pro
> **Professional Weather Intelligence System** — Specialized in edge data collection, DEB smart blending, and real-time decision alerts.
Production weather-intelligence stack for temperature settlement markets.
---
Official dashboard: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)
## 💎 Project Vision
## What This Project Does
PolyWeather is a specialized intelligence system built for **Polymarket** high-stakes participants. We aggregate top-tier meteorological sources, apply proprietary **DEB (Dynamic Error Balancing)** logic, and surface **actionable shift signals** at critical decision windows.
- Aggregates weather observations and forecasts for monitored cities.
- Blends multi-model forecasts with DEB (Dynamic Error Balancing).
- Computes settlement-oriented probability buckets (mu-centered distribution).
- Maps model view to Polymarket read-only market data for mispricing/risk scan.
- Delivers the same core logic to web dashboard and Telegram bot.
---
## Mindmap
## 🏗️ Production Architecture
```mermaid
mindmap
root((PolyWeather Pro))
Data Layer
METAR(Aviation Weather / METAR)
MGM(Turkey MGM)
Station 17130(Ankara Center 17130)
Open-Meteo
weather.gov(US cities)
Polymarket(P0 Read-only)
Analysis Layer
DEB(Dynamic Error Balancing)
Probability Engine(mu + buckets)
Trend Engine
Risk Profiles
Mispricing Radar
Delivery Layer
FastAPI
Next.js Dashboard
Telegram Bot
Alert Push
Ops Layer
Docker Compose(VPS backend + bot)
Vercel(frontend)
Cache + force_refresh
Speed Insights
```
This project uses a decoupled production setup for reliability and iteration speed:
- **Frontend**: A **Next.js** dashboard on **Vercel** with React component rendering.
- **Backend API**: A **FastAPI** service on VPS for low-latency weather aggregation and analysis.
- **Bot & Alert Heartbeat**: A **Telegram Bot** on VPS for minute-level scanning and push alerts.
🔗 **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="450">
<br>
<em>📊 <b>Deep Query View</b>: DEB blended forecast + settlement probability + AI analysis context</em>
</p>
<p align="center">
<img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
<br>
<em>🗺️ <b>Omni-Dashboard</b>: global station markers + nearby station context + right-side city intelligence panel</em>
</p>
---
## 🚀 Core Features
- **📡 Full-Spectrum Collection**
- **Major Models**: ECMWF, GFS, ICON, GEM, JMA, Open-Meteo, and city-level daily/hourly guidance.
- **Observed Data**: Aviation Weather / METAR as the primary observation source, plus Turkish MGM coverage for Ankara.
- **City Specialization**: `17130` (`Ankara (Bölge/Center)`) remains the Ankara lead station without replacing LTAC settlement observation.
- **⚖️ DEB Smart Blending**
- Dynamic weighting based on city-level performance and current model spread.
- **📈 Market Data Integration**
- Live Polymarket quotes, probabilities, and dynamic settlement bucket tracking.
- Automatic Market Edge and Spread calculation comparing DEB vs Market.
- **🧩 React Quant Dashboard (v2.0)**
- **Pull-based Dynamic Cache**: Default 5-minute TTL safety lock, with a 1-minute high-frequency bypass exclusively for Ankara (ANKARA).
- **Optimistic UI & Cache Breakthrough**: Manual `force_refresh` trigger maintains legacy observations during load to prevent screen flickering, isolating loading states only to external polymarket edges.
- **Dark Quant Aesthetics**: Upgraded from emojis to native `lucide-react` SVGs. Re-engineered cold/warm structure progress bars, dynamic threshold palettes, and fluid 100% card widths.
- **Bilingual & Seamless**: Built-in comprehensive `i18n.ts` with transparent localization mapping.
- **🔔 Edge Analytics & Alerts**
- **Momentum Spike**: Captures rapid short-window temperature slope changes.
- **Forecast Breakthrough**: Fires when observations break model envelopes plus margin.
- **Advection Monitoring**: Combines lead-station and wind direction to judge cold/warm advections against live temperature drifts.
---
## 🔐 Alert Logic Details
| 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 |
---
## 🧭 Current Data Logic
- **Primary observation source**: Aviation Weather / METAR
- **Ankara enhancement**:
- Settlement observation: `LTAC / Esenboğa`
- Official lead station: `Ankara (Bölge/Center)` / `17130`
- Nearby station layer: Turkish MGM network (Ankara-specific preferred station ordering)
- **Other cities nearby layer**:
- Production currently uses Aviation Weather METAR clusters
- U.S. cities may later receive Mesonet augmentation while METAR stays baseline
- **Frontend request optimization**:
- Initial map temperatures preload via `/api/city/{name}/summary`
- City detail cache TTL = 5 minutes, revision probe avoids unnecessary refetch
- Map movements, panel toggles, and modal open/close do not trigger redundant requests
- Manual refresh always bypasses cache (`force_refresh=true`)
---
## 🏗️ System Architecture
## Architecture
```mermaid
graph TD
subgraph "Client / Terminals"
Web[Next.js React Web App]
TG[Telegram Client]
end
User[Web / Telegram User] --> FE[Next.js Frontend on Vercel]
User --> Bot[Telegram Bot on VPS]
FE --> API[FastAPI Service]
Bot --> API
subgraph "Edge Deployment (Vercel)"
Web --> |BFF Routes| Fast[FastAPI API]
end
API --> WX[Weather Data Collector]
WX --> METAR[METAR / Aviation Weather]
WX --> MGM[MGM API / nearby stations]
WX --> OM[Open-Meteo]
WX --> NWS[weather.gov]
subgraph "Core Hub (VPS)"
Fast --- |Shared Logic| Worker[Alert Engine / Worker]
Bot[Telegram Bot] --- |Shared Logic| Worker
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
API --> DEB[DEB + Trend + Probability Engines]
API --> PM[Polymarket Read-only Layer]
PM --> Gamma[Gamma API]
PM --> CLOB[CLOB / py-clob-client]
```
---
## Current Source Policy
## 🛠️ Deployment
| Domain | Source Policy |
| :-- | :-- |
| Primary observation | Aviation Weather / METAR |
| Ankara enhancement | MGM + nearby stations, lead station fixed to `17130` |
| Forecast baseline | Open-Meteo |
| US official context | weather.gov |
| Market layer | Polymarket P0 read-only discovery + quotes |
| Removed source | Meteoblue (fully removed from code and docs) |
### 1. Backend / Bot (VPS)
## Recent Changes (2026-03-11)
- Removed all Meteoblue API integration and references.
- Fixed market top-bucket rendering path by deduplicating repeated temperature buckets.
- Added frontend fallback guard when market top buckets collapse to low-quality duplicates.
- Fixed detail panel accessibility issue (`aria-hidden` focus conflict) using `inert` + active-element blur.
- Added Vercel Speed Insights integration in `frontend/app/layout.tsx`.
## Repositories and Runtime Paths
- Frontend: `frontend/` (Next.js App Router)
- Backend API: `web/app.py` and `src/`
- Telegram runtime: `bot_listener.py` + `src/analysis/*`
- Docs: `docs/`
## Quick Start
### Backend + Bot (VPS / Docker)
```bash
# Pull source
git pull
# Environment
# Edit .env with TELEGRAM_BOT_TOKEN and other keys
# Launch
docker-compose up -d --build
docker compose up -d --build
```
### 2. Frontend (Vercel)
### Frontend (local)
Set `frontend` as the Vercel root directory for automatic CI/CD.
```bash
cd frontend
npm install
npm run dev
```
---
### Frontend production build check
## 💬 Bot Commands
```bash
cd frontend
npm run build
```
| Command | Description | Example |
| :------ | :------------------------------------ | :------------- |
| `/city` | Query real-time analysis for a city | `/city ankara` |
| `/deb` | View historical accuracy of DEB model | `/deb london` |
| `/top` | View activity leaderboard | `/top` |
| `/help` | Get detailed instructions | `/help` |
## Command Surface (Telegram)
---
| Command | Purpose |
| :-- | :-- |
| `/city <name>` | City real-time analysis |
| `/deb <name>` | DEB historical reconciliation |
| `/top` | User leaderboard |
| `/help` | Help and command usage |
> [!NOTE]
> **Commercialization**: Current plans keep **Web Dashboard ($5/mo)** and **Telegram Signal Channel ($1/mo)** as the core entry offers.
> User entitlement and payment automation are tracked in `docs/COMMERCIALIZATION.md`.
## Documentation Index
> [!NOTE]
> **Frontend Model**: Production rendering is now fully handled by React components under `frontend/components/dashboard` and hooks under `frontend/hooks`.
> Legacy static files are retained for reference, but no longer act as the main runtime path.
- 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`
- Chinese overview: `README_ZH.md`
---
## Status
---
**📅 Last Updated**: 2026-03-10
**🚀 Status**: v1.2 Stable - React Dashboard with i18n & Polymarket Integration in Production
> [!TIP]
> **Production Note**: The UI layout remains consistent while introducing full internationalization, market quote integration, and premium visual feedback (glassmorphism overlays, sonar markers).
- Version: `v1.3`
- Last Updated: `2026-03-11`
- Runtime: Stable (web + bot + market read-only layer in production)
README_ZH.md
+106 -143
View File
@@ -1,172 +1,135 @@
# 🌡️ PolyWeather Pro
# PolyWeather Pro
> **专业级博弈情报系统** —— 专注边缘气象数据采集、DEB 智能融合与实时决策预警。
面向温度结算市场的生产级气象情报系统。
---
官方看板：[polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)
## 💎 项目愿景
## 这个项目在做什么
PolyWeather 是一套专为 **Polymarket** 深度博弈者设计的实时情报系统。我们不只提供天气预报，而是通过聚合全球气象源、应用自研 **DEB (Dynamic Error Balancing)** 算法，并在关键时间节点输出**可执行的异动信号**。
- 聚合监控城市的实测与预报数据。
- 用 DEB（Dynamic Error Balancing）做动态融合预测。
- 计算结算导向的温度概率分布（`μ` + 温度桶）。
- 将模型概率与 Polymarket 只读市场数据对齐，输出错价/风险信号。
- Web 仪表盘与 Telegram 机器人共用同一套核心逻辑。
---
## 思维导图
## 🏗️ 生产架构
```mermaid
mindmap
root((PolyWeather Pro))
数据层
METAR(Aviation Weather / METAR)
MGM(土耳其 MGM)
安卡拉主站(17130 Center)
Open-Meteo
weather.gov(美国城市)
Polymarket(P0 只读)
分析层
DEB(动态误差平衡)
概率引擎(mu + 桶分布)
趋势引擎
城市风险档案
错价雷达
交付层
FastAPI
Next.js 仪表盘
Telegram Bot
预警推送
运维层
Docker Compose(VPS)
Vercel(前端)
缓存 + force_refresh
Speed Insights
```
本项目采用生产级解耦架构，确保高可用与迭代效率：
- **前端**：部署在 **Vercel** 上的 **Next.js + React 组件化仪表盘**。
- **后端 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="450">
<br>
<em>📊 <b>深度查询效果</b>：DEB 融合预测 + 结算概率 + AI 分析上下文</em>
</p>
<p align="center">
<img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
<br>
<em>🗺️ <b>全景仪表盘</b>：全球站点标记 + 周边站点联动 + 右侧城市详情卡片</em>
</p>
---
## 🚀 核心功能
- **📡 多源全量采集**
- **主流模型**：ECMWF、GFS、ICON、GEM、JMA、Open-Meteo 的日/小时指导。
- **实测数据**：Aviation Weather / METAR 为主观测源，安卡拉叠加 Turkish MGM 官方网络。
- **城市特化**：安卡拉保留 `17130`（`Ankara (Bölge/Center)`）领先站逻辑，不替代 LTAC 结算主站。
- **⚖️ DEB 智能融合**
- 基于城市历史表现与当前模型分歧动态调整权重。
- **📈 市场数据深度整合**
- 实时接入 Polymarket 报价、结算概率及动态“最热温度桶”追踪。
- 自动对比 DEB 与市场差值，计算 Edge 与点差。
- **🧩 React 量化仪表盘 (v2.0)**
- **按需动态缓存体系 (Pull-based Cache)**：默认 5 分钟安全锁，安卡拉 (ANKARA) 特权级 1 分钟短平快刷新。
- **乐观 UI (Optimistic UI) & 缓存击穿**：专属“强制刷新”按键，数据加载期间保持旧版实况渲染无黑屏跳动，仅对市场边缘概率面板挂载极客加载遮罩。
- **极致暗黑美学**：使用 `lucide-react` SVG 高清响应图标替代生硬 Emoji，重绘冷暖平流进度（蓝/深/橙阈值指示），卡片 100% 自适应满屏。
- **双语零感切换**：自带完善的中英语言包 `i18n.ts` 以及数据可视化映射机制。
- **🔔 边缘套利与预警**
- **动量突变**：捕捉短窗口温度斜率变化。
- **预测突破**：实测突破模型包络与安全边际时触发。
- **平流监测**：结合前导站和风向智能判断冷暖平流并与温度走势做叉乘对比。
---
## 🔐 预警逻辑深度说明
| 触发器名称 | 核心逻辑 | 博弈价值 |
| :--------------- | :------------------------------------------- | :--------------------------------- |
| **Center Hit** | 仅识别安卡拉总部 `17130` 站点的 DEB 触发信号 | **最高级信号**，定盘星 |
| **Momentum** | 30min 温度斜率超过 | 捕捉突发天气系统（如锋面） |
| **Breakthrough** | 击穿所有预报上限 + 安全边际 | 捕捉市场极少数情况下的暴利点 |
| **Advection** | 前导站温升 + 风向匹配 | 获得 20-40 分钟的提前离场/建仓时间 |
---
## 🧭 当前数据逻辑
- **主观测源**：Aviation Weather / METAR
- **安卡拉增强逻辑**：
- 结算主观测：`LTAC / Esenboğa`
- 官方领先站：`Ankara (Bölge/Center)` / `17130`
- 周边站层：土耳其 MGM 网络（含安卡拉优先站筛选）
- **其他城市周边站层**：
- 当前生产环境使用 Aviation Weather METAR cluster
- 美国城市后续可叠加 Mesonet，但 METAR 仍为基础层
- **前端请求优化口径**：
- 首屏先走 `/api/city/{name}/summary` 预热地图温度
- 城市详情 5 分钟 TTL，revision 不变则跳过重拉
- 地图联动、侧卡开关、modal 开关不会重复请求
- 手动刷新强制绕过缓存（`force_refresh=true`）
---
## 🏗️ 架构解析
## 系统架构
```mermaid
graph TD
subgraph "客户端 / 终端"
Web[Next.js React 网页端]
TG[Telegram 客户端]
end
User[Web / Telegram 用户] --> FE[Vercel Next.js 前端]
User --> Bot[VPS Telegram Bot]
FE --> API[FastAPI 服务]
Bot --> API
subgraph "云端部署 (Vercel)"
Web --> |BFF 路由| Fast[FastAPI API]
end
API --> WX[Weather Collector]
WX --> METAR[METAR / Aviation Weather]
WX --> MGM[MGM API / 周边站]
WX --> OM[Open-Meteo]
WX --> NWS[weather.gov]
subgraph "核心引擎 (VPS)"
Fast --- |Shared Logic| Worker[Alert Engine / Worker]
Bot[Telegram Bot] --- |Shared Logic| Worker
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
API --> DEB[DEB + 趋势 + 概率引擎]
API --> PM[Polymarket 只读层]
PM --> Gamma[Gamma API]
PM --> CLOB[CLOB / py-clob-client]
```
---
## 当前数据源口径
## 🛠️ 部署指南
| 领域 | 当前口径 |
| :-- | :-- |
| 主观测源 | Aviation Weather / METAR |
| Ankara 增强 | MGM + 周边站，领先站固定 `17130` |
| 预报基线 | Open-Meteo |
| 美国官方语义层 | weather.gov |
| 市场层 | Polymarket P0 只读发现 + 报价 |
| 已移除 | Meteoblue（代码与文档已全部移除） |
### 1. 后端 / 机器人 (VPS)
## 最近更新（2026-03-11）
- 完整移除 Meteoblue API 及全部引用。
- 修复市场“最热温度桶”重复温度刷屏问题（后端按温度去重 + 前端兜底去重）。
- 修复详情面板可访问性告警（`aria-hidden` 焦点冲突），改为 `inert + blur`。
- 集成 Vercel Speed Insights（`frontend/app/layout.tsx`）。
## 目录说明
- 前端：`frontend/`（Next.js App Router）
- 后端：`web/app.py` 与 `src/`
- 机器人：`bot_listener.py` + `src/analysis/*`
- 文档：`docs/`
## 快速启动
### 后端 + 机器人（VPS / Docker）
```bash
# 获取源码
git pull
# 环境配置
# 编辑 .env 文件，填入 TELEGRAM_BOT_TOKEN 等关键参数
# 一键启动
docker-compose up -d --build
docker compose up -d --build
```
### 2. 前端 (Vercel)
### 前端本地运行
关联本项目 `frontend` 目录作为根目录，启用自动 CI/CD。
```bash
cd frontend
npm install
npm run dev
```
---
### 前端构建校验
## 💬 机器人指令
```bash
cd frontend
npm run build
```
| 命令 | 说明 | 示例 |
| :------ | :------------------------ | :------------- |
| `/city` | 查询指定城市实时分析 | `/city ankara` |
| `/deb` | 查看 DEB 模型的历史准确率 | `/deb london` |
| `/top` | 查看活跃积分排行榜 | `/top` |
| `/help` | 获取详细功能说明 | `/help` |
## Telegram 命令
---
| 命令 | 用途 |
| :-- | :-- |
| `/city <name>` | 城市实时分析 |
| `/deb <name>` | DEB 历史对账 |
| `/top` | 用户排行榜 |
| `/help` | 帮助说明 |
> [!NOTE]
> **商业化提示**：当前仍以 **Web 仪表盘 ($5/月)** 与 **Telegram 信号频道 ($1/月)** 为核心入口套餐。
> 自动化支付与订阅鉴权规划见 `docs/COMMERCIALIZATION.md`。
## 文档索引
> [!NOTE]
> **前端现状**：生产环境页面已由 `frontend/components/dashboard` 与 `frontend/hooks` 完整接管渲染。
> legacy 静态文件仅保留为历史参考，不再作为主运行入口。
- API 文档（中文）：`docs/API_ZH.md`
- 商业化路线：`docs/COMMERCIALIZATION.md`
- 技术债（英文）：`docs/TECH_DEBT.md`
- 技术债（中文）：`docs/TECH_DEBT_ZH.md`
- 英文总览：`README.md`
---
## 当前状态
---
**📅 最后更新**：2026-03-10
**🚀 状态**：v1.2 稳定版 - 国际化及 Polymarket 市场层融合已上线
> [!TIP]
> **生产提示**：在不改变既有 UI 布局的前提下，前端已全面引入国际化、市场报价集成及进阶视觉效果（如动态雷达标记、高级加载与毛玻璃控件）。
- 版本：`v1.3`
- 最后更新：`2026-03-11`
- 状态：稳定运行（Web + Bot + 市场只读层）
docs/API_ZH.md
+178 -181
View File
@@ -1,30 +1,64 @@
# PolyWeather API 接口文档 (v1.2)
# PolyWeather API 文档（v1.3）
本文档说明当前 PolyWeather 后端实际提供的 HTTP API。后端由 `web/app.py` 提供，前端通过 Next.js BFF 路由代理访问这些接口。
本文档描述当前后端真实可用接口（`web/app.py`）。
前端一般通过 Next.js BFF 路由代理访问这些接口。
---
## 1. 基础信息
- **本地 Base URL**: `http://127.0.0.1:8000`
- **生产 Base URL**: `http://<your-vps-ip>:8000` 或绑定后的 HTTPS API 域名
- **响应格式**: JSON
- **缓存策略**:
- 后端 `web/app.py` 内部分析缓存：默认 5 分钟（Ankara 为 60 秒）
- 前端城市详情缓存：5 分钟 TTL + revision 校验
- 前端手动刷新：强制 `force_refresh=true` 跳过缓存
- 本地地址：`http://127.0.0.1:8000`
- 生产地址：`http://<vps-ip>:8000` 或你绑定的 HTTPS 域名
- 返回格式：`application/json`
- 缓存策略：
- 后端分析缓存：默认 5 分钟（Ankara 特殊口径 60 秒）
- 前端详情缓存：5 分钟 + revision 检查
- 手动刷新：`force_refresh=true` 强制绕过缓存
---
## 2. 接口列表
## 2. API 思维导图
### 2.1 获取监控城市列表
```mermaid
mindmap
root((PolyWeather API))
城市列表
GET /api/cities
城市主数据
GET /api/city/{name}
GET /api/city/{name}/summary
GET /api/city/{name}/detail
历史数据
GET /api/history/{name}
关键对象
current
forecast
probabilities(mu + distribution)
multi_model / multi_model_daily
market_scan(P0 只读)
```
- **URL**: `/api/cities`
- **Method**: `GET`
- **用途**: 返回首页左侧监控城市与地图 marker 的基础元数据。
---
**响应示例**
## 3. 接口总览
| 接口 | 方法 | 用途 |
| :-- | :-- | :-- |
| `/api/cities` | GET | 城市清单与地图基础信息 |
| `/api/city/{name}` | GET | 城市主分析数据（侧栏/今日分析主来源） |
| `/api/city/{name}/summary` | GET | 轻量摘要（首屏预热/低开销更新） |
| `/api/city/{name}/detail` | GET | 聚合详情 + Polymarket P0 只读市场层 |
| `/api/history/{name}` | GET | 历史对账数据 |
---
## 4. 关键接口详解
### 4.1 `GET /api/cities`
返回监控城市列表（地图 Marker 与侧边栏基础数据）。
示例：
```json
{
@@ -32,8 +66,8 @@
{
"name": "ankara",
"display_name": "Ankara",
"lat": 40.1281,
"lon": 32.9951,
"lat": 39.9334,
"lon": 32.8597,
"risk_level": "medium",
"risk_emoji": "🟠",
"airport": "Esenboğa",
@@ -45,54 +79,91 @@
}
```
### 2.2 获取城市实时分析
### 4.2 `GET /api/city/{name}`
- **URL**: `/api/city/{name}`
- **Method**: `GET`
- **参数**:
- `name`: 城市名或别名，如 `ankara`、`new-york`
- `force_refresh` (可选): `true` 时跳过缓存
- **用途**: 右侧详情卡片、今日分析 modal、图表和周边站点的主数据接口。
主数据接口，前端详情面板和今日分析最常用。
**当前核心字段**
可选参数：
- `display_name`
- `local_time`
- `local_date`
- `temp_symbol`
- `force_refresh=true|false`
核心字段：
- `name`, `display_name`, `local_date`, `local_time`, `temp_symbol`
- `risk`
- `current`
- `mgm`
- `mgm_nearby`
- `forecast`
- `multi_model`
- `mgm`, `mgm_nearby`
- `multi_model`, `multi_model_daily`
- `deb`
- `ensemble`
- `probabilities`
- `trend`
- `metar_today_obs`
- `metar_recent_obs`
- `hourly`
- `hourly_next_48h`
- `source_forecasts`
- `multi_model_daily`
- `probabilities`（`mu` + `distribution`）
- `trend`, `peak`
- `hourly`, `hourly_next_48h`
- `source_forecasts`（当前只保留 `weather_gov`）
- `market_scan`
- `updated_at`
**说明**
说明：
- `current.raw_metar` 为 Aviation Weather 返回的原始报文字段。
- `mgm` 仅在具备官方 MGM 覆盖的城市（如 Ankara）有效。
- `mgm_nearby` 为统一周边站点字段：
- Ankara：MGM 官方周边站
- 其他多数城市：METAR cluster
- `current.raw_metar` 是原始 METAR 报文。
- Ankara 专项增强使用 MGM 站网，领先站固定 `17130`。
- Meteoblue 已彻底移除，不再出现在接口字段中。
### 2.3 获取历史对账数据
### 4.3 `GET /api/city/{name}/summary`
- **URL**: `/api/history/{name}`
- **Method**: `GET`
- **用途**: 历史对账弹窗与 `/deb` 指令的历史样本来源。
轻量温度摘要，用于地图首屏预热和低成本刷新。
**响应示例**
典型字段：
- `name`, `display_name`, `icao`
- `local_time`, `temp_symbol`
- `current.temp`, `current.obs_time`
- `deb.prediction`
- `risk.level`, `risk.warning`
- `updated_at`
### 4.4 `GET /api/city/{name}/detail`
聚合视图接口，包含天气分析和市场只读层。
可选参数：
- `force_refresh=true|false`
- `market_slug=<slug>`（调试/定向市场匹配）
关键结构：
- `overview`
- `official`
- `timeseries`
- `models`
- `probabilities`
- `market_scan`
- `risk`
- `ai_analysis`
`market_scan`（P0 只读）重点字段：
- `primary_market`, `selected_condition_id`, `selected_slug`
- `yes_token`, `no_token`
- `yes_buy`, `yes_sell`, `no_buy`, `no_sell`
- `market_price`, `model_probability`, `edge_percent`
- `temperature_bucket`
- `top_buckets`（前端展示前会再去重）
- `signal_label`（`BUY YES` / `BUY NO` / `MONITOR`）
- `websocket.asset_ids`, `websocket.condition_ids`（订阅标识，不涉及下单）
注意：
- 后端已做温度桶去重与方向优先（优先与主市场同方向的 `or higher`/`or lower` 桶）。
- 前端还有二次去重兜底，避免重复温度桶刷屏。
### 4.5 `GET /api/history/{name}`
历史对账数据来源。
示例：
```json
{
@@ -108,145 +179,71 @@
}
```
**说明**
---
- 网页端历史图默认展示近期样本，但统计口径只使用已结算日期。
- 当天未结算样本可用于可视化趋势，不计入胜率与 MAE。
## 5. 请求链路（以 `/api/city/{name}` 为例）
### 2.4 获取城市摘要
```mermaid
sequenceDiagram
participant FE as Frontend
participant API as FastAPI
participant WX as Weather Collector
participant PM as Polymarket RO Layer
- **URL**: `/api/city/{name}/summary`
- **Method**: `GET`
- **用途**: 轻量级温度摘要接口，用于首屏地图温度预热与低开销列表更新。
FE->>API: GET /api/city/{name}?force_refresh=...
API->>WX: fetch_all_sources(city)
WX-->>API: METAR / MGM / Open-Meteo / weather.gov / Multi-model
API->>API: DEB + trend + probability
API->>PM: build_market_scan(...)
PM-->>API: market_scan (read-only)
API-->>FE: merged city payload
```
**字段**
---
## 6. 数据口径
### 6.1 主观测
- Aviation Weather / METAR 是全局主观测源。
- Ankara：结算主站仍是 `LTAC`，领先信号强化使用 MGM（`17130`）。
### 6.2 预测源
- Open-Meteo
- weather.gov（美国城市）
- 多模型：ECMWF / GFS / ICON / GEM / JMA
### 6.3 概率口径
- `mu`：动态分布中心，不是固定结算值。
- `distribution`：按温度桶输出概率分布，面向结算决策而非通用天气展示。
---
## 7. 常见问题
### 7.1 接口 500
- 先检查容器是否启动：`docker compose ps`
- 查看日志：`docker compose logs -f polyweather_web`
### 7.2 METAR 看起来“延迟”
优先核对：
- `name`
- `display_name`
- `icao`
- `local_time`
- `temp_symbol`
- `current.temp`
- `current.obs_time`
- `deb.prediction`
- `risk.level`
- `risk.warning`
- `updated_at`
- `current.report_time`
- `current.receipt_time`
### 2.5 获取城市聚合详情
通常是上游发布节奏，不一定是本地轮询问题。
- **URL**: `/api/city/{name}/detail`
- **Method**: `GET`
- **用途**: 商业化聚合视图单请求接口（已接入 P0 只读价格层）。
- **可选参数**:
- `force_refresh=true|false`
- `market_slug=<slug>`（调试优先直查；传入后优先按 slug 精确定位市场，跳过自动发现）
### 7.3 前端仍显示旧内容
**当前结构**
- `overview`
- `official`
- `timeseries`
- `models`
- `probabilities`
- `market_scan`
- `risk`
- `ai_analysis`
**说明**
- 当前生产前端主链路仍以 `/api/city/{name}` + `/api/history/{name}` 为主。
- `/api/city/{name}/detail` 当前已包含 Polymarket P0 只读字段：
- `primary_market`
- `selected_condition_id`
- `yes_token` / `no_token`
- `yes_buy` / `yes_sell` / `no_buy` / `no_sell` / `model_probability`
- `market_price`（优先 midpoint）
- `edge_percent`（`(model_probability - market_price) * 100`）
- `temperature_bucket` / `top_buckets` （结算温度桶及市场概率）
- `signal_label`（`BUY YES` / `BUY NO` / `MONITOR`）
- `websocket.asset_ids` / `websocket.condition_ids`（仅用于订阅标识，P0 不下单）
- 确认 Vercel 已部署最新构建
- 浏览器强刷（`Ctrl+F5`）
- 检查是否命中前端 5 分钟 TTL
---
## 3. 核心对象定义
### 3.1 风险等级
- `low`: 低风险，模型与实测整体较一致
- `medium`: 中风险，存在一定分歧或站点偏置
- `high`: 高风险，模型冲突较大或盘面波动价值高
### 3.2 DEB
`DEB` 是 PolyWeather 的动态融合预测层，不是简单平均值。它会综合：
- 多模型预测值
- 近期表现
- 城市级偏差特征
- 实况修正上下文
### 3.3 μ
`μ` 表示当前结算概率分布中心（动态期望值），会随模型分歧与实况变化而更新。
它不应直接按固定 forecast 口径做静态历史对账。
---
## 4. 数据源与第三方 API
### 4.1 主观测源
- **Aviation Weather / METAR**
- 全球机场主观测源
- 同时提供结构化字段与原始 METAR 报文
### 4.2 Ankara 专属源
- **Turkish MGM**
- Ankara 官方增强层
- 含 `Ankara (Bölge/Center)` 与周边站点
### 4.3 预测源
- **Open-Meteo**
- **weather.gov**（美国城市）
- **多模型集成**: ECMWF / GFS / ICON / GEM / JMA
---
## 5. 当前口径说明
- 地图 marker 显示当前温度（首屏通过 `summary` 预热）。
- 点击城市后打开右侧详情卡片，保持当前布局与样式不变。
- “今日日内分析”在 modal 中展示：
- 今日温度走势（含 METAR 实测点）
- 结算概率分布
- 多模型预报
- 今日日内结构信号（规则引擎）
- AI 深度分析 + 0-2 小时临近判断
- modal 打开时地图停止动画；点击空白地图仅关闭右侧卡片，不重置视角。
---
## 6. 常见问题
- **接口 500**
- 先检查 `polyweather_web` 是否启动成功
- 再看 `docker-compose logs -f polyweather_web`
- **METAR 看起来慢几分钟**
- 常见原因是上游发布延迟，不一定是本地轮询问题
- 建议同时查看：
- `current.obs_time`
- `current.report_time`
- `current.receipt_time`
- **网页显示旧内容**
- 先确认 Vercel 已部署最新版本
- 再强刷浏览器缓存
- 如为详情数据，确认是否命中前端 5 分钟 TTL
---
**最后更新**: 2026-03-10
最后更新：`2026-03-11`
docs/COMMERCIALIZATION.md
+78 -66
View File
@@ -1,95 +1,107 @@
# 📈 Commercialization Roadmap
# Commercialization Roadmap
> **Target**: Transforming PolyWeather for paid weather intelligence delivery.
Target: make PolyWeather a sustainable paid weather-intelligence product.
---
## 🎯 Product Focus
## 1. Product Positioning
PolyWeather is positioned as a **premium intelligence service** for weather-driven prediction markets (**Polymarket**). The core differentiators remain **Ankara specialization**, **advection-aware signal logic**, and **DEB-weighted consensus**.
PolyWeather is not a generic weather app.
It is a decision-support layer for temperature-settlement markets:
- observation-first (METAR/MGM),
- settlement-aware probability modeling (DEB + mu/buckets),
- market mapping (Polymarket read-only) for actionable edge detection.
---
## 💰 Pricing & Monetization
## 2. Business Mindmap
| Tier | Price | Primary Value Proposition |
| :------------------- | :------------ | :------------------------------------------------------ |
| **Telegram Channel** | **$1 / mo** | High-fidelity proactive alerts, low noise. |
| **Web Dashboard** | **$5 / mo** | Full multi-model context + historical DEB benchmarking. |
| **VIP Bundle** | **$5.5 / mo** | Unified access to dashboard + signal stream. |
### 🛠️ Payment Infrastructure
- **Currency**: Polygon / USDC.
- **Method**: Phase-1 manual activation; Phase-2 automatic deposit detection and entitlement sync.
```mermaid
mindmap
root((PolyWeather Monetization))
Product
Telegram Signal Channel
Web Dashboard
VIP Bundle
Pricing
Entry 1 USD
Dashboard 5 USD
Bundle 5.5 USD
Access Control
Manual activation(P1)
Wallet/USDC detection(P2)
Entitlement middleware
Growth
Accuracy reports
Retention analytics
User preference center
```
---
## 🗺️ Execution Roadmap
## 3. Packaging and Pricing
| Tier | Price | Value |
| :-- | :-- | :-- |
| Telegram Channel | $1 / month | Low-noise proactive signal feed |
| Web Dashboard | $5 / month | Full multi-model context + reconciliation |
| VIP Bundle | $5.5 / month | Dashboard + signal stream |
Payment direction:
- Currency: Polygon USDC
- Phasing: manual activation first, then automated entitlement sync
---
## 4. Execution Phases
```mermaid
graph LR
P1[Phase 1: Manual Beta] --> P2[Phase 2: USDC Automation]
P2 --> P3[Phase 3: Scaling & Analytics]
subgraph P1_Detail [Manual Operations]
P1 -->|DM Bot| Pay[Manual Payment]
Pay -->|Invite| Link[One-time Link]
end
subgraph P2_Detail [Smart Automation]
P2 -->|Monitor| Chain[Polygon/USDC]
Chain -->|Auto| Access[JWT/Sub Activation]
end
P1[Phase 1 Manual Beta] --> P2[Phase 2 Payment Automation]
P2 --> P3[Phase 3 Growth and B2B]
```
### 📦 Phase 1: Manual Beta
### Phase 1: Manual Beta
- **Goal**: Stabilize signal quality and convert initial paid users.
- **Actions**:
- Manual subscription activation via Telegram DM.
- Small paid Telegram channel for low-noise signal validation.
- Invite-based Web access while entitlement layer is being finalized.
- Keep Ankara as flagship strategy city for product credibility.
- Keep paid channel small, optimize signal quality first.
- Manual payment confirmation + manual entitlement grant.
- Invite-gated dashboard while access control hardens.
### 🛠️ Phase 2: Automation (USDC)
### Phase 2: Payment Automation
- **Goal**: Reduce operational friction and improve payment reliability.
- **Actions**:
- **On-chain monitoring**: Detect USDC deposits to dedicated addresses.
- **One-time Links**: Bot-generated invite links with strict member limits.
- **JWT Auth**: Subscriber-only access control for the Next.js frontend.
- Detect wallet payment events (USDC).
- Auto-issue/refresh entitlement.
- Enforce route-level and API-level access guards.
### 🌐 Phase 3: Scaling & Analytics
### Phase 3: Growth and Expansion
- **Goal**: Improve retention and expand B2C/B2B utility.
- **Actions**:
- **Accuracy Leaderboard**: Monthly DEB vs settled-actual reports.
- **Self-Serve Portal**: Billing, subscription status, and alert preferences.
- **Usage Telemetry**: Feature-level analytics for conversion optimization.
### 📡 API Expansion Priority
- **P0-1 Market Layer**
- Polymarket Gamma discovery + `py-clob-client` pricing / order book
- **P0-2 Official Observation Layer**
- Aviation Weather / METAR
- weather.gov official forecast / observation / alert context
- **P1 Lead Layer**
- Ankara keeps Turkish MGM nearby network
- U.S. cities may later receive Mesonet enhancement without replacing METAR
- **P2 Product Layer**
- Stripe / Polygon-USDC automation
- Realtime entitlement sync and subscriber state management
- Self-serve billing and subscription panel.
- Operator analytics and feature usage telemetry.
- Optional B2B API package for quant teams.
---
## 🚧 Critical Constraints
## 5. Technical Dependencies for Revenue
- **Weather-First**: The product is built around physical weather shifts, not exchange-side execution tooling.
- **Quality > Quantity**: Alert fatigue directly harms retention; thresholds must favor actionable rarity.
- **UI Stability**: Commercial rollout assumes layout consistency; visual contract stays fixed while internals evolve.
| Dependency | Why it matters |
| :-- | :-- |
| Entitlement guard | Prevents unpaid dashboard/API access |
| Subscriber store | Persistent paid user state |
| Audit trail | Explains why each alert fired |
| Observability | Detects degradation before churn |
| Frontend performance | Impacts conversion and retention (Speed Insights now integrated) |
---
**📅 Last Updated**: 2026-03-10
## 6. Immediate Commercial Priorities
1. Finish robust entitlement middleware in frontend and backend.
2. Persist subscriber/payment state in managed DB.
3. Publish transparent monthly accuracy and signal-quality reports.
4. Add support playbooks for false-alert and stale-data incidents.
---
Last Updated: `2026-03-11`
docs/TECH_DEBT.md
+52 -43
View File
@@ -1,70 +1,79 @@
# 🛠️ Technical Debt & Engineering Backlog
# Technical Debt Backlog
> **Vision**: Moving from a research script to a production SaaS.
Purpose: keep engineering debt explicit while shipping production features.
---
## 🏛️ System Health: 82%
## 1. Debt Landscape
```mermaid
pie title System Health & Tech Debt
"Stable Engine" : 82
"Entitlement/Payments Debt" : 8
"Test/Replay Debt" : 6
"Observability Debt" : 4
mindmap
root((Tech Debt))
Architecture
Monolithic bot entry
Shared runtime coupling
Product Infra
Entitlement hardening
Subscription persistence
Quality
Replay harness
Broader regression tests
Observability
Alert evidence trace
SLO dashboards
```
The core weather engine and React dashboard runtime are now stable, but product-layer infrastructure debt is still material.
### Current Stable Modules
- [x] Multi-source Weather Aggregation
- [x] DEB Blending Algorithm
- [x] Proactive Telegram Alert Engine
- [x] Vercel Dashboard Infrastructure
- [x] React component-driven dashboard runtime
- [x] Internationalization (i18n) & Polymarket P0 Data Merge
Current system health estimate: **84% stable / 16% debt**.
---
## 🔴 High Priority: Immediate Focus
## 2. Recently Closed (2026-03-11)
| 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. |
| **Entitlement Guard** | Dashboard routes are public by default. | Add JWT/session gating in Next.js middleware + backend checks. |
- Meteoblue API path fully removed from backend, frontend, config and docs.
- Market top-bucket duplicate temperature issue fixed (backend dedupe + frontend guard).
- Detail panel a11y conflict fixed (`aria-hidden` focus conflict resolved with `inert` + blur).
- Vercel Speed Insights integrated for frontend performance telemetry.
---
## 🟡 Medium Priority: Quality of Life
## 3. High Priority Debt
| 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. |
| **Chart Regression Tests** | UI relies on custom Chart.js lifecycles. | Add snapshot + interaction tests for chart datasets and legends. |
| Item | Impact | Suggested Work |
| :-- | :-- | :-- |
| Monolithic bot entry (`bot_listener.py`) | Hard to test and safely refactor | Split orchestration, IO and analysis modules |
| Entitlement enforcement consistency | Revenue leakage risk | Align frontend middleware and backend enforcement |
| Subscriber persistence model | Manual operations do not scale | Move to managed PostgreSQL/Supabase state |
| Alert explainability | Operator trust and debugging cost | Standardize evidence payload per alert |
---
## 🟢 Low Priority: Optimization
## 4. 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). |
| Item | Impact | Suggested Work |
| :-- | :-- | :-- |
| Replay simulation harness | Hard to reproduce edge cases | Build deterministic replay over stored records |
| Chart/UI regression coverage | Visual regressions can slip | Add snapshot + interaction test coverage |
| Config centralization | Threshold changes are error-prone | Consolidate runtime knobs into structured config |
| Naming cleanup | Legacy terms reduce clarity | Refactor naming in market/weather boundary layer |
---
## 🗓️ Next Milestones
## 5. Low Priority Debt
1. **DB Integration**: Connect Supabase to `src/database/db_manager.py`.
2. **Entitlement Layer**: Enforce paid-access middleware on dashboard and API proxy routes.
3. **Alert Transparency**: Append logic metrics (slope, lead delta, advection factors) to push payloads.
4. **Replay & QA**: Add deterministic replay tests for map/panel/modal interaction regressions.
| Item | Impact | Suggested Work |
| :-- | :-- | :-- |
| Cold-start behavior | First request latency variance | Add warming strategy for top city routes |
| Storage abstraction | Local file assumptions remain | Continue moving state to remote services |
---
**📅 Last Updated**: 2026-03-10
## 6. Next Milestones
1. Entitlement parity: one policy across frontend and backend.
2. Subscriber DB integration and migration scripts.
3. Alert evidence schema + tooling for quick operator audit.
4. Replay runner for weather/market mixed regression scenarios.
---
Last Updated: `2026-03-11`
docs/TECH_DEBT_ZH.md
+52 -43
View File
@@ -1,70 +1,79 @@
# 🛠️ 技术债与工程待办
# 技术债与工程待办
> **愿景**：从研究脚本演进为可持续的生产级 SaaS。
目标：在持续交付的同时，把关键技术债显式化、可追踪化。
---
## 🏛️ 系统健康度：82%
## 1. 技术债全景
```mermaid
pie title 系统健康度与技术债
"稳定引擎" : 82
"权限与支付债务" : 8
"测试/回放债务" : 6
"可观测性债务" : 4
mindmap
root((技术债))
架构层
机器人入口过于集中
共享运行时耦合
产品基础设施
订阅权限一致性
付费用户持久化
质量保障
回放测试能力
UI 回归覆盖不足
可观测性
告警证据链
SLO 看板
```
核心天气引擎与 React 仪表盘运行时已基本稳定，但产品层基础设施债务仍然明显。
### 当前稳定模块
- [x] 多源天气聚合
- [x] DEB 融合算法
- [x] 主动式 Telegram 预警引擎
- [x] Vercel 仪表盘基础设施
- [x] React 组件驱动仪表盘运行时
- [x] 国际化 (i18n) 与前端市场数据集成 (Polymarket)
当前系统健康度估计：**84% 稳定 / 16% 技术债**。
---
## 🔴 高优先级：立即处理
## 2. 最近已关闭项（2026-03-11）
| 债务项 | 影响 | 建议修复 |
| :--------------------- | :----------------------------------------- | :-------------------------------------------------------- |
| **Monolithic Bot** | `bot_listener.py` 可测试性差，演进成本高。 | 将 UI 交互与业务逻辑解耦，沉入 `src/analysis`。 |
| **Subscription Store** | 付费用户缺少持久化记录。 | 从内存校验迁移到 **Supabase/PostgreSQL**。 |
| **Alert Transparency** | 运维侧难以审计“告警为何触发”。 | 为所有内部告警载荷增加 `Evidence` 元数据块。 |
| **Entitlement Guard** | 仪表盘路由默认仍是公开可访问。 | 在 Next.js middleware 与后端校验中加入 JWT/会话权限守卫。 |
- Meteoblue API 全链路移除（后端/前端/配置/文档）。
- 市场温度桶重复刷屏问题修复（后端去重 + 前端兜底）。
- 详情面板可访问性告警修复（`aria-hidden` 焦点冲突改为 `inert + blur`）。
- 前端已接入 Vercel Speed Insights。
---
## 🟡 中优先级：体验与效率
## 3. 高优先级技术债
| 债务项 | 影响 | 建议修复 |
| :------------------------- | :--------------------------------------------- | :--------------------------------------------------- |
| **Hard-coded Thresholds** | 阈值修改需要改代码（如 5s 冷却）。 | 将业务常量统一抽离到结构化 `config.yaml`。 |
| **Simulation Harness** | 无法“回放历史天气日”验证告警逻辑。 | 基于 `data/daily_records.json` 构建 `ReplayEngine`。 |
| **Backend Naming** | 仍有“市场价格时代”的命名残留。 | 系统化重命名，统一为 weather-intelligence 语义。 |
| **Chart Regression Tests** | 图表依赖自定义 Chart.js 生命周期，回归风险高。 | 增加图表数据集与图例的快照测试 + 交互测试。 |
| 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- |
| 机器人入口单体化（`bot_listener.py`） | 测试和重构风险高 | 拆分为编排层、IO 层、分析层 |
| 订阅权限策略不完全统一 | 可能造成付费泄露 | 前后端统一权限校验策略 |
| 付费用户状态持久化不足 | 人工运营不可扩展 | 迁移到托管 DB（PostgreSQL/Supabase） |
| 告警可解释性不足 | 运维排障成本高 | 统一告警证据字段（Evidence Schema） |
---
## 🟢 低优先级：性能优化
## 4. 中优先级技术债
| 债务项 | 影响 | 建议修复 |
| :------------------------- | :----------------------------- | :--------------------------------------- |
| **Serverless Cold Starts** | Vercel 首次 API 调用可能偏慢。 | 为主要城市接口增加边缘缓存或预热任务。 |
| **Local SQLite Files** | 与 Vercel 短暂文件系统不兼容。 | 全面迁移到远程数据库（Supabase/Redis）。 |
| 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- |
| 回放仿真能力不足 | 边缘场景难复现 | 基于历史记录构建可重复 Replay |
| 图表/UI 回归覆盖不足 | 视觉回归风险 | 增加快照与交互自动化测试 |
| 阈值配置分散 | 改动成本高且易错 | 统一收口到结构化配置 |
| 命名历史包袱 | 认知成本高 | 系统化命名治理 |
---
## 🗓️ 下一阶段里程碑
## 5. 低优先级技术债
1. **DB Integration**：将 Supabase 接入 `src/database/db_manager.py`。
2. **Entitlement Layer**：在仪表盘与 API 代理路由上落实付费访问中间件。
3. **Alert Transparency**：在推送载荷中附加逻辑指标（斜率、领先差、平流因子）。
4. **Replay & QA**：为地图/侧卡/modal 联动补齐可复现回放测试。
| 项目 | 影响 | 建议动作 |
| :-- | :-- | :-- |
| 冷启动波动 | 首次请求延迟不稳定 | 热点城市路由预热 |
| 本地文件状态依赖 | 云端弹性场景受限 | 持续迁移到远程存储 |
---
**📅 最后更新**：2026-03-10
## 6. 下阶段里程碑
1. 完成前后端订阅权限一致化。
2. 上线付费用户持久化与迁移脚本。
3. 建立告警证据标准并接入运维排障流。
4. 落地天气+市场混合回放回归测试。
---
最后更新：`2026-03-11`