feat: implement AI city forecast streaming service and documentation

docs/API_ZH.md

@@ -1,6 +1,6 @@
 # PolyWeather API 文档（v1.5.4）
 
-最后更新：`2026-04-18`
+最后更新：`2026-04-27`
 
 本文档描述当前对外可用 API 口径（`web/app.py` + `web/routes.py` + `frontend/app/api/*`）。
 
@@ -31,6 +31,8 @@ flowchart LR
 | `/api/city/{name}/summary` | GET | 轻量摘要 |
 | `/api/city/{name}/detail` | GET | 聚合详情（含 market_scan） |
 | `/api/history/{name}` | GET | 历史对账 |
+| `/api/scan/terminal/ai-city` | POST | 城市决策卡 AI 解读（非流式 JSON） |
+| `/api/scan/terminal/ai-city/stream` | POST | 城市决策卡 AI 解读（SSE 流式） |
 
 ### `GET /api/city/{name}/detail`
 
@@ -59,6 +61,47 @@ flowchart LR
 - `vertical_profile_signal.heating_setup / suppression_risk / trigger_risk / mixing_strength`
 - `taf.signal.peak_window / suppression_level / disruption_level / markers`
 
+### `POST /api/scan/terminal/ai-city/stream`
+
+城市决策卡使用该接口生成“AI 机场报文解读”。前端默认请求 SSE 流，流式展示机场报文解读片段，最终以 `final` 事件返回完整 payload。
+
+请求体：
+
+```json
+{
+  "city": "Buenos Aires",
+  "force_refresh": false,
+  "locale": "zh-CN"
+}
+```
+
+SSE 事件：
+
+- `progress`：阶段性状态，例如开始调用 AI、切换非流式重试。
+- `preview`：可显示的预览文本。
+- `delta`：模型流式文本增量，前端会从中提取机场报文解读片段。
+- `final`：完整 `AiCityForecastPayload`。
+
+重点字段：
+
+- `status`：通常为 `ready`；超时或降级时会带 `reason / reason_zh / reason_en`。
+- `cached`：是否命中后端 AI 缓存。
+- `degraded`：是否为降级结果。前端不会把 degraded 结果写入长期 localStorage，但会保留页面内存态，避免切换选项卡后空白。
+- `city_forecast.predicted_max`：AI 给出的预计最高温中枢候选。
+- `city_forecast.range_low / range_high`：AI 给出的天气区间。
+- `city_forecast.final_judgment_zh / final_judgment_en`：最终判断。
+- `city_forecast.metar_read_zh / metar_read_en`：机场报文解读。
+- `city_forecast.reasoning_zh / reasoning_en`：把 METAR、DEB、多模型集群与日内风险合并后的推理。
+- `city_forecast.model_cluster_note_zh / model_cluster_note_en`：模型集群说明。
+- `city_forecast.risks_zh / risks_en`：后续上修或下修触发条件。
+
+### 城市决策卡市场层口径
+
+- 前端会请求完整 `market_scan` / `all_buckets`，而不是只取 lite 结果。
+- 温度桶匹配按今日预计最高温中枢映射，并区分 exact、range、or higher、or lower，避免把 30°C 附近的天气中枢误配到不合理尾部桶。
+- `模型-市场差 = 模型概率 - 市场隐含概率`。正值表示天气概率高于市场报价；负值表示市场已经更充分计价。
+- 温度桶标签会统一规范化 `C/F/°C/°F`，避免前端重复显示单位。
+
 ### `detail` 新增结构信号说明
 
 `/api/city/{name}/detail` 现在会返回一组更偏交易场景的结构字段：
@@ -253,6 +296,10 @@ flowchart LR
 - 详情接口与支付接口：`no-store`
 - `METAR` / `TAF` / settlement current 由后端各自维护短 TTL 缓存
 - 前端打开今日日内分析时，如果 full detail 或 market scan 正在同步，会先显示刷新锁，不展示可交互的旧内容
+- 城市决策卡 AI 解读前端缓存键为 `city + local_date + locale + METAR signature`；signature 优先使用原始 METAR，缺失时回退到报文时间、观测时间和温度
+- 城市决策卡 AI 解读使用两层前端缓存：页面内存缓存保存 loading / 流式进度 / 最终 payload，`localStorage` 保存最终成功 payload，默认 TTL 1 小时
+- 后端城市 AI 缓存不使用 `local_time` 作为 key，避免同一观测因当前时钟变化反复失效
+- 城市市场扫描完整桶缓存按 `city + local_date + full` 存储，默认 TTL 10 分钟
 
 ## 9. 调试示例