From 44af26da703d28e3b8a3ac085518748f362226b8 Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Wed, 11 Mar 2026 11:18:48 +0800 Subject: [PATCH] docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README. --- README.md | 250 ++++++++++++-------------- README_ZH.md | 249 +++++++++++--------------- docs/API_ZH.md | 359 +++++++++++++++++++------------------- docs/COMMERCIALIZATION.md | 144 ++++++++------- docs/TECH_DEBT.md | 95 +++++----- docs/TECH_DEBT_ZH.md | 95 +++++----- 6 files changed, 573 insertions(+), 619 deletions(-) diff --git a/README.md b/README.md index 3fd3a244..55aa799a 100644 --- a/README.md +++ b/README.md @@ -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 - -

- PolyWeather Demo - Ankara Live Analysis -
- 📊 Deep Query View: DEB blended forecast + settlement probability + AI analysis context -

- -

- PolyWeather Web Map -
- 🗺️ Omni-Dashboard: global station markers + nearby station context + right-side city intelligence panel -

- ---- - -## 🚀 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 ` | City real-time analysis | +| `/deb ` | 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) diff --git a/README_ZH.md b/README_ZH.md index af71374d..3cc8c271 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -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/) - ---- - -## 🖼️ 预览与交互 - -

- PolyWeather 效果展示 - 安卡拉实时分析 -
- 📊 深度查询效果：DEB 融合预测 + 结算概率 + AI 分析上下文 -

- -

- PolyWeather Web Map -
- 🗺️ 全景仪表盘：全球站点标记 + 周边站点联动 + 右侧城市详情卡片 -

- ---- - -## 🚀 核心功能 - -- **📡 多源全量采集** - - **主流模型**：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 ` | 城市实时分析 | +| `/deb ` | 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 + 市场只读层） diff --git a/docs/API_ZH.md b/docs/API_ZH.md index 444f49a5..5c668b75 100644 --- a/docs/API_ZH.md +++ b/docs/API_ZH.md @@ -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://:8000` 或绑定后的 HTTPS API 域名 -- **响应格式**: JSON -- **缓存策略**: - - 后端 `web/app.py` 内部分析缓存：默认 5 分钟（Ankara 为 60 秒） - - 前端城市详情缓存：5 分钟 TTL + revision 校验 - - 前端手动刷新：强制 `force_refresh=true` 跳过缓存 +- 本地地址：`http://127.0.0.1:8000` +- 生产地址：`http://: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=`（调试/定向市场匹配） + +关键结构： + +- `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 精确定位市场，跳过自动发现） +### 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` diff --git a/docs/COMMERCIALIZATION.md b/docs/COMMERCIALIZATION.md index 768a4e7f..0e133ac2 100644 --- a/docs/COMMERCIALIZATION.md +++ b/docs/COMMERCIALIZATION.md @@ -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` diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md index 8286681e..1c5fac00 100644 --- a/docs/TECH_DEBT.md +++ b/docs/TECH_DEBT.md @@ -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` diff --git a/docs/TECH_DEBT_ZH.md b/docs/TECH_DEBT_ZH.md index d3d43e15..30b3cf2c 100644 --- a/docs/TECH_DEBT_ZH.md +++ b/docs/TECH_DEBT_ZH.md @@ -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`