feat: enhance project documentation with new overview diagrams, commercialization roadmap, and technical debt backlog.

2026-03-11 11:45:57 +08:00
parent 35345a1b04
commit e89fdb7e09
6 changed files with 185 additions and 115 deletions
@@ -12,34 +12,47 @@ Official dashboard: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.
 - 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
+## Overview Diagram

 ```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"
+flowchart TD
+    A["PolyWeather Pro"]
+
+    subgraph DL["Data Layer"]
+        DL1["METAR (Aviation Weather / METAR)"]
+        DL2["MGM (Turkey MGM)"]
+        DL3["Station 17130 (Ankara Center 17130)"]
+        DL4["Open-Meteo"]
+        DL5["weather.gov (US cities)"]
+        DL6["Polymarket (P0 Read-only)"]
+    end
+
+    subgraph AL["Analysis Layer"]
+        AL1["DEB (Dynamic Error Balancing)"]
+        AL2["Probability Engine (mu + buckets)"]
+        AL3["Trend Engine"]
+        AL4["Risk Profiles"]
+        AL5["Mispricing Radar"]
+    end
+
+    subgraph DEL["Delivery Layer"]
+        DEL1["FastAPI"]
+        DEL2["Next.js Dashboard"]
+        DEL3["Telegram Bot"]
+        DEL4["Alert Push"]
+    end
+
+    subgraph OL["Ops Layer"]
+        OL1["Docker Compose (VPS backend + bot)"]
+        OL2["Vercel (frontend)"]
+        OL3["Cache + force_refresh"]
+        OL4["Speed Insights"]
+    end
+
+    A --> DL
+    A --> AL
+    A --> DEL
+    A --> OL
 ```

 ## Architecture
@@ -12,34 +12,47 @@
 - 将模型概率与 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"
+flowchart TD
+    A["PolyWeather Pro"]
+
+    subgraph DL["数据层"]
+        DL1["METAR (Aviation Weather / METAR)"]
+        DL2["MGM (土耳其 MGM)"]
+        DL3["安卡拉主站 (17130 Center)"]
+        DL4["Open-Meteo"]
+        DL5["weather.gov (美国城市)"]
+        DL6["Polymarket (P0 只读)"]
+    end
+
+    subgraph AL["分析层"]
+        AL1["DEB (动态误差平衡)"]
+        AL2["概率引擎 (mu + 桶分布)"]
+        AL3["趋势引擎"]
+        AL4["城市风险档案"]
+        AL5["错价雷达"]
+    end
+
+    subgraph DEL["交付层"]
+        DEL1["FastAPI"]
+        DEL2["Next.js 仪表盘"]
+        DEL3["Telegram Bot"]
+        DEL4["预警推送"]
+    end
+
+    subgraph OL["运维层"]
+        OL1["Docker Compose (VPS)"]
+        OL2["Vercel (前端)"]
+        OL3["缓存 + force_refresh"]
+        OL4["Speed Insights"]
+    end
+
+    A --> DL
+    A --> AL
+    A --> DEL
+    A --> OL
 ```

 ## 系统架构
@@ -20,22 +20,27 @@
 ## 2. API 思维导图

 ```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 只读)"
+flowchart TD
+    A["PolyWeather API"]
+
+    subgraph E["接口分组"]
+        E1["GET /api/cities"]
+        E2["GET /api/city/{name}"]
+        E3["GET /api/city/{name}/summary"]
+        E4["GET /api/city/{name}/detail"]
+        E5["GET /api/history/{name}"]
+    end
+
+    subgraph O["关键对象"]
+        O1["current"]
+        O2["forecast"]
+        O3["probabilities (mu + distribution)"]
+        O4["multi_model / multi_model_daily"]
+        O5["market_scan (P0 只读)"]
+    end
+
+    A --> E
+    A --> O
 ```

 ---
@@ -15,27 +15,40 @@ It is a decision-support layer for temperature-settlement markets:

 ---

-## 2. Business Mindmap
+## 2. Business Overview Diagram

 ```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"
+flowchart TD
+    A["PolyWeather Monetization"]
+
+    subgraph P["Product"]
+        P1["Telegram Signal Channel"]
+        P2["Web Dashboard"]
+        P3["VIP Bundle"]
+    end
+
+    subgraph R["Pricing"]
+        R1["Entry 1 USD"]
+        R2["Dashboard 5 USD"]
+        R3["Bundle 5.5 USD"]
+    end
+
+    subgraph AC["Access Control"]
+        AC1["Manual activation (P1)"]
+        AC2["Wallet/USDC detection (P2)"]
+        AC3["Entitlement middleware"]
+    end
+
+    subgraph G["Growth"]
+        G1["Accuracy reports"]
+        G2["Retention analytics"]
+        G3["User preference center"]
+    end
+
+    A --> P
+    A --> R
+    A --> AC
+    A --> G
 ```

 ---
@@ -7,20 +7,33 @@ Purpose: keep engineering debt explicit while shipping production features.
 ## 1. Debt Landscape

 ```mermaid
-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"
+flowchart TD
+    A["Tech Debt"]
+
+    subgraph AR["Architecture"]
+        AR1["Monolithic bot entry"]
+        AR2["Shared runtime coupling"]
+    end
+
+    subgraph PI["Product Infra"]
+        PI1["Entitlement hardening"]
+        PI2["Subscription persistence"]
+    end
+
+    subgraph Q["Quality"]
+        Q1["Replay harness"]
+        Q2["Broader regression tests"]
+    end
+
+    subgraph O["Observability"]
+        O1["Alert evidence trace"]
+        O2["SLO dashboards"]
+    end
+
+    A --> AR
+    A --> PI
+    A --> Q
+    A --> O
 ```

 Current system health estimate: **84% stable / 16% debt**.
@@ -7,20 +7,33 @@
 ## 1. 技术债全景

 ```mermaid
-mindmap
-  root((技术债))
-    "架构层"
-      "机器人入口过于集中"
-      "共享运行时耦合"
-    "产品基础设施"
-      "订阅权限一致性"
-      "付费用户持久化"
-    "质量保障"
-      "回放测试能力"
-      "UI 回归覆盖不足"
-    "可观测性"
-      "告警证据链"
-      "SLO 看板"
+flowchart TD
+    A["技术债"]
+
+    subgraph AR["架构层"]
+        AR1["机器人入口过于集中"]
+        AR2["共享运行时耦合"]
+    end
+
+    subgraph PI["产品基础设施"]
+        PI1["订阅权限一致性"]
+        PI2["付费用户持久化"]
+    end
+
+    subgraph Q["质量保障"]
+        Q1["回放测试能力"]
+        Q2["UI 回归覆盖不足"]
+    end
+
+    subgraph O["可观测性"]
+        O1["告警证据链"]
+        O2["SLO 看板"]
+    end
+
+    A --> AR
+    A --> PI
+    A --> Q
+    A --> O
 ```

 当前系统健康度估计：**84% 稳定 / 16% 技术债**。