docs: add TECH_DEBT.md with honest assessment and roadmap

2026-03-04 02:35:35 +08:00
parent 63ea4d0a80
commit cb393fd97a
1 changed files with 116 additions and 0 deletions
@@ -0,0 +1,116 @@
+# PolyWeather 技术债与演进路线
+
+> 最后更新：2026-03-04
+
+---
+
+## 一、当前完成度：约 65%
+
+### ✅ 已经可用
+
+| 模块             | 状态         | 说明                                                           |
+| ---------------- | ------------ | -------------------------------------------------------------- |
+| 多源数据采集     | **可用**     | Open-Meteo / ECMWF / GFS / ICON / GEM / JMA / METAR / MGM      |
+| DEB 动态融合预报 | **可用**     | 误差加权 + 自学习 + 冷启动处理                                 |
+| 概率引擎         | **基本可用** | Gaussian 拟合 + Shock Score + 时间衰减 + 实况锚定 μ + 死盘覆盖 |
+| AI 决策          | **基本可用** | P0→P4 分级框架 + 预报失准分级 + 高可用降级                     |
+| Telegram Bot     | **稳定运行** | 当前最成熟的交互端                                             |
+| Web 仪表盘       | **基本可用** | 地图 + 面板 + 图表均可运作，完善度不如 Bot                     |
+| 部署             | **可用**     | Docker + 传统 VPS 双通道，`update.sh` 一键部署                 |
+
+### ⚠️ 真实能力边界
+
+1. **概率引擎的 μ 是手工规则（非统计学习的）**。70/30 加权 + 实况锚定的逻辑在多数情况下"看起来合理"，但没有经过回测校准，在极端天气下的准确性无统计保障。
+2. **AI 决策是"结构化的猜测"**。Prompt 再精巧，底层仍是 LLM 概率续写。AI 有时自相矛盾，置信度是自评的，不代表真实概率。
+3. **Shock Score 是启发式指标**。风向/云量/气压权重（0.4/0.35/0.25）未经回归验证。
+4. **DEB 自学习窗口只有 7 天**，无法捕捉季节性趋势。
+5. **Web 端图表数据来自 Open-Meteo 分析值**，已过时段与 METAR 实测存在 1-2°C 偏差（已标注为"OM 模型"并叠加 METAR 散点）。
+
+---
+
+## 二、技术债
+
+### 🔴 高优先级
+
+| 问题                       | 影响                                                                     | 建议                                                                     |
+| -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `bot_listener.py` 过于臃肿 | 单文件 1200 行，混杂数据处理、概率计算、趋势分析、AI 调用。可维护性极差  | 将 `analyze_weather_trend` 和概率引擎拆到 `src/analysis/trend_engine.py` |
+| Web 与 Bot 概率引擎重复    | 两端各有独立的概率计算代码。AI 上下文已统一，但概率分布仍各算各的        | Web 端应直接复用 Bot 端的概率结果，或提取到共享模块                      |
+| 无测试覆盖                 | 概率引擎、DEB 算法、趋势分析等核心逻辑没有单元测试，任何改动只能人肉验证 | 至少覆盖：μ/σ 计算、死盘判定、forecast bust 检测                         |
+
+### 🟡 中优先级
+
+| 问题               | 影响                                                                        | 建议                                   |
+| ------------------ | --------------------------------------------------------------------------- | -------------------------------------- |
+| 无回测框架         | 无法用历史数据验证算法改动是否真的提升了准确率，改代码全凭直觉              | 用 `fetch_history.py` 的数据搭回测管线 |
+| 硬编码阈值散落各处 | 死盘 (3°C/1.5°C)、forecast bust (2°C)、Shock Score 权重等直接写在业务代码里 | 提取到配置文件或 `constants.py`        |
+| MGM 数据源不稳定   | 经常 403，fallback 逻辑虽有但增加延迟                                       | 考虑增加本地缓存或二次 fallback        |
+
+### 🟢 低优先级
+
+| 问题              | 影响                                                | 建议                       |
+| ----------------- | --------------------------------------------------- | -------------------------- |
+| 缓存策略粗糙      | Web 端用简单 dict + 过期时间，无 LRU 或容量限制     | 引入 `cachetools` 或 Redis |
+| 日志没有结构化    | loguru 直接 print，上线后难做分析和报警             | 改用 JSON 格式 + 集中收集  |
+| CI badge 链接失效 | 已移除 GitHub Actions 但 README 之前还留着 CI badge | 已在本次文档更新中修复     |
+
+---
+
+## 三、未完成功能
+
+| #   | 功能                | 说明                                                     |
+| --- | ------------------- | -------------------------------------------------------- |
+| 1   | 历史数据消费        | `fetch_history.py` 可采集 3 年数据，但没有任何模型在使用 |
+| 2   | 结算自动对账        | 系统不知道昨天的预测对不对（`/deb` 需人工触发）          |
+| 3   | 交易信号输出        | 系统只给分析建议，不输出可执行的交易信号                 |
+| 4   | Web 身份认证        | 任何人都可以访问 Web 面板                                |
+| 5   | 主动推送            | 预报崩盘或结算边界预警时不会主动通知用户                 |
+| 6   | 完整日内 METAR 走势 | `trend.recent` 只保留最近 4 条，无法展示完整日内观测曲线 |
+
+---
+
+## 四、演进路线
+
+### 短期（1-2 周）— 偿还核心债务
+
+1. **拆分 `bot_listener.py`**
+   - 将 `analyze_weather_trend` 移到 `src/analysis/trend_engine.py`
+   - 将概率引擎移到 `src/analysis/probability.py`
+   - `bot_listener.py` 只保留 Telegram 交互逻辑
+
+2. **概率引擎统一**
+   - Web 端概率计算应直接调用共享模块的结果
+   - 消除两份独立实现
+
+3. **核心单元测试**
+   - 测试范围：μ/σ 计算、死盘判定、forecast bust 检测、DEB 权重计算
+   - 不追求覆盖率，追求"改代码时有安全网"
+
+### 中期（1-2 月）— 建立校验能力
+
+4. **回测框架**
+   - 用历史数据跑"过去 90 天每天的 μ 偏差是多少"
+   - 这是证明概率引擎有效的唯一方式
+
+5. **结算自动对账**
+   - 每天自动拉取合约实际结算结果
+   - 与系统前一天的预测做比对，自动生成准确率报告
+
+6. **推送机制**
+   - 检测到 forecast bust 或结算边界预警时主动推送 Telegram 通知
+
+### 长期（3+ 月）— 从规则到模型
+
+7. **MOS/XGBoost 替代手工 μ**
+   - 用历史 METAR + 模型预报训练后处理模型
+   - 概率引擎从"合理的猜测"升级到"可校验的预测"
+
+8. **多市场适配**
+   - 当前只针对温度合约
+   - 扩展到降水、风速等需要重构分析框架
+
+---
+
+## 五、一句话总结
+
+> PolyWeather 目前最大的价值是**信息聚合和格式化**——把分散在多个 API 的气象数据整合成可快速消化的仪表盘。至于"预测准不准"，诚实的回答是：**不知道，因为还没有建立衡量准确率的机制**。