147 lines
7.4 KiB
Markdown
147 lines
7.4 KiB
Markdown
# 数据产品流水线、数据源批量运维与抗击穿图层接口计划
|
||
|
||
## Summary
|
||
|
||
前端展示分两类数据：
|
||
|
||
- **图层数据**：按 viewport、bbox、zoom、limit 返回，可降级、截断、缓存，用来保护服务器。
|
||
- **聚合面板统计**：必须是全量统计，不受当前 viewport 限制，但不能实时扫全表；通过产品状态表或预计算统计提供。
|
||
|
||
也就是说：地图上低 zoom 可以只画摘要或局部数据，但面板里的“总船只数、总海缆数、BGP 活跃事件数、卫星数”等应该代表全局数据产品状态。
|
||
|
||
## Implementation Status
|
||
|
||
- 已新增 `POST /api/v1/datasources/trigger-batch`，支持按选中 `source_ids` 或筛选条件批量触发，并返回 `triggered/skipped/failed`。
|
||
- 已改造 `/datasources` 页面，支持产品域、层级、启用状态、最近执行状态、是否已有数据和关键词筛选，并支持复选框批量采集。
|
||
- 已新增 `/api/v1/data-products` 和 `/api/v1/data-products/{product_id}/status`，聚合面板可以读取全量/全局统计口径。
|
||
- 已新增 `/api/v1/layers/*` 受控图层接口骨架，要求 `bbox/zoom/limit`，响应包含 `visible_count/returned_count/diagnostics`。
|
||
- 非船只图层当前先复用已有 GeoJSON 转换再做保护层；下一步应把 cables/BGP/satellites 的 bbox 过滤继续下推到各自产品查询，避免转换前仍加载过多候选。
|
||
|
||
## Key Changes
|
||
|
||
- 新增数据产品状态/统计层：
|
||
- 每个产品维护全量统计：总实体数、活跃数、最近更新时间、使用源、缺失源、冲突数、构建状态。
|
||
- 统计在采集成功或产品投影完成后更新，不在用户打开页面时临时全表聚合。
|
||
- 前端聚合面板统一读取产品统计接口，而不是从图层返回量推断总数。
|
||
- 新增接口：
|
||
- `GET /api/v1/data-products`
|
||
- `GET /api/v1/data-products/{product_id}/status`
|
||
- `GET /api/v1/layers/{product}/...`
|
||
- `POST /api/v1/datasources/trigger-batch`
|
||
- `/layers/*` 只负责可视化数据：
|
||
- 支持 bbox、zoom、limit、since。
|
||
- 可以返回 `degraded`、`truncated`、`cache_hit`。
|
||
- 返回 `visible_count` 和 `returned_count`，但不作为全量统计来源。
|
||
- `/data-products/*/status` 负责全量统计：
|
||
- 返回 `total_count`、`active_count`、`source_counts`、`last_built_at`、`health`。
|
||
- 数据来自预计算状态或轻量索引统计。
|
||
- 即使图层降级，统计也保持全量口径。
|
||
|
||
## Product Processing
|
||
|
||
- 船只：
|
||
- 图层：bbox snapshot + WS 聚合流，受限返回。
|
||
- 统计：全量唯一 MMSI、最近窗口活跃 MMSI、AISStream/BarentsWatch/source counts。
|
||
- 海缆：
|
||
- 图层：viewport 内 cable segments/landing points，低 zoom 可简化路线。
|
||
- 统计：全量 cable count、landing point count、relation count、graph 构建状态。
|
||
- 处理：专用 cable graph assembler，区分路线源、登陆点源、关系源、补充源，不使用统一字段融合函数。
|
||
- BGP：
|
||
- 图层：active incidents/anomalies/collectors，按窗口和 limit 返回。
|
||
- 统计：全量活跃事件、最近 24h/7d 事件数、collector 数、incident/anomaly 分布。
|
||
- 处理：专用事件流水线，区分 observation、anomaly、incident、geo hint、infrastructure inference。
|
||
- 卫星：
|
||
- 图层：可见卫星或受控 limit。
|
||
- 统计：全量卫星数、最新 TLE epoch、源覆盖情况。
|
||
- 处理：按 NORAD id 生成轨道快照，TLE epoch 最新优先。
|
||
|
||
## Data Source Page
|
||
|
||
- 增加筛选：
|
||
- 产品类型、启用/禁用、最近成功/失败/运行中/未执行、已采集/未采集、凭证状态、文本搜索。
|
||
- 增加复选框批量操作：
|
||
- 批量启用、禁用、采集、强制采集。
|
||
- 一键采集改为：采集全部启用源、采集筛选结果、采集选中源。
|
||
- 后端 batch 逻辑：
|
||
- 禁用源 skipped。
|
||
- 运行中源按 force 处理。
|
||
- 单个失败不影响其他源。
|
||
- 返回 `triggered`、`skipped`、`failed`，并包含每个 source 的原因和 task_id。
|
||
|
||
## Protection Rules
|
||
|
||
- 所有 `/layers/*` 接口必须有保护层：
|
||
- limit clamp。
|
||
- bbox/zoom 校验。
|
||
- 低 zoom 降级。
|
||
- 短 TTL 缓存。
|
||
- 慢查询超时。
|
||
- diagnostics 返回降级原因。
|
||
- 全量统计不走图层查询：
|
||
- 不允许为了面板统计在请求时 `.all()` 全量加载。
|
||
- 统计由采集/投影任务异步更新。
|
||
- 统计缺失时返回 `unknown` 或 `stale`，不触发重型实时计算。
|
||
- 缓存失效规则：
|
||
- 采集成功后失效对应产品缓存。
|
||
- 海缆 graph cache 在路线、登陆点或关系源成功采集后失效。
|
||
- BGP incident/anomaly 生成后失效 BGP layer cache。
|
||
- 船只实时流使用短 TTL 或 viewport 级缓存，不清全局缓存。
|
||
- 接口观测：
|
||
- 记录每个 layer endpoint 的耗时、返回数量、是否降级、是否缓存命中、limit 是否被 clamp。
|
||
- 对高频 viewport 请求增加简单 per-IP 或 per-user rate limit。
|
||
|
||
## Frontend UX
|
||
|
||
- 数据源页：
|
||
- 顶部统计可作为快捷筛选入口：全部、启用、禁用、运行中、失败、未采集。
|
||
- 表格左侧增加复选框。
|
||
- 工具栏显示“已选择 N 个”，并提供批量按钮。
|
||
- 筛选结果和选中结果分清楚，避免误触发全部源。
|
||
- 批量采集完成后弹出摘要：触发、跳过、失败数量，可展开查看原因。
|
||
- 设置/配置页：
|
||
- “采集器设置”改为“数据产品配置”。
|
||
- 产品内按源角色分组展示，而不是简单列出 collector。
|
||
- 海缆显示路线源、登陆点源、关系源、补充源。
|
||
- BGP 显示实时观测源、历史回填源、地理 hint 源、检测输出。
|
||
- 船只显示实时 AIS、轮询 AIS、自定义补充源。
|
||
- Earth 图层交互：
|
||
- 聚合面板统计读取 `/data-products/*/status`，保持全量口径。
|
||
- 图层面板展示当前图层是否降级、截断、缓存命中。
|
||
- 对象详情展示来源证据：
|
||
- 船只：字段来源、冲突。
|
||
- 海缆：路线源、登陆点源、关系源。
|
||
- BGP：事件证据、分组依据、地理推断依据。
|
||
- 产品 degraded 时仍显示可用部分，并提示缺失源角色。
|
||
|
||
## Test Plan
|
||
|
||
- 图层接口：
|
||
- 大 limit 被 clamp。
|
||
- 低 zoom 降级。
|
||
- 大数据集不全量内存过滤。
|
||
- diagnostics 正确说明截断、缓存、降级。
|
||
- 全量统计：
|
||
- 面板统计不受 bbox 影响。
|
||
- 图层返回 1000 条时，产品统计仍显示全量总数。
|
||
- 统计陈旧时返回 `stale=true` 和 `last_built_at`。
|
||
- 采集成功后对应产品统计刷新。
|
||
- 数据源批量：
|
||
- 筛选、选中、批量采集行为正确。
|
||
- skipped/failed/triggered 分组正确。
|
||
- 禁用源在 batch 中被 skipped。
|
||
- 运行中源按 force 参数处理。
|
||
- batch 单源失败不阻断整体。
|
||
- 产品处理：
|
||
- 海缆缺 relation 时产品状态 degraded，但 cable layer 可用。
|
||
- BGP observation 不直接变成前端 marker，必须经过 anomaly/incident 投影。
|
||
- 船只 bbox snapshot 和 WS 节流继续有效。
|
||
- 卫星列表不返回无限轨道点。
|
||
|
||
## Assumptions
|
||
|
||
- 前端聚合面板以后只读 `/data-products/*/status`。
|
||
- 地图图层只读 `/layers/*`。
|
||
- 统计可以短暂 stale，但不能因实时全量统计击穿服务器。
|
||
- 保留现有 collector，不为了重构而删除 BarentsWatch 或其他源。
|
||
- 当前开发阶段允许前端从旧 `/visualization/geo/*` 迁移到 `/layers/*`。
|