# 数据产品流水线、数据源批量运维与抗击穿图层接口计划

## 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/*`。