研学 + 教育 · API 对接（骨架）

核心接口

• GET /api/v1/tour/study/subjects
  获取学科列表
• GET /api/v1/tour/study/knowledge-points
  按学科/学段/版本获取知识点
• GET /api/v1/tour/study/paths
  按景区/学段/主题/时长获取研学路线
• GET /api/v1/tour/study/paths/{id}
  获取路线详情（含 POI 顺序）
• POST /api/v1/tour/study/progress/events
  事件流回传（幂等）
• GET /api/v1/tour/study/progress/summary
  用户视角汇总
• POST /api/v1/tour/study/reflections
  复盘提交

复用接口

• /api/v1/explain/*
  个性化讲解，研学任务可把“讲解完成/互动问答”作为完成条件
• /api/v1/vision/*
  拍照识别，用于研学中的观察任务

事件流回传

POST /api/v1/tour/study/progress/events

{
  "idempotency_key": "uuid",
  "occurred_at": "2026-04-10T12:00:00Z",
  "event_type": "CHECKIN|LEARN|UPLOAD|REFLECTION",
  "path_id": 1001,
  "poi_id": 101,
  "payload": { "note": "..." }
}
          

幂等设计

• 服务端按 idempotency_key 去重
• 客户端生成唯一 UUID 作为幂等键
• 支持批量回传，减少网络请求
• 回传失败时自动重试，网络恢复后继续

离线缓存策略

• 端上使用本地存储缓存事件流
• 网络恢复后自动触发补传
• 补传成功后清理本地缓存
• 定期检查未补传的事件