docs: Add commercialization, technical debt, and frontend documentation, and update project READMEs.

docs/TECH_DEBT_ZH.md

@@ -1,94 +1,93 @@
 # 技术债与工程待办
 
-目标：在持续交付的同时，把关键技术债显式化、可追踪化。
+目标：在持续交付的同时，让技术债可见、可追踪、可关闭。
 
 ---
 
-## 1. 技术债全景
+## 1. 债务快照
+
+当前估计：**90% 稳定 / 10% 技术债**。
 
 ```mermaid
 flowchart TD
     A["技术债"]
 
-    subgraph AR["架构层"]
-        AR1["机器人入口过于集中"]
-        AR2["共享运行时耦合"]
-    end
-
-    subgraph PI["产品基础设施"]
-        PI1["订阅权限一致性"]
-        PI2["付费用户持久化"]
+    subgraph PI["支付基础设施"]
+        PI1["支付事件入库与对账"]
+        PI2["订阅用户持久化"]
+        PI3["权限策略一致化"]
     end
 
     subgraph Q["质量保障"]
-        Q1["回放测试能力"]
-        Q2["UI 回归覆盖不足"]
+        Q1["回放仿真能力"]
+        Q2["端到端集成覆盖"]
     end
 
     subgraph O["可观测性"]
-        O1["告警证据链"]
-        O2["SLO 看板"]
+        O1["告警证据标准"]
+        O2["运维看板"]
     end
 
-    A --> AR
     A --> PI
     A --> Q
     A --> O
 ```
 
-当前系统健康度估计：**86% 稳定 / 14% 技术债**。
+---
+
+## 2. 近期已关闭（2026-03-12）
+
+- Bot 入口重构完成：
+  - `bot_listener.py` 已收敛为薄入口。
+  - 运行时拆分为编排层/处理层/服务层/分析层/守卫层/协调层。
+- 启动诊断完成：
+  - 新增 `/diag` 指令
+  - 后台循环启动状态可视化（错价雷达、Polygon 钱包、Polymarket 异动）
+- 错价锚点完成升级：从单一 Open-Meteo 改为多模型最高温锚点。
+- 不可交易市场硬拦截完成：`closed`/inactive/不接单/超结束时间全部跳过。
+- 钱包异动监听增强完成：昵称映射、链接预览开关、去抖与即时推送控制。
+- 前端 BFF `ETag/304` 缓存完成（cities/summary/history）。
+- Meteoblue 已从运行链路与文档中彻底移除。
 
 ---
 
-## 2. 最近已关闭项（2026-03-12）
-
-- Meteoblue API 全链路移除（后端/前端/配置/文档）。
-- 市场温度桶重复刷屏问题修复（后端去重 + 前端兜底）。
-- 详情面板可访问性告警修复（`aria-hidden` 焦点冲突改为 `inert + blur`）。
-- 前端已接入 Vercel Speed Insights。
-- 前端 BFF 增加 `ETag + Cache-Control`（cities/summary/history）与 `force_refresh=no-store` 语义。
-- 错价雷达增加“不可交易市场硬拦截”（closed/inactive/不接单/过 endDate）。
-- AI 分析增加峰值时段硬约束（before 状态禁止“已锁定/已确认底线”）。
-
----
-
-## 3. 高优先级技术债
+## 3. 当前高优先级技术债
 
 | 项目 | 影响 | 建议动作 |
 | :-- | :-- | :-- |
-| 机器人入口单体化（`bot_listener.py`） | 测试和重构风险高 | 拆分为编排层、IO 层、分析层 |
-| 订阅权限策略不完全统一 | 可能造成付费泄露 | 前后端统一权限校验策略 |
-| 付费用户状态持久化不足 | 人工运营不可扩展 | 迁移到托管 DB（PostgreSQL/Supabase） |
-| 告警可解释性不足 | 运维排障成本高 | 统一告警证据字段（Evidence Schema） |
+| 支付事件采集与对账流水线 | 无法稳定自动开通付费权限 | 构建幂等 payment ingest + reconciliation worker |
+| 订阅用户持久化模型 | 人工开通不可扩展 | 落地 PostgreSQL/Supabase 订阅状态 |
+| 权限策略一致性矩阵 | 存在漏放行/误拦截风险 | 统一前端中间件、后端 API、Bot 守卫策略 |
+| 告警证据协议 | 假阳性排障成本高 | 统一机器可读 Evidence Schema |
 
 ---
 
-## 4. 中优先级技术债
+## 4. 当前中优先级技术债
 
 | 项目 | 影响 | 建议动作 |
 | :-- | :-- | :-- |
-| 回放仿真能力不足 | 边缘场景难复现 | 基于历史记录构建可重复 Replay |
-| 图表/UI 回归覆盖不足 | 视觉回归风险 | 增加快照与交互自动化测试 |
-| 阈值配置分散 | 改动成本高且易错 | 统一收口到结构化配置 |
-| 命名历史包袱 | 认知成本高 | 系统化命名治理 |
+| 回放仿真能力不足 | 边缘场景回归难复现 | 基于天气+市场快照构建确定性 Replay |
+| 端到端集成覆盖不足 | 运行时回归难提前发现 | 增加 `/api/city/{name}/detail` 与推送链路集成测试 |
+| 配置项分散 | 阈值调优易出错 | 将关键 env 聚合为结构化配置分组 |
+| 命名与字段兼容历史包袱 | 认知与维护成本高 | 统一模型/市场字段命名与兼容层 |
 
 ---
 
-## 5. 低优先级技术债
+## 5. 当前低优先级技术债
 
 | 项目 | 影响 | 建议动作 |
 | :-- | :-- | :-- |
-| 冷启动波动 | 首次请求延迟不稳定 | 热点城市路由预热 |
-| 本地文件状态依赖 | 云端弹性场景受限 | 持续迁移到远程存储 |
+| 冷启动波动 | 首次请求延迟抖动 | 对热点城市路由做预热 |
+| 本地文件状态依赖 | 多实例扩展受限 | 继续迁移到托管存储 |
 
 ---
 
 ## 6. 下阶段里程碑
 
-1. 完成前后端订阅权限一致化。
-2. 上线付费用户持久化与迁移脚本。
-3. 建立告警证据标准并接入运维排障流。
-4. 落地天气+市场混合回放回归测试。
+1. 上线订阅用户 DB 与权限过期模型。
+2. 完成支付事件入库与自动授权同步。
+3. 落地天气+市场混合回放回归。
+4. 发布告警证据标准与运维排障工具。
 
 ---