From 27fe6ea49412b6b3fd64013b3e246bef0d23e40e Mon Sep 17 00:00:00 2001
From: "2569718930@qq.com" <2569718930@qq.com>
Date: Thu, 12 Mar 2026 10:43:31 +0800
Subject: [PATCH] feat: Introduce API and technical debt documentation, and
 enhance frontend caching, mispricing radar, and AI decision logic.

---
 README.md            | 34 +++++++++++++++++++++++++++++++---
 README_ZH.md         | 34 +++++++++++++++++++++++++++++++---
 docs/API_ZH.md       | 43 ++++++++++++++++++++++++++++++++++++++++---
 docs/TECH_DEBT.md    |  9 ++++++---
 docs/TECH_DEBT_ZH.md |  9 ++++++---
 5 files changed, 114 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 6c9e239c..bea37437 100644
--- a/README.md
+++ b/README.md
@@ -97,9 +97,23 @@ graph TD
 | Market layer        | Polymarket P0 read-only discovery + quotes           |
 | Removed source      | Meteoblue (fully removed from code and docs)         |
 
-## Recent Changes (2026-03-11)
+## Recent Changes (2026-03-12)
 
 - Removed all Meteoblue API integration and references.
+- Added frontend BFF `ETag + Cache-Control` for:
+  - `/api/cities`
+  - `/api/city/{name}/summary` (`force_refresh=true` keeps `no-store`)
+  - `/api/history/{name}`
+- Added frontend state persistence:
+  - selected city in `localStorage`
+  - risk-group collapse state in sidebar `localStorage`
+  - background summary revision check to silently refresh stale detail cache
+- Mispricing radar safety hardening:
+  - skip non-tradable markets (`closed`, inactive, not accepting orders, or past `endDate`)
+  - propagate tradable state in `market_scan.primary_market`
+- AI decision guard:
+  - peak-window state (`before` / `in_window` / `past`) now explicitly injected into AI context
+  - before-peak state now forbids "locked/confirmed floor" style conclusions
 - Fixed market top-bucket rendering path by deduplicating repeated temperature buckets.
 - Added frontend fallback guard when market top buckets collapse to low-quality duplicates.
 - Fixed detail panel accessibility issue (`aria-hidden` focus conflict) using `inert` + active-element blur.
@@ -135,6 +149,20 @@ cd frontend
 npm run build
 ```
 
+## Operations Verification
+
+### Validate frontend cache headers (`ETag` / `304` / `force_refresh=no-store`)
+
+```bash
+./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
+```
+
+### Watch mispricing radar push decisions
+
+```bash
+docker compose logs -f polyweather | egrep "market not tradable|trade alert pushed|mispricing cap"
+```
+
 ## Command Surface (Telegram)
 
 | Command        | Purpose                       |
@@ -154,6 +182,6 @@ npm run build
 
 ## Status
 
-- Version: `v1.3`
-- Last Updated: `2026-03-11`
+- Version: `v1.4`
+- Last Updated: `2026-03-12`
 - Runtime: Stable (web + bot + market read-only layer in production)
diff --git a/README_ZH.md b/README_ZH.md
index c3c37f80..91061ba9 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -97,9 +97,23 @@ graph TD
 | 市场层         | Polymarket P0 只读发现 + 报价     |
 | 已移除         | Meteoblue（代码与文档已全部移除） |
 
-## 最近更新（2026-03-11）
+## 最近更新（2026-03-12）
 
 - 完整移除 Meteoblue API 及全部引用。
+- 前端 BFF 增加 `ETag + Cache-Control`：
+  - `/api/cities`
+  - `/api/city/{name}/summary`（`force_refresh=true` 仍保持 `no-store`）
+  - `/api/history/{name}`
+- 前端状态持久化优化：
+  - 记住上次选中城市（`localStorage`）
+  - 记住侧边栏风险分组折叠状态（`localStorage`）
+  - 详情命中缓存时做后台 revision 检查，静默更新陈旧数据
+- 错价雷达安全加固：
+  - 市场 `closed` / 不活跃 / 不接受下单 / 超过 `endDate` 时跳过推送
+  - `market_scan.primary_market` 透传可交易状态字段
+- AI 决策时段约束：
+  - 上下文显式注入峰值窗口状态（`before` / `in_window` / `past`）
+  - 峰值窗口前禁止“已锁定/已确认底线”结论
 - 修复市场“最热温度桶”重复温度刷屏问题（后端按温度去重 + 前端兜底去重）。
 - 修复详情面板可访问性告警（`aria-hidden` 焦点冲突），改为 `inert + blur`。
 - 集成 Vercel Speed Insights（`frontend/app/layout.tsx`）。
@@ -134,6 +148,20 @@ cd frontend
 npm run build
 ```
 
+## 运维验收
+
+### 验证前端缓存头（`ETag` / `304` / `force_refresh=no-store`）
+
+```bash
+./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
+```
+
+### 观察错价雷达推送决策日志
+
+```bash
+docker compose logs -f polyweather | egrep "market not tradable|trade alert pushed|mispricing cap"
+```
+
 ## Telegram 命令
 
 | 命令           | 用途         |
@@ -153,6 +181,6 @@ npm run build
 
 ## 当前状态
 
-- 版本：`v1.3`
-- 最后更新：`2026-03-11`
+- 版本：`v1.4`
+- 最后更新：`2026-03-12`
 - 状态：稳定运行（Web + Bot + 市场只读层）
