chore: initialize insar management system v2

docs/archive/RADAR_PREVIEW_SCHEME_B.md

@@ -0,0 +1,86 @@
+# 源影像叠加稳定化方案（Scheme B）
+
+目标：解决“覆盖面是斜四边形，源影像是矩形包围框”的错位问题，优先保障长期稳定与前端流畅。
+
+---
+
+## 1. 问题本质
+
+当前地图展示中：
+- 覆盖范围来自 `coverage_polygon`（真实斜四边形）
+- 源图叠加常用 `imageOverlay(url, bounds)`（矩形边界）
+
+当源图本身有旋转/倾斜时，直接矩形贴图会产生明显错位。
+
+---
+
+## 2. 方案选择
+
+### A（前端实时变换）
+- 在浏览器端做逐帧几何变换
+- 优点：改动快
+- 缺点：前端负载高，图层增多后容易卡顿
+
+### B（后端预纠正缓存）✅
+- 扫描/构建阶段在后端完成几何纠正，前端只显示结果图
+- 优点：渲染轻、稳定性高、易观测
+- 缺点：后端实现复杂度更高
+
+本项目已确定采用 **B 方案**。
+
+---
+
+## 3. 当前实现（2026-02-10）
+
+## 3.1 缓存分层
+- `backend/image_cache/radar_geo/`：地理纠正后的主缓存
+- `backend/image_cache/radar_raw/`：原图回退缓存
+
+## 3.2 后端能力
+- 默认由手动扫描任务触发增量构建（前端“立即扫描”或 `POST /api/monitor/run-now`）
+- 扫描时增量构建纠正缓存（`radar_geo`）
+- 同步维护原图缓存（`radar_raw`）作为兜底
+- 方向判定优先使用 XML 的 `sceneCornerCoord/refRow/refColumn`，避免仅靠角点名称导致镜像/翻转误判
+- `GET /api/radar-data/{id}/thumb`：
+  - 优先返回 `radar_geo`
+  - 失败自动回退 `radar_raw`
+- 新增状态接口：
+  - `GET /api/radar-data/{id}/preview-status`
+  - `POST /api/radar-data/{id}/rebuild-preview-cache`（管理员）
+
+## 3.3 前端能力
+- 每条源影像显示预览状态（纠正/回退/失败/未建）
+- 管理员支持“重建”按钮
+- 预览请求增加缓存键，避免浏览器长期缓存旧图
+
+---
+
+## 4. 关键配置项
+
+```env
+RADAR_GEO_CACHE_WORKERS=2
+RADAR_GEO_CACHE_VERSION=b1
+RADAR_GEO_CACHE_QUALITY=84
+RADAR_PREVIEW_BUILD_ON_DEMAND=true
+```
+
+建议：
+- 小规模先用 `RADAR_GEO_CACHE_WORKERS=1~2`
+- 算法升级时提高 `RADAR_GEO_CACHE_VERSION` 触发重建
+
+---
+
+## 5. 验收标准
+
+- 同一场景下，源图与覆盖面边界明显趋于一致
+- 缩放/平移时交互平滑，无明显掉帧
+- 构建失败可在状态接口与日志中定位原因
+- 失败场景可回退原图缓存，不阻塞业务操作
+
+---
+
+## 6. 后续建议
+
+1. 采集 3 类典型数据（升轨/降轨/大倾斜）做对齐验收
+2. 统计 `radar_geo` 构建失败原因并分级治理
+3. 发布前执行一次全量重建，提升线上命中率