From cb393fd97a8473ee14cd10aab9dc1fe36ddd726c Mon Sep 17 00:00:00 2001 From: "2569718930@qq.com" <2569718930@qq.com> Date: Wed, 4 Mar 2026 02:35:35 +0800 Subject: [PATCH] docs: add TECH_DEBT.md with honest assessment and roadmap --- docs/TECH_DEBT.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/TECH_DEBT.md diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md new file mode 100644 index 00000000..8c5780b6 --- /dev/null +++ b/docs/TECH_DEBT.md @@ -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 的气象数据整合成可快速消化的仪表盘。至于"预测准不准"，诚实的回答是：**不知道，因为还没有建立衡量准确率的机制**。