diff --git a/docs/API_ZH.md b/docs/API_ZH.md
index a05104a2..e934f16a 100644
--- a/docs/API_ZH.md
+++ b/docs/API_ZH.md
@@ -1,4 +1,4 @@
-# PolyWeather API 文档（v1.2）
+# PolyWeather API 文档（v1.4）
 
 本文档描述当前后端真实可用接口（`web/app.py`）。  
 前端一般通过 Next.js BFF 路由代理访问这些接口。
@@ -12,7 +12,12 @@
 - 返回格式：`application/json`
 - 缓存策略：
   - 后端分析缓存：默认 5 分钟（Ankara 特殊口径 60 秒）
-  - 前端详情缓存：5 分钟 + revision 检查
+  - 前端详情缓存：5 分钟 + revision 检查 + 后台静默刷新
+  - 前端 BFF HTTP 缓存（Vercel 层）：
+    - `/api/cities`：`ETag` + `Cache-Control`（`s-maxage=300`）
+    - `/api/city/{name}/summary`：`ETag` + `Cache-Control`（`s-maxage=20`）
+    - `/api/history/{name}`：`ETag` + `Cache-Control`（`s-maxage=60`）
+    - `summary?force_refresh=true`：`Cache-Control: no-store`
   - 手动刷新：`force_refresh=true` 强制绕过缓存
 
 ---
@@ -128,6 +133,11 @@ flowchart TD
 - `risk.level`, `risk.warning`
 - `updated_at`
 
+缓存说明：
+
+- 通过前端 BFF 访问时，默认返回 `ETag` 与可缓存 `Cache-Control`。
+- 当 `force_refresh=true` 时，BFF 强制 `no-store`，用于人工排障与即时刷新。
+
 ### 4.4 `GET /api/city/{name}/detail`
 
 聚合视图接口，包含天气分析和市场只读层。
@@ -158,11 +168,16 @@ flowchart TD
 - `top_buckets`（前端展示前会再去重）
 - `signal_label`（`BUY YES` / `BUY NO` / `MONITOR`）
 - `websocket.asset_ids`, `websocket.condition_ids`（订阅标识，不涉及下单）
+- `primary_market.tradable`（是否可交易）
+- `primary_market.tradable_reason`（不可交易原因）
+- `primary_market.ended_at_utc`（UTC 结束时刻）
+- `primary_market.accepting_orders`（是否仍接收订单）
 
 注意：
 
 - 后端已做温度桶去重与方向优先（优先与主市场同方向的 `or higher`/`or lower` 桶）。
 - 前端还有二次去重兜底，避免重复温度桶刷屏。
+- 错价雷达推送前会二次校验交易状态，若市场已不可交易（`closed` / inactive / 不接单 / 过 `endDate`）会跳过。
 
 ### 4.5 `GET /api/history/{name}`
 
@@ -249,6 +264,28 @@ sequenceDiagram
 - 浏览器强刷（`Ctrl+F5`）
 - 检查是否命中前端 5 分钟 TTL
 
+### 7.4 为什么 VPS `:8000` 看不到 `ETag`？
+
+- `:8000` 是 FastAPI 后端直连口径，主要负责分析与数据聚合。
+- `ETag/304` 主要由前端 BFF 路由返回（Vercel 域名下的 `/api/*`）。
+- 验证缓存头请用前端域名，而不是后端直连 IP。
+
 ---
 
-最后更新：`2026-03-11`
+## 8. 验收脚本
+
+项目内置缓存验收脚本：
+
+```bash
+./scripts/validate_frontend_cache.sh "https://polyweather-pro.vercel.app"
+```
+
+输出 `Result: PASS` 代表以下链路均正常：
+
+- `ETag` 返回
+- `If-None-Match -> 304`
+- `force_refresh=true -> no-store`
+
+---
+
+最后更新：`2026-03-12`
diff --git a/docs/TECH_DEBT.md b/docs/TECH_DEBT.md
index cb27388d..888411ce 100644
--- a/docs/TECH_DEBT.md
+++ b/docs/TECH_DEBT.md
@@ -36,16 +36,19 @@ flowchart TD
     A --> O
 ```
 
-Current system health estimate: **84% stable / 16% debt**.
+Current system health estimate: **86% stable / 14% debt**.
 
 ---
 
-## 2. Recently Closed (2026-03-11)
+## 2. Recently Closed (2026-03-12)
 
 - 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.
+- Frontend BFF `ETag + Cache-Control` landed for cities/summary/history (`force_refresh` keeps `no-store`).
+- Mispricing radar now hard-skips non-tradable markets (closed/inactive/not accepting orders/past endDate).
+- AI analysis now includes peak-window hard constraints (before-window cannot claim "locked"/"confirmed floor").
 
 ---
 
@@ -89,4 +92,4 @@ Current system health estimate: **84% stable / 16% debt**.
 
 ---
 
-Last Updated: `2026-03-11`
+Last Updated: `2026-03-12`
diff --git a/docs/TECH_DEBT_ZH.md b/docs/TECH_DEBT_ZH.md
index 1c9c12d3..ca875059 100644
--- a/docs/TECH_DEBT_ZH.md
+++ b/docs/TECH_DEBT_ZH.md
@@ -36,16 +36,19 @@ flowchart TD
     A --> O
 ```
 
-当前系统健康度估计：**84% 稳定 / 16% 技术债**。
+当前系统健康度估计：**86% 稳定 / 14% 技术债**。
 
 ---
 
-## 2. 最近已关闭项（2026-03-11）
+## 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 状态禁止“已锁定/已确认底线”）。
 
 ---
 
@@ -89,4 +92,4 @@ flowchart TD
 
 ---
 
-最后更新：`2026-03-11`
+最后更新：`2026-03-12`