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 @@
|
||||
# 🛠️ 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`
|
||||
|
||||
Reference in New Issue
Block a user