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

2026-03-11 11:18:48 +08:00
parent 3cbef28b13
commit 44af26da70
6 changed files with 573 additions and 619 deletions
@@ -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`
@@ -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`
@@ -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`
@@ -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`