docs: Add comprehensive documentation for commercialization and technical debt, and streamline the main README.
This commit is contained in:
2569718930@qq.com
+52
-43
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user