docs: 同步事件时间轴删除视频功能到 README/PROGRESS

补充 §5.1/§5.2 新增的 POST /api/oracle/video/delete + DELETE /api/ui/videos/<id>
端点说明、FAM-UI 页面表格、§12 当前进度;PROGRESS.md 记录完整变更 + 端到端
验证过程。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ericwyuan
2026-08-24 04:28:55 +08:00
parent 28397e9e6a
commit 3cb08c9749
2 changed files with 20 additions and 6 deletions

View File

@@ -3,7 +3,7 @@
> 多模型容灾降级 + 交互式命名 + AI 对话的家庭监控系统。
> 本文档为项目需求文档与 README 的整合版按当前代码实际状态v1.0 E2E 已打通)编写。
> 最后更新2026-08-23问答链路抽离为独立 ai-gateway 服务FAM-Edge 不再自己维护问答模型降级链,改为转发调用
> 最后更新2026-08-24事件时间轴支持删除视频会话
---
@@ -202,7 +202,7 @@ Vue3 + Vite + Tailwind SPA`fam-ui/src/views/*.vue`,构建产物 `fam-ui/dis
| 页面 | 功能 |
|------|------|
| 🕒 事件时间轴 | 运动片段会话列表(`motion_*.mp4`,只显示有内容的会话)+ 选中会话的事件时间线(时间点 + 描述 + 人物/关注徽章 + 事件帧图);支持 `?video=<id>` 定位跳转 |
| 🕒 事件时间轴 | 运动片段会话列表(`motion_*.mp4`,只显示有内容的会话)+ 选中会话的事件时间线(时间点 + 描述 + 人物/关注徽章 + 事件帧图);支持 `?video=<id>` 定位跳转;详情卡片支持**删除会话**(原生 `confirm()` 二次确认2026-08-24 新增) |
| 👤 人物管理 | 按规范名/标签聚合,命名/合并(回推 Oracle**人物卡含「运动片段」区块**(该人物出现过的运动片段:缩略图/时间/摘要/事件数,点击跳时间轴) |
| 💬 AI 对话 | 输入框 + 调 `/api/chat/ask`;按 queried_person 预设快捷提问 |
| 📝 对话历史 | chat_history 倒序展示 |
@@ -306,6 +306,7 @@ chat_history 独立表(问答上下文摘要留存)
- 401token 校验失败
**POST /api/oracle/people/correct** — 命名校正回推:`{"label":"人物A","canonical_name":"汤圆","token":...}`manual 优先,不被 LLM 覆盖)→ `{"status":"ok"}`
**POST /api/oracle/video/delete**2026-08-24 新增)— 删除视频会话NAS 转发):`{"video_id":123,"token":...}` → 删 `events`+`videos` 行 + 磁盘上的运动片段文件 → `{"status":"ok","video_id":123}`**不清理**对应的 `ss_motion_events` 源事件那是硬件推送的原始事件记录跟切出来的片段生命周期独立素材一旦处理完就不会被生产者重新捡起删片段不会触发重新分割video_id 不存在返回 404
**POST /api/edge/chat/ask(/stream)** — 智能问答FAM-Core Chat-Handler 调用):请求 `{"prompt","max_tokens"}` → 响应 `{"answer","provider"}`(流式版为 SSE事件 `provider_trying`/`chunk`/`done`/`all_failed`**2026-08-23 起 FAM-Edge 自己不跑模型,转发到同机 AI-Gateway `/v1/chat/completions`**,内部按 NVIDIA → Gemini → 本地 Ollama 顺序降级(对 FAM-Core 不可见,接口契约不变)
**POST /api/ss/motion** — 运动事件接收NAS MotionNotifier 推送):`{"token", "events":[{event_id, camera_id, event_type, start_time, duration, thumbnail_url}]}` → 幂等落库 `ss_motion_events` + 刷新心跳;`events: []` 空数组即心跳
**GET /api/oracle/frame** — 事件帧图:`?video_id=&ts=&w=` → jpeg`ts` 为绝对时间,`frame_service``ts event_start_time` 偏移从视频文件取帧)
@@ -331,6 +332,7 @@ chat_history 独立表(问答上下文摘要留存)
| `/api/ss/status` | GET | 运动监测状态:`poll_enabled` / `camera_loaded` / `camera_map` / `pushed_total` / `last_error` / 心跳 |
| `/api/ui/videos` | GET | 运动片段会话列表(`?date=&page=`**只返回 `motion_` 前缀或有事件的会话**0 段素材不展示) |
| `/api/ui/videos/<id>` | GET | 会话详情:`{video, events[]}`(事件含 person_list_json / person_appearances_json / is_attention_event |
| `/api/ui/videos/<id>` | DELETE | **2026-08-24 新增)**删除会话:先回推 Oracle 物理删除(含磁盘文件),成功后清本地镜像(`sync_events`+`sync_videos`增量同步感知不到删除必须显式清理Oracle 回推失败返回 502不改本地状态 |
| `/api/ui/stats` | GET | 统计卡videos / events / people / attention`?date=` 过滤,口径与列表一致) |
| `/api/ui/people` | GET | 人物列表(按 canonical_name 聚合display / labels / appearances / first_seen / features_json / display_uid |
| `/api/ui/people/clips` | GET | 人物运动片段:`?label=&limit=` → 该人物出现过的运动片段video_id / event_start_time / duration / summary / first_ts 缩略图定位 / clip_events |
@@ -827,8 +829,9 @@ export NVIDIA_API_KEY="nvapi-9cFAdO5xdbwPuxS8KGRTnlVimn1gJzbbbzWNhPwHa_Yl3pTe-Pf
## 12. 当前进度与 v1.1 计划
### 已完成(截至 2026-08-23
### 已完成(截至 2026-08-24
- **事件时间轴支持删除视频会话**2026-08-24三端联动沿用"NAS 转发写请求到 Oracle"的既有模式(新增 `POST /api/oracle/video/delete` + `DELETE /api/ui/videos/<id>`);删 events+videos 行 + 磁盘文件,不清理 `ss_motion_events` 源事件;`db_layer.delete_sync_video()` 是项目里第一个"NAS 直接写自己镜像表"的函数(增量同步机制感知不到删除,不能靠 `trigger_now()` 拉增量清理)
- **问答链路抽离为独立 ai-gateway 服务**2026-08-23FAM-Edge 原本自己维护的问答模型降级链NVIDIA→Gemini→Ollama含 key 轮换/熔断)整个搬到独立仓库/独立部署单元 `ai-gateway`OpenAI 兼容协议 `/v1/chat/completions`Bearer token 鉴权,对外 `:5100`FAM-Edge `qa.py` 重写为转发客户端,`/api/edge/chat/ask(/stream)` 对 FAM-Core 的契约不变;`OllamaAdapter` 从 FAM-Edge 删除
- **运动事件驱动**v32026-08-22不再分析整段视频。NAS MotionNotifier 轮询 SS 事件列表60s游标续用/失败重试/心跳)推送 `ss_motion_events`Oracle 整段素材按运动事件 ffmpeg 分割运动片段(`-c:v copy -c:a aac`,只分割已结束事件,`motion_event_id` 幂等),**只分析运动片段**;前端契约不变
- **数据迁移**2026-08-22整段提取的旧数据Oracle videos/events/people + NAS 镜像已清空并按运动视频重新提取历史素材NAS 轮询启动前)无运动事件,时间轴已过滤其空会话