From e89fdb7e09991637835a97561364b6cd22f6b1b4 Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Wed, 11 Mar 2026 11:45:57 +0800 Subject: [PATCH] feat: enhance project documentation with new overview diagrams, commercialization roadmap, and technical debt backlog. --- README.md | 65 +++++++++++++++++++++++---------------- README_ZH.md | 65 +++++++++++++++++++++++---------------- docs/API_ZH.md | 37 ++++++++++++---------- docs/COMMERCIALIZATION.md | 51 ++++++++++++++++++------------ docs/TECH_DEBT.md | 41 +++++++++++++++--------- docs/TECH_DEBT_ZH.md | 41 +++++++++++++++--------- 6 files changed, 185 insertions(+), 115 deletions(-) diff --git a/README.md b/README.md index 35026a5e..72c123a4 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README_ZH.md b/README_ZH.md index a165a1f8..39394df7 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -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 ``` ## 系统架构 diff --git a/docs/API_ZH.md b/docs/API_ZH.md index 2c9aef0d..23aba9d9 100644 --- a/docs/API_ZH.md +++ b/docs/API_ZH.md @@ -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 ``` --- diff --git a/docs/COMMERCIALIZATION.md b/docs/COMMERCIALIZATION.md index ba938d40..2bccc06b 100644 --- a/docs/COMMERCIALIZATION.md +++ b/docs/COMMERCIALIZATION.md @@ -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 ``` --- diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md index e0bdb5b9..cb27388d 100644 --- a/docs/TECH_DEBT.md +++ b/docs/TECH_DEBT.md @@ -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**. diff --git a/docs/TECH_DEBT_ZH.md b/docs/TECH_DEBT_ZH.md index 36e7318f..1c9c12d3 100644 --- a/docs/TECH_DEBT_ZH.md +++ b/docs/TECH_DEBT_ZH.md @@ -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% 技术债**。