feat: Introduce API and technical debt documentation, and enhance frontend caching, mispricing radar, and AI decision logic.

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`

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`

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`