# sentinel-home-ai 项目长期记忆

## 项目概况
- 家庭多模态智能监控系统，仓库 `http://192.168.50.64:3000/ericwyuan/sentinel-home-ai`（Gitea 内网）
- 本地 `/Users/ericwyuan/Desktop/Work/sentinel-home-ai`（monorepo：fam-core NAS 端 + fam-edge Oracle 端 + fam-ui Vue3 前端）

## 架构 v3（2026-08-22 定稿：运动事件驱动）
- **不再分析整段视频**。Google Drive --rclone--> Oracle gdrive_videos（整段素材保留）；
  Oracle 按 NAS 推送的 `ss_motion_events`（start_time/duration，Unix epoch）ffmpeg 分割运动片段
  （`-c:v copy -c:a aac` 保留音频，产物 `/opt/fam-edge/motion_clips/`），**只分析运动片段**。
- **Drive 中转是跨境提速设计（非仅 NAT 原因）**：中国→海外裸 HTTP/SCP 直传 Oracle 很难（跨境单 TCP 流
  丢包掉速）；改走 Google（CloudSync 分块并发 + 断点续传，抗抖动）→ Oracle rclone 每 5min 拉取
  （海外数据中心互联，Gbps）。**不要轻易提议砍掉 Drive 改 NAS 直连 Oracle**。
- NAS MotionNotifier 轮询 SS `EventCenter.Event.List`（60s，camera_ids=2, event_types=10）推送
  /api/ss/motion；游标 MariaDB 续用 + 失败批次不前进 + 心跳。Webhook 端点保留为可选补充。
- **SS duration=0 = 动作进行中**（结束才回填真实时长），分割只处理已结束事件。
- 前端（fam-ui Vue3）不改：/api/ui/videos|stats|people|attention-events|... 契约保持；
  事件帧图 /api/proxy/frame 用绝对 ts − event_start_time 偏移取帧，运动片段天然兼容。

## 服务器与部署
- NAS (192.168.50.64)：SSH 2222, ericwyuan/iLoveJava5；fam-core 代码 `/volume1/web/sentinel-home-ai`，
  venv `fam-core/venv`，`start_core.sh` source .env；重启 = kill gunicorn + `setsid bash start_core.sh`
  （NAS 无 systemd 守护）。
- **Oracle（云服务器 129.146.26.249）**：SSH key `~/.ssh/oracle_new`；fam-edge 由 **systemd
  `fam-edge.service` 守护（Restart=always）**——部署代码后必须 `sudo systemctl restart fam-edge`，
  手动 setsid 会端口冲突；venv `/opt/fam-edge/venv`；库 `/opt/fam-edge/data/oracle.db`；
  素材 `/opt/fam-edge/gdrive_videos`；logs 目录 ubuntu 可写。
  **前端亦托管于此机 Caddy :80**（fam-ui SPA + /api 反代回 NAS fam-core :8000 经 frp 隧道）；旧机 129.146.203.203 已退役。
- **登录（2026-08-31 起）**：fam-core 不再自己校验密码，登录全权走 auth-hub 统一登录
  （OAuth2 Auth Code + PKCE / OIDC，`http://129.146.26.249:5300`）。fam-core client
  `a2PJTZuKQYxt1oGh`，回调 `:8000/api/auth/callback`（auth-hub 侧注册了 :80 和 :8000 两个回调）。
  NAS `.env` 配 `AUTH_HUB_ISSUER/CLIENT_ID/CLIENT_SECRET/REDIRECT_URI`（缺任一 fail closed）。
  账号：`ericwyuan / iLoveJava5`（hub 端）。NAS venv 需 PyJWT + cryptography（RS256 验签）。
- 部署：本地 git 提交 push Gitea → tar 管道（NAS 直接解包；Oracle `--strip-components=1` 到临时目录再 cp，避免动 data/venv）。
- **NAS 部署坑（2026-08-29 踩过）**：拷贝 `.py` 会带旧 mtime，若 `.pyc` 比 `.py` 新，Python 加载陈旧字节码
  （旧逻辑上线，曾导致 1062 假象）。部署后必须 `find src -name __pycache__ -exec rm -rf {} +` 再重启；
  `pkill -f` 会匹配 SSH 自身命令导致断连（用 PID 文件或精确 pattern）。
- **镜像表键设计（2026-08-29 定稿）**：`sync_identity_map` 不再以 Oracle `person_identity_map.id` 作主键
  （Oracle 库重建会复用 id），改 NAS 本地自增 `id` + 唯一键 `(video_id, raw_uid)`，Oracle id 落 `oracle_id` 列溯源；
  同批 upsert 的 UPDATE 子句不改写键列，避免 uq 二次冲突 1062。sync_videos/events/model_calls 同理（风险低未改）。

## 提交规范（强制）
- 格式 `[阶段X.Y子任务号] 子任务名称 - 完成内容简述`；Bug 修复 `fix(模块): 问题简述`
- 一任务一 commit；开工先 `git pull --rebase`；阻塞先 commit 加 `[WIP]`
- 禁止 `git push --force` 和 `--no-verify`