320 lines
10 KiB
Markdown
320 lines
10 KiB
Markdown
# Production Realtime SSE Patch Design
|
||
|
||
> 日期: 2026-05-26
|
||
> 范围: PolyWeather 网站终端图表的生产级实时观测增量层
|
||
> 目标服务器: 2 vCPU / 8 GB RAM / 50 GB 系统盘
|
||
|
||
## 背景
|
||
|
||
当前网站已经有 SSE patch 通道，但它更像一个进程内即时广播层：
|
||
|
||
- 后端 `web/sse_manager.py` 用进程内 `asyncio.Queue` 管连接。
|
||
- 采集器通过 `/api/internal/collector-patch` 推送城市温度变化。
|
||
- 前端 `use-sse-patches.ts` 用 `EventSource` 接收 patch，并把温度合并到终端列表和图表。
|
||
|
||
这个结构能做轻量实时更新，但还不是生产级“像股票行情一样”的实时架构。主要缺口是：
|
||
|
||
- 断线后没有 replay event log。
|
||
- 连接不能按城市订阅，只能广播后让前端筛选。
|
||
- patch schema 没有版本化，后续扩展跑道、站点、最高温字段风险较高。
|
||
- 多实例共享 pub/sub 还没有抽象边界。
|
||
|
||
## 目标
|
||
|
||
把当前实时层升级为“HTTP 快照基线 + SSE 增量观测事件 + 可重放事件日志”的架构：
|
||
|
||
- 页面首屏仍通过 HTTP snapshot 加载完整 terminal rows / city detail。
|
||
- 实测温度、站点观测、跑道观测通过 SSE 增量追加到图表。
|
||
- 浏览器断线重连后可以通过 `since_revision` 补发错过的事件。
|
||
- 前端只订阅当前可见城市，例如 2x2 图表中的四个城市。
|
||
- patch payload 明确使用 `city_observation_patch.v1` schema。
|
||
- 第一版用 SQLite event log 适配当前服务器规格，预留 Redis/Postgres event bus 接口。
|
||
|
||
## 非目标
|
||
|
||
第一版不做这些事：
|
||
|
||
- 不把全部 terminal state 改成 event sourcing。
|
||
- 不用 SSE 取代 `/api/scan/terminal` 或 `/api/city/{name}/detail`。
|
||
- 不在第一版强依赖 Redis。
|
||
- 不把 DEB、多模型、概率分布改成分钟级实时更新。
|
||
- 不做 WebSocket；继续使用 SSE，因为浏览器端简单、代理友好、适合单向行情流。
|
||
|
||
## 推荐架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Collector["WeatherDataCollector"] --> Ingest["POST /api/internal/collector-patch"]
|
||
Ingest --> Normalize["Patch schema normalizer"]
|
||
Normalize --> Log["SQLite observation_patch_events"]
|
||
Normalize --> Bus["PatchEventBus"]
|
||
Bus --> SSE["GET /api/events?cities=...&since_revision=..."]
|
||
API["HTTP snapshot APIs"] --> FE["Frontend terminal/chart state"]
|
||
SSE --> FE
|
||
FE -->|gap / stale / reconnect| API
|
||
```
|
||
|
||
## 事件存储
|
||
|
||
新增 SQLite 表 `observation_patch_events`，由 `DBManager` 初始化。
|
||
|
||
字段：
|
||
|
||
- `revision INTEGER PRIMARY KEY AUTOINCREMENT`
|
||
- `schema_type TEXT NOT NULL`
|
||
- `schema_version INTEGER NOT NULL`
|
||
- `city TEXT NOT NULL`
|
||
- `source TEXT NOT NULL`
|
||
- `obs_time TEXT`
|
||
- `payload_json TEXT NOT NULL`
|
||
- `created_at TEXT NOT NULL`
|
||
|
||
索引：
|
||
|
||
- `idx_observation_patch_events_city_revision(city, revision)`
|
||
- `idx_observation_patch_events_created_at(created_at)`
|
||
|
||
保留策略：
|
||
|
||
- 默认保留 6 小时。
|
||
- event log 只用于 SSE 断线 replay，不作为日内历史曲线归档。
|
||
- 完整日内曲线仍由 `/api/city/{name}/detail` 从现有观测存储和 city cache 构建。
|
||
- 6 小时窗口覆盖浏览器短线重连、页面休眠恢复和用户午后交易窗口内的 replay；超过窗口直接触发 HTTP resync。
|
||
- 每次写入后低频触发清理，避免每条事件都扫表。
|
||
- 环境变量：`POLYWEATHER_PATCH_EVENT_RETENTION_HOURS=6`。
|
||
|
||
## Patch Schema v1
|
||
|
||
事件类型固定为：
|
||
|
||
```json
|
||
{
|
||
"type": "city_observation_patch.v1",
|
||
"revision": 12345,
|
||
"city": "shanghai",
|
||
"source": "amsc_awos",
|
||
"obs_time": "2026-05-26T10:02:00Z",
|
||
"ts": 1780000000000,
|
||
"payload": {
|
||
"temp": 30.4,
|
||
"max_so_far": 31.0,
|
||
"station_code": "ZSPD",
|
||
"station_label": "Shanghai Pudong",
|
||
"series_key": "airport_primary",
|
||
"unit": "celsius",
|
||
"runway_points": [
|
||
{
|
||
"runway": "17L/35R",
|
||
"temp": 30.8,
|
||
"tdz_temp": 30.5,
|
||
"mid_temp": 30.6,
|
||
"end_temp": 30.8,
|
||
"is_settlement": true
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
兼容要求：
|
||
|
||
- 前端仍接受旧 `city_patch` 一段时间，避免部署顺序问题。
|
||
- 新事件统一转换成前端内部 `CityPatch`。
|
||
- 后端 ingest 接受旧字段 `changes`，但写入 event log 时规范化成 v1。
|
||
|
||
## SSE API
|
||
|
||
`GET /api/events`
|
||
|
||
查询参数：
|
||
|
||
- `cities`: 逗号分隔城市 key，例如 `shanghai,hong kong,taipei`
|
||
- `since_revision`: 客户端上次处理过的最大 revision
|
||
- `replay_limit`: 最大补发数量，默认 500，上限 2000
|
||
|
||
连接行为：
|
||
|
||
1. 建立连接。
|
||
2. 返回 `connected` event，包含当前 server revision。
|
||
3. 如果传入 `since_revision`，先从 SQLite 补发匹配城市的历史事件。
|
||
4. 进入 live stream，只推送匹配城市的事件。
|
||
5. 每 30 秒发送 heartbeat。
|
||
|
||
gap 处理：
|
||
|
||
- 如果 `since_revision` 太旧，超过保留窗口或补发上限，服务端发送：
|
||
|
||
```json
|
||
{
|
||
"type": "resync_required",
|
||
"reason": "replay_window_exceeded",
|
||
"latest_revision": 12345
|
||
}
|
||
```
|
||
|
||
- 前端收到后对当前可见城市调用 HTTP full detail resync。
|
||
|
||
## 后端模块边界
|
||
|
||
新增或调整模块：
|
||
|
||
- `web/realtime_patch_schema.py`
|
||
- 负责规范化旧 `city_patch` 输入为 `city_observation_patch.v1`。
|
||
- 负责校验城市、温度、时间、source。
|
||
|
||
- `web/realtime_event_store.py`
|
||
- 封装 SQLite event log 写入、查询、保留清理。
|
||
- 使用 `DBManager` 的 DB path。
|
||
|
||
- `web/sse_manager.py`
|
||
- 从纯进程队列升级为基于 `PatchEventBus` 的连接管理。
|
||
- 保留进程内 live fanout。
|
||
- 每个连接记录订阅城市集合。
|
||
|
||
- `web/routers/sse_router.py`
|
||
- 解析 `cities`、`since_revision`、`replay_limit`。
|
||
- ingest 后先写 event log，再广播 live event。
|
||
|
||
第一版 `PatchEventBus`：
|
||
|
||
- `SQLitePatchEventBus`
|
||
- 写入 SQLite event log。
|
||
- 进程内广播给当前 worker 的连接。
|
||
|
||
后续可新增：
|
||
|
||
- `RedisPatchEventBus`
|
||
- `PostgresPatchEventBus`
|
||
|
||
## 前端模块边界
|
||
|
||
调整：
|
||
|
||
- `frontend/hooks/use-sse-patches.ts`
|
||
- 支持 `city_observation_patch.v1`。
|
||
- 记录 `lastRevision`。
|
||
- 支持按可见城市集合建立 SSE URL。
|
||
- 收到 `resync_required` 时通知图表重拉。
|
||
|
||
- `frontend/components/dashboard/scan-terminal/use-scan-terminal-query.ts`
|
||
- 继续负责 terminal rows 的 HTTP snapshot。
|
||
- 消费 patch 时只更新轻量字段：当前温度、最高温、观测时间。
|
||
|
||
- `frontend/components/dashboard/scan-terminal/LiveTemperatureThresholdChart.tsx`
|
||
- 消费 patch 时追加分钟级观测点。
|
||
- 对 runway patch 更新对应 runway series。
|
||
- resync required 或长时间无 patch 时重拉 `/api/city/{name}/detail`。
|
||
|
||
城市订阅策略：
|
||
|
||
- 2x2 / 3x3 图表只订阅当前 slots 中的城市。
|
||
- 移动端只订阅当前主图城市。
|
||
- 切换布局或城市后重建 SSE 连接。
|
||
|
||
## 数据流
|
||
|
||
### 首屏加载
|
||
|
||
1. 前端调用 `/api/scan/terminal` 得到 terminal rows。
|
||
2. 每个可见图表调用 `/api/city/{name}/detail` 得到完整基线曲线。
|
||
3. 前端用可见城市列表连接 `/api/events?cities=...&since_revision=...`。
|
||
|
||
### 新观测进入
|
||
|
||
1. `WeatherDataCollector` 发现温度或跑道观测变化。
|
||
2. POST `/api/internal/collector-patch`。
|
||
3. 后端规范化为 `city_observation_patch.v1`。
|
||
4. 写入 SQLite event log，生成 revision。
|
||
5. 广播给订阅该城市的 SSE 连接。
|
||
6. 前端追加图表点并更新 terminal row。
|
||
|
||
### 断线重连
|
||
|
||
1. 前端保留 `lastRevision`。
|
||
2. EventSource 断线后指数退避重连。
|
||
3. 重连 URL 带 `since_revision=lastRevision`。
|
||
4. 后端 replay missed events。
|
||
5. 如果 replay 不完整，返回 `resync_required`，前端 HTTP 重拉。
|
||
|
||
## 错误处理
|
||
|
||
- ingest payload 无 city 或无有效 temp/runway point：返回 400。
|
||
- event log 写入失败：返回 500，不广播，避免前端看到不可 replay 的事件。
|
||
- SSE replay 查询失败：发送 `resync_required`，然后继续 heartbeat/live stream。
|
||
- 前端收到未知 schema：忽略并记录 debug log。
|
||
- 前端 revision 倒退：忽略。
|
||
- 前端 revision 跳号：标记 gap，并触发 HTTP resync。
|
||
|
||
## 测试策略
|
||
|
||
后端：
|
||
|
||
- `tests/test_realtime_patch_schema.py`
|
||
- 旧 `city_patch` 输入能规范化成 `city_observation_patch.v1`。
|
||
- 跑道 payload 保留 runway point。
|
||
- 无效 city/temp 返回校验失败。
|
||
|
||
- `tests/test_realtime_event_store.py`
|
||
- append event 生成单调 revision。
|
||
- replay 按 city 过滤。
|
||
- retention cleanup 删除旧事件。
|
||
|
||
- `tests/test_sse_replay.py`
|
||
- `/api/events?cities=...&since_revision=...` 只 replay 匹配城市。
|
||
- replay window 超限返回 `resync_required`。
|
||
|
||
前端：
|
||
|
||
- `frontend/components/dashboard/scan-terminal/__tests__/ssePatchArchitecture.test.ts`
|
||
- 确认 v1 schema、city subscription、since_revision URL 存在。
|
||
|
||
- `frontend/components/dashboard/scan-terminal/__tests__/temperatureDefaultVisibilityPolicy.test.ts`
|
||
- 确认 patch 追加分钟级观测点。
|
||
- 确认 runway patch 更新对应 runway series。
|
||
|
||
验收命令：
|
||
|
||
```powershell
|
||
pytest tests/test_realtime_patch_schema.py tests/test_realtime_event_store.py tests/test_sse_replay.py
|
||
cd frontend
|
||
npm run test:business
|
||
npm run typecheck
|
||
npm run build
|
||
```
|
||
|
||
## 部署与容量
|
||
|
||
当前服务器 2 vCPU / 8 GB / 50 GB 足够第一版 SQLite-first：
|
||
|
||
- 30 个高频城市，每分钟 1 条事件，约 43,200 条/天。
|
||
- 默认只保留 6 小时，约 10,800 条事件。
|
||
- payload 控制在 1-3 KB，SQLite event log 体积预计维持在几十 MB 内。
|
||
- PM 最高温预测市场不需要把当天所有 patch 都保留在 event log；超过 replay 窗口时用 HTTP detail 重建当前画面。
|
||
|
||
运行建议：
|
||
|
||
- SQLite 使用 WAL。
|
||
- event log 与现有 `POLYWEATHER_DB_PATH` 同库。
|
||
- 先保持单 backend worker，避免进程内 fanout 跨 worker 不一致。
|
||
- 多实例或多 worker 时再启用 Redis bus。
|
||
|
||
## 后续 Redis 扩展
|
||
|
||
当部署变成多实例或多 worker 后，新增 `RedisPatchEventBus`：
|
||
|
||
- SQLite 仍作为 replay log。
|
||
- Redis Pub/Sub 或 Redis Stream 负责跨实例 live fanout。
|
||
- 每个 worker 从 Redis 订阅 live event，再投递给本进程 SSE 连接。
|
||
|
||
这个扩展不改变前端协议。
|
||
|
||
## 验收标准
|
||
|
||
- 页面加载后可见图表只订阅当前城市。
|
||
- 高频城市新观测进入后，图表在无需手动刷新下追加新点。
|
||
- 浏览器断线重连后，能补齐断线期间的事件。
|
||
- replay 超窗时，前端自动 HTTP resync。
|
||
- 未订阅城市的事件不会推送到该连接。
|
||
- 旧 `city_patch` 输入在迁移期仍可用。
|
||
- 所有新增行为有自动化测试覆盖。
|