[文档] 同步 v3 运动事件驱动架构 - 整段素材分割运动片段再分析(不再整段送云端): README 1.1/2.2/2.2.1/2.3/模块表, PROGRESS 运行状态+变更记录; 记录 systemd 守护部署方式

PROGRESS.md

@@ -1,15 +1,27 @@
 # 项目进度追踪
 
-> 最后更新: 2026-08-22 11:08
+> 最后更新: 2026-08-22 12:45
 
 ## 服务运行状态
 
 | 服务 | 节点 | 地址 | 状态 | 验证结果 |
 |------|------|------|------|---------|
-| FAM-Core | NAS | 0.0.0.0:8000 | ✅ 运行中 | health=ok, gunicorn 单 worker；Oracle-Sync + 运动监测 Webhook（轮询已关闭，SS→NAS→Oracle 推送） |
-| FAM-Edge | Oracle | 0.0.0.0:5000 | ✅ 运行中 | v2.0, SQLite 异步队列 + 消费者线程 + TokenBucket 速率限制 |
+| FAM-Core | NAS | 0.0.0.0:8000 | ✅ 运行中 | health=ok, gunicorn 单 worker；Oracle-Sync + MotionNotifier 轮询 SS 事件推送（游标 DB 续用/失败重试） |
+| FAM-Edge | Oracle | 0.0.0.0:5000 | ✅ 运行中 | systemd 守护（fam-edge.service）；素材→运动片段分割→只分析片段；队列消费正常 |
 | MariaDB | NAS | 127.0.0.1:3306 | ✅ 运行中 | 10.11.11, 6 张表, utf8mb4 |
 | Ollama | Oracle | 127.0.0.1:11434 | ✅ 运行中 | qwen2.5:7b，仅智能问答兜底（不参与视觉/融合） |
+
+## 2026-08-22 运动事件驱动架构（v3）
+
+- **决策**：不再分析整段视频。rclone 整段素材保留在 Oracle，按 NAS 推送的 `ss_motion_events`（start_time/duration）**ffmpeg 分割成运动片段**，只分析片段。
+- **改动**（commit `a1523b4` + `8d6cfad`，已部署 Oracle systemd 重启）：
+  - `oracle_db.py`：videos 表兼容加 `motion_event_id`/`camera_id` 列；新增 `get_motion_events_in_range`（窗口内已结束事件，grace 容差）/`has_unfinished_motion_in_range`/`get_video_by_motion_event_id`
+  - `video_processor.py`：素材→分割（只分割已结束事件，`-c:v copy -c:a aac` 保留音频，motion_event_id 幂等）/片段→只分析 双分支；修复 ffmpeg args 缺可执行文件 bug
+  - `video_queue.py`：素材分割出的片段入队
+  - `config.yaml`：新增 `motion_segment` 块（clips_dir/keep_audio/min_duration/unfinished_grace_sec）
+- **E2E 验证（真机）**：素材 `Generic_ONVIF-001-20260822-110859-...mp4` → 分割 35 段（真实 event_id 25504-25538、duration 1-132s）→ 片段只分析（summary 真实：人物/动作）→ events（绝对时间 ts）→ NAS 同步 → `/api/ui/videos` 显示 motion_ 片段（字段契约不变：filename/event_start_time/camera_name/event_count/summary_json/compute_provider）→ `/api/ui/videos/<id>` 详情 events + people 正常 → `/api/proxy/frame` 帧图 200 OK
+- **关键认知**：SS 事件 duration=0 仅在动作**进行中**（结束时必为正数，实测 id=25538 从 0→2s），故只分割已结束事件（start+duration ≤ now+grace），进行中的等下一轮。
+- **部署注意**：Oracle fam-edge 由 **systemd `fam-edge.service` 守护**（Restart=always），代码部署后必须 `sudo systemctl restart fam-edge`（手动 setsid 会与守护打架导致端口冲突）。
 | Tailscale | Oracle ↔ NAS | 100.74 ↔ 100.70 | ⚠️ 待修复 | Tailscale 运行但端口不通，当前用公网IP |
 | FAM-UI | NAS | 0.0.0.0:8501 | ✅ 运行中 | Streamlit 1.61.1, HTTP 200, health=ok |