ucvl-home-vision/README.md

# 赵府智家 · 视觉系统

## v0.1.35 · Vue、Bootstrap 与设备网络状态

前端采用 Vue 3 + Vite + Bootstrap 5，家庭卡片、设备目录与网络拓扑组件化，提供桌面及手机布局。GL.iNet 等路由器显示服务器探测状态、Tailscale 节点与子网路由状态，并提供管理后台跳转。权限仍以家庭／场所隔离。

详见 [本次发布](RELEASE-v0.1.35.md) 与 [前端构建和模块边界](frontend/README.md)。复杂视频、家谱、记事控制器暂通过兼容层保留；生产主机直接使用已提交的构建产物，无需安装 Node。

## v0.1.32 · 真实网盘验收与保存反馈

- 修复家庭档案已保存、后续列表刷新失败时提示不可见的问题；立即提示保存结果，刷新失败单独提示，无需重复提交。
- 网盘设置中展示封面、平台外观、个人记事、数据库备份四类存储说明；修正“全部本地存储”的旧文案。
- 异常国家编码类型统一返回字段校验错误，不再触发服务器异常，失败保留原档案。
- 真实百度网盘验收：在应用内“验收资料”目录上传 100867 字节合成图片，清空进程缓存后读回校验一致；重复上传返回相同文件 ID。正式家庭的已上传封面也通过独立回读及浏览器刷新、重新打开验证。验收不修改正式家庭档案。
- 手机宽度检查覆盖已上传封面与编辑对话框。自动文件选择器仍受 Edge 扩展文件 URL 权限限制，不将接口上传或用户自行上传等同为自动选文件验收。

验证：150 项 Python、120 项 JavaScript 回归通过。真实网盘和正式封面回读校验通过；360px 网盘说明、390px 封面及对话框无横向溢出。上线前备份数据库，发布源码后部署。

## v0.1.31 · 地域分级选择与网盘图片

- 家庭／场所、空间和家谱籍贯／出生地共用地域控件：中国省市区联动、世界国家／地区选择、自定义历史地名或其他天体。更换上级清空下级；服务端以编码校验父子关系。旧地名无法匹配时原样保留为自定义，权限仍按家庭／场所划分。
- 离线内置中国 2023-06-30 区划快照，来源 [Administrative-divisions-of-China](https://github.com/modood/Administrative-divisions-of-China)，该项目不再更新。港澳台下级及新设区划可手填或自定义；世界下级行政区不声称完整收录。国家／地区名称来源 [Unicode CLDR](https://github.com/unicode-org/cldr-json)，许可证随数据打包于 web/data/GEOGRAPHY-LICENSES.txt。
- 封面支持 30 MiB 内、8000 万像素内的 PNG/JPEG/WebP 原图，由浏览器缩小至最长 960px、至多 600 KiB 后上传。读取失败阻止保存；服务端确认网盘上传并回读校验后才保存引用。保存失败保持原档案，再次打开按持久化引用加载。
- 所有新选择的封面、Logo、图标存百度网盘。数据库只保存 provider/fsId/remotePath/size/sha256；短时图片缓存仅在内存，最多 16 MiB、10 分钟。文字、人员与家庭权限仍由本系统管理；图片地址经鉴权代理，不暴露网盘凭据。默认内置标识仍是程序资源。
- 网盘分类：`家庭与场所/<实例>/<家庭>/封面`、`平台外观/<实例>/platform/Logo或图标`、`个人记事/<实例>/<家庭>/<用户>/照片或视频或语音`。数据库备份保留原独立目录与一个自然月云端保留策略。旧记事附件链接继续有效，不移动或删除云端原文件。
- 支持显式迁移旧封面和品牌图；每张上传回读校验成功后才移除数据库中的内嵌图片。已产生的历史数据库备份按原保留策略自然过期。外观导出保留文字与版式，已上传网盘图片不嵌入导出文件。

验证：148 项 Python、116 项 JavaScript 回归通过。Edge 实测中国联动清空、世界地址保存与回填、自定义火星路径、390px 对话框无横向溢出、接口上传后刷新重开封面。自动文件选择受 Edge 扩展“允许访问文件 URL”权限限制；大图读取/压缩与失败阻止保存由单元测试覆盖，图片上传回读由接口测试覆盖，不将这些测试混同为真实文件选择器上传成功。

## v0.1.30 · 日常操作流程与手机网页

- 家庭或办公、工厂是权限归属；内部区域可分多级。设备提供按区域、类型、负责人三个快捷视图，并保留自定义组合。搜索支持“卧室 灯”等多词组合，涵盖区域、品牌、人员与标签。
- 总览补充记事入口；区域管理收进设备页；设备返回列表，家谱与家族记事返回家庭传承。区分个人日常记事与家族重大记事，办公场所不显示家族传承。
- 修复编辑后新建残留隐藏记录编号的问题。新建区域可选择新增下级，设备和录像机继承当前选中的区域。
- 记事保存后清空本次输入、附件和旧筛选，重新加载并定位保存结果。补记往事也可定位到对应分页；空页自动回到有效页。保存中锁定表单，失败保留草稿；另写、退出或切换家庭前提示未保存输入。
- 设置中心分为我的偏好、网盘连接、品牌与外观、数据库备份，后三项仅超级管理员可配置。录像机原有历史录像明确标注待接入，避免查询后才发现不可用。
- 手机使用可展开的顶部菜单，选择页面后自动收起。表单单列、输入字号 16px、按钮至少 44px；修复设备弹窗、媒体预览和筛选操作在窄屏的布局。

验证：138 项 Python 回归、109 项 JavaScript 回归。通过 Edge Computer Use 验证管理员和普通成员、设备查找与编辑后新建、记事保存清空与定位、照片预览和语音播放、草稿取消清空、设置分区、办公场所切换。响应式检查覆盖 360、390、430、768px；手机浏览器引擎、软键盘和真机录音仍需 Android/iOS 实机复核。流程测试使用独立的本地合成数据，未向正式家庭写入测试记事或设备。

范围：灯、冰箱等仍是设备档案，自动控制需接入实际协议；录像机原有历史录像接口仍待接入。浏览器预览测试不能替代长时间监控稳定性或设备全部厂商功能的验证。

## v0.1.29 · 记事预览、完整地域与云备份保留

- 记事照片默认显示，点击放大；语音、视频自动加载播放信息，提供播放、暂停、进度和音量控制，不自动出声。页面原生播放器按需缓冲，图片延迟解码；媒体仍保存在百度网盘，由同源鉴权接口转发，服务器不保存个人媒体文件。
- 本次附件采用卡片，支持预览、从本条移除、删除和恢复。附件库默认折叠。保存成功清空文字与本次附件、结束录音，再读取下方个人阅历；失败则保留草稿。附件库删除是可恢复的整理操作，保留已发布引用与网盘原文件；彻底删除云文件仍由用户在网盘管理。
- 籍贯（祖籍）与出生地分别支持国家、省、地级市、区县、乡镇街道、村社区、详细地址及历史地名。层级可留空，原有地域文本保留，搜索和修改记录涵盖新字段；升级不会猜测或覆盖已有地址。
- 百度数据库备份保留最近 **一个自然月**（北京时间，以备份文件时间为准，月末按上月最后一天处理）。上传成功后流式读回校验 SHA-256，再清理本应用、当前实例目录下的过期 SQLite 文件；最新副本、其他实例和个人媒体不参与清理。上传或校验失败不清理旧云备份，清理失败单独报告，可在下次备份重试。新备份使用应用目录下的 `数据库备份/实例/文件.sqlite`，兼容旧版多一级同名目录的文件。
- 本机和挂载目录仍按设置中的份数保留；每日自动备份开关与时间保持用户原设置。不会自动清空百度回收站。云备份是完整数据库，含所有家庭数据及设备配置；私有 OAuth 凭据文件不在其中。

验证：136 项 Python 回归、98 项 JavaScript 回归；浏览器验收包括默认照片与音视频控件、预览与 Esc、附件删除恢复、保存后草稿清空及地域分别保存。接口依据：[百度官方 SDK 文件管理](https://github.com/baidu-netdisk/baidu-drive-sdk-go/blob/main/baidudriver/api/file_manager.go)、[目录分页](https://github.com/baidu-netdisk/baidu-drive-sdk-go/blob/main/baidudriver/api/file_list.go)。

## v0.1.28 · 个人记事与百度网盘

- 场所内新增「记事与阅历」。文字、日期、分类、作者、可见范围、点赞和评论存于本机数据库，同一条记事可从动态或个人阅历查询。支持关键词、人物、分类及日期筛选，每页 20 条。默认仅自己可见，选择「当前家庭／场所」才会共享；其他家庭不可查看，超级管理员的普通记事 API 也不越过他人的私密范围。
- 支持照片、视频、音频附件和浏览器直接录音。每条最多 9 个附件，单文件上限 256 MiB，录音最多 5 分钟；录音需要 HTTPS 与用户的麦克风授权。只上传原始媒体，不进行服务端转码或语音识别；实际播放还取决于浏览器编码支持。
- **一个后台百度网盘账号统一存放媒体**，应用账号与网盘账号分别管理。用户权限通过本平台的家庭归属和记事可见范围检查。该网盘账号持有人可以直接管理网盘中的全部文件。开发者应用的个人场景限制以百度后台为准。
- 个人记事的媒体不写入服务器磁盘。浏览器逐个计算 4 MiB 分片 MD5，以 512 KiB 请求发送；服务器最多保留两个 4 MiB 中转缓冲，转发至百度预上传／分片上传／创建文件接口。中断后选择同一原文件，重新读取云端缺失分片继续。数据库仅保存附件归属、名称、大小、校验值、网盘路径和文件 ID 等元数据，不保存媒体内容或永久公开分享链接。
- 展示时逐次检查记事访问权限，再获取临时下载地址并同源转发。照片和音视频的加载交互已在 v0.1.29 更新，浏览器负责展示与缓冲。退出、离开记事页或切换家庭会释放页面媒体资源。不使用服务端文件缓存、Service Worker 离线缓存或浏览器本地存储保存附件。删除记事／移除引用不删除网盘原文件；云端整理在百度网盘进行。
- 设置中心由超级管理员填写 AppKey、SecretKey、百度后台应用名称及 `https://你的域名/api/baidu/callback`。回调地址须在百度开发者后台登记且完全一致；通过这个 HTTPS 域名登录后发起授权。SignKey 不用于当前 OAuth 接入。授权 state 一次性、10 分钟有效，并绑定原登录会话与浏览器 HttpOnly/Lax 回调 Cookie；原账号退出、停用或降权后不可完成授权。重新连接须使用原网盘账号，避免已有附件失联。
- AppKey、SecretKey 和网盘令牌保存在 `VISION_DATA/baidu-secrets.json`，权限 0600；不进入 Git、品牌配置导出或数据库备份。主机管理员能读取该文件。数据库恢复后需要重新配置并授权原网盘；请单独安全保管开发者凭据。授权失败不会使本系统账号退出登录。
- 数据库备份可独立勾选「同时上传到百度网盘」，默认关闭。本机 SQLite 一致性副本校验后上传，界面分别报告本机、网络目录和百度网盘结果。数据库备份包含各家庭的业务数据和设备连接配置，因此仅超级管理员可操作；不含个人媒体原文件。云端保留规则已在 v0.1.29 更新，本机保留份数只作用于本机和挂载目录。
- 稳定性：家庭档案使用独立修订号防止相互覆盖；Logo、图标及封面采用最新图片任务校验，取消或重新选择后旧解码结果不会覆盖新选择；备份配置读取失败也会释放执行状态。

升级会新增 `journal_entries`、`journal_media`、`journal_comments` 和 `journal_likes` 表，现有设备、家谱和家庭数据保持原样。当前版本的「个人阅历」以系统账号为人物主体，尚未提供导入网盘已有文件、自动关联祖先人物、分享链接或语音转文字。自定义品牌小图及家庭封面仍沿用原有外观配置，新的记事附件全部使用上述云端流程。

回归验证增加 `python3 -m unittest -q test_journal` 与 `node --test test_journal.js`，应和原有完整测试集一起执行。接口参考：[百度 OAuth](https://pan.baidu.com/union/doc/al0rwqzzl)、[上传](https://pan.baidu.com/union/doc/3ksg0s9ye)、[下载](https://pan.baidu.com/union/doc/pkuo3snyp)及[百度网盘官方 Go SDK](https://github.com/baidu-netdisk/baidu-drive-sdk-go)。真实上传、播放和云端备份仍须在合法网盘授权后验收；模拟接口测试不能代替真实平台验收。

运行在自有小电脑上的视频管理程序。Python 标准库负责对象、空间、配置与登录；MediaMTX 负责 RTSP 接入、HLS 实时预览、本机录像及回放；浏览器使用本地打包的 hls.js。

## 界面风格

v0.1.22 采用「庭院书卷」视觉：宣纸白底、黛青导航、朱砂点缀与淡金本人标记。统一实时监控、家谱树、家族记事、设备档案、表单和登录界面；全屏监控保留深色背景。样式集中在 `web/chinese-theme.css`，本地系统宋体用于标题，不请求外部字体。桌面和手机使用同一套功能与自适应布局。

## 对象与空间

- **区域与空间**：各家庭、办公场所、工厂独立设置区域树，自定义名称、类别与上级区域，不设固定层数。地址可记录省、市、区县、街道、小区或园区、楼栋、单元、楼层、门牌。
- **统一设备管理**：摄像机、录像机与其他设备统一展示，支持按类型、区域、负责人、所有人、自定义标签调整分组顺序。灯、手机、冰箱等当前提供档案登记，实际控制需要另行接入协议。
- **摄像头对象**：实体设备的稳定 ID、品牌、型号、序列号、镜头数、安装位置和空间引用。
- **镜头通道**：每个物理镜头一个通道，关联摄像头对象，配置主、子码流。双镜头摄像头的主、子码流不能当作两个物理镜头。
- **录像机**：独立的设备与凭据档案，通道可以引用录像机获取画面。也可以直接连接摄像头。
- **录像来源**：明确区分录像机原有录像与小电脑新保存的录像。

## 当前功能与边界

源码包括空间 / 摄像头 / 录像机 / 镜头档案，局域网 RTSP 探测、ONVIF 设备信息与独立镜头媒体配置读取、同源 HLS 播放、本机可选持续录像、日期查询、录像时间轴、定位回放和片段下载、存储保护、管理员初始化与登录。

**录像机原有历史录像回放尚未实现。** 需要取得具体型号及合法设备账号，接入其录像检索和回放接口；实时 RTSP 地址不能代替录像检索接口。驱动选项目前仅表示路径模板与接入类型，不能视为某个品牌全系列已经兼容。实际通道号需要由设备确认，不能根据三台双镜头直接猜成通道 1–6。

本机录像默认关闭，用户逐通道开启。默认保留 7 天、容量 40 GB、磁盘预留 8 GB，界面可调整。保留期限到达后 MediaMTX 自动删除本机录像；配额达到后暂停录制，不删除录像机中的数据。配额每 20 秒观察一次，允许少量超出。文件路径及录像索引使用 UTC，界面按浏览器时区显示。

HLS 会有数秒延迟。网页清晰度仅提供“主码流”和“子码流”两个选项，默认主码流。主码流预览使用实际主码流，通过 Intel VAAPI 硬件解码、缩放及 H.264 Main 编码，最高 1920×1080、15 帧/秒。子码流预览使用实际子码流，由 FFmpeg 按需生成 H.264 Baseline / AAC 兼容画面，最高 768×432、10 帧/秒。高清预览需要可用的 Intel 核显、驱动及 render 设备权限，不自动退回高负载的软件高清转码。首开需要等待取流与缓冲。没有观看者后会停止转码；同一镜头的观看者共享一路转码。网页不提供原始编码直出的预览选项。本机录像保留原始主码流编码，兼容预览不改变录像及摄像头设置。网页回放按需转换为 H.264/AAC，最多同时两个会话，每段最多一小时；使用时间轴或定位时间跳转。关闭回放或切换页面后终止转换，不生成额外缓存文件。有可用 VAAPI 时回放最高 1080p/15 帧，否则使用 768×432/10 帧软件转换。下载保留原始录像编码，需支持该编码的播放器。设备状态基于 MediaMTX 实际码流状态；“正在录像”还要求观察到近期写入的本机录像文件。离线不会生成假画面或假录像。

实时预览按镜头独立恢复连接：普通状态轮询只更新标签，不重建播放器；断流后按 2–30 秒退避重连，画面长时间不前进时也会自动恢复。用户主动暂停会保留暂停状态，离开页面会清理播放器和重试任务。

## Ubuntu x86_64 部署

先将源文件提交、公开发布，再部署同一 Git 提交的归档。建议放在 `/opt/zhaovision/releases/<commit>/`。Python 3.11 以上，无 pip 运行依赖。

```sh
sudo VISION_BIND=<本机的Tailscale-IPv4> bash deploy/install.sh
```

安装脚本从系统软件源安装 FFmpeg；检测到 Intel renderD128 时安装 Intel 媒体驱动，授予服务用户 render 组权限，并校验安装固定版本 MediaMTX v1.21.1，创建无登录权限的服务用户，数据写入 `/var/lib/zhaovision`，应用入口为 `http://<Tailscale-IP>:8790/`。可用逗号分隔的 `VISION_BIND` 同时指定本机局域网与 Tailscale 地址；已安装系统在 `/etc/zhaovision.env` 中修改并重启服务。视频服务的 HTTP、RTSP 与管理 API 全部仅监听回环地址，由应用进行登录鉴权并代理。

首次打开页面，读取服务器上的 `/var/lib/zhaovision/setup-code.txt`，输入初始化码，设置至少 8 位管理密码（初始用户名为 admin）。初始化后码文件删除。摄像头与录像机密码在自己的界面填写。

```sh
systemctl status zhaovision zhaovision-media
journalctl -u zhaovision -u zhaovision-media --since '10 minutes ago'
```

程序不自动修改网络、防火墙、Tailscale 子网路由或设备密码。录像机仍按其原有设置运行。

## 开发

```sh
python3 app.py
# 在另一个终端运行 MediaMTX，使用首次启动生成的配置
mediamtx ./data/mediamtx.yml
```

回归测试：`python3 -m unittest -v test_app test_ptz test_camera_settings test_ptz_presets test_households test_heritage test_appearance test_backups` 和 `node --test test_live_player.js test_kinship.js test_calendar.js test_family_graph.js test_ui_logic.js test_recording_tools.js test_theme.js test_households_ui.js test_devices.js test_steward.js test_personalization.js`。测试使用临时数据库和模拟播放器，不连接真实设备。

访问 `http://127.0.0.1:8790/`。后端配置变量：`VISION_BIND`、`VISION_PORT`、`VISION_DATA`、`VISION_RECORDINGS`；高清转码可用 `VISION_VAAPI_DEVICE` 指定渲染设备（默认 `/dev/dri/renderD128`）。HTTPS 反向代理场景可设 `VISION_SECURE_COOKIE=1`。当前管理 API 使用管理员与个人账号分权。

## 数据与恢复

数据库和生成的 MediaMTX 配置含设备连接凭据，存于权限受限的本机目录，不进入 Git。系统管理员可以读取这些凭据；当前版本未提供硬盘加密。备份时停止两个服务并一并备份整个 `/var/lib/zhaovision`。恢复到同一路径、修正服务用户所有权后启动服务。升级时保留数据目录，发布目录按提交留存，回滚 `current` 符号链接并重启服务；后续涉及数据库版本变更时需遵循对应迁移说明。

本仓库不包含真实家庭地址、设备凭据、视频文件或部署主机凭据。

## 第三方软件

- [MediaMTX](https://github.com/bluenviron/mediamtx) v1.21.1，MIT，部署时独立安装。
- [FFmpeg](https://ffmpeg.org/)，通过系统软件源安装为独立进程，用于按需兼容预览。
- [hls.js](https://github.com/video-dev/hls.js) v1.7.3，Apache-2.0，浏览器构建与许可证位于 `web/vendor/`。
- 官方接口参考：[录像](https://mediamtx.org/docs/features/record)、[回放](https://mediamtx.org/docs/features/playback)、[配置](https://mediamtx.org/docs/references/configuration-file)。

[系统架构与对象关系](ARCHITECTURE.md)。

本项目源码以 MIT 许可证发布。v0.1.x 为初始版本，真实录像机的历史回放兼容性需完成型号适配后另行验证。

## 账号与家谱（v0.1.11）

- 管理员维护设备、空间、账号和权限。个人账号只可观看授权空间内的实时画面与本机回放，设备配置归属本家庭管理员；网络发现、全局存储与审计仅超级管理员可用。媒体播放请求逐次检查空间权限。
- 每个账号具有独立用户名和密码，密码使用 scrypt 散列存储；更新密码、角色、空间范围、家谱权限或停用状态会撤销该账号会话。亲属关系不自动授予权限。
- 管理员在“账号与关系”中设置显示名称、相对于哪个账号的称呼，以及关联的家谱人物。支持常用称呼与自定义称呼。默认新个人账号没有空间或家谱权限。
- 家谱是各家庭独立的家庭档案，具有独立的不可访问、查看、编辑权限。一个编辑账号可录入任意数量的祖先、亲属与后辈，无需为每位人物开户。v0.1.23 起按家庭隔离人物、记事、历史版本与导出。
- 人物记录姓名/称呼、别名、性别、生卒日期、在世情况、籍贯、生平和信息来源。日期可按公历或农历录入，并自动换算；不确定日期可留空，在备注中保留原记载。
- 亲子关系按“父母一方 → 子女”逐条连接，支持亲生、收养、继亲和未注明；配偶关系为双向。禁止自我关系、重复关系、祖先循环、直系祖先与配偶冲突。关系可以停用后恢复，人物可归档后恢复。
- 支持关系参照人物、搜索、全家关系图、人物名册和 JSON 导出。孙辈、曾孙辈、玄孙辈等直系辈分由路径推算；旁系复杂称谓显示明确路径，缺少出生日期时不猜测兄弟姐妹的长幼。称谓用于辅助阅读，以录入关系为准。
- 并发编辑使用家谱修订号，旧表单提交会被拒绝，避免覆盖他人的更新。导出包含人物和关系，不含密码和设备凭据。当前导出用于保存副本，尚未提供 JSON 导入界面。

### 从 v0.1.10 升级

部署前用 SQLite backup API 保存 `/var/lib/zhaovision/vision.db`。首次启动 v0.1.11 会将原有单密码账户迁移为 `admin`，保留原密码散列，并把既有会话关联到管理员；没有固定出厂密码。新增 `users`、`people`、`family_links` 表和 `sessions.user_id` 列。以后可以直接升级；若回退到 v0.1.10，必须同时恢复升级前数据库副本，因为旧版本使用旧账户模型。人物和实际账号数据仅在受限数据目录中，不包含在公开源码内。

## 监控墙、云台与日期（v0.1.13）

- 监控墙支持自适应（每页最多六路）、1/2/4/6/9/16 分屏、翻页、拖动和前移/后移排列。布局和顺序按账号保存在当前浏览器；不跨设备同步。排列和分屏只改 CSS 与可见性，不重建播放器。全屏使用浏览器 Fullscreen API，Esc 退出。属于网页全屏模式，尚非可离线运行的安装包。
- 当前监控页的通道保持连接，翻页隐藏的通道也继续播放，以便切回时不重复连接；大规模通道应评估转码和网络开销。浏览器处于前台并保持系统唤醒时可持续监看。
- 云台读取 ONVIF PTZ 能力，仅对有匹配媒体配置、标准连续方向速度空间和一秒超时支持的直连摄像头提供四方向短距离微调。每次移动明确设置 PT1S，随后发 Stop；同一物理节点串行控制，独立停止按钮不排队。设备未声明的变焦、回到原点等功能不显示。协议参考：[ONVIF PTZ](https://www.onvif.org/ver20/ptz/wsdl/)。ONVIF 服务端口默认为 80。
- 管理员具有云台权限；个人账号需同时具备空间访问和独立的云台控制权限。新账号默认不允许转动。两个镜头如果指向同一 PTZ 节点，控制的是同一物理云台，不能据镜头数量推断独立电机。
- 人物默认在世；只在“不在世”时显示去世日期，旧人物的“待确认”状态保持原样。出生/去世各使用一个日期输入，选择历法，农历可勾选闰月；数据库统一保存公历日期，避免两份日期不一致。使用浏览器 ICU Chinese calendar，不联网。公历转农历范围 1901–2100，农历录入范围 1901–2099。更早祖先生卒日期可填公历并保留原始记载；不对古代历法作精确推断。
- 站点与标签页图标为“赵”字的甲骨文风格原创设计，并非考古字形摹本。参考字库及生成说明见 [ICON.md](ICON.md)。


## 完整关系图与家族记事（v0.1.16）

### 看全家

进入“家谱”默认打开完整关系图，包含有效的亲子和配偶关系；归档人物默认隐藏，可勾选显示。每位人物只出现一次，不按代数截断。父母在上、子女在下，配偶在不违反亲子方向时并列；跨层配偶和复杂多重关系保留连线及提示。尚未建立关系的人单独展示，不推测亲属身份。

暖金色和“本人”标识只用于当前账号关联的家谱人物，由管理员在“账号与关系 → 关联家谱人物”设置。关系参照和当前选中人物可另外切换，不改变本人身份。管理员未关联人物时会提示，不把其他人误标为本人。支持点击档案、名册、人物搜索、放大缩小、拖动空白处、滚动条、查看全谱、定位本人、全屏和 Esc 退出。浏览器拒绝原生全屏时使用网页内铺满显示。

### 记事的完整流程

1. 在“家族时间线 → 写一则记事”，或人物档案“记一件事”开始记录。
2. 填写标题、发生日期、摘要、正文，并可关联多位人物、附报道来源和 HTTP/HTTPS 链接。发生日期支持公历或农历输入，沿用日期换算范围，统一存储公历。
3. 可保存草稿，编辑完成后发布。发布范围是拥有家谱权限的账号，不是互联网匿名访问。家谱编辑者及管理员可查看和维护草稿、已发布内容、归档记录；只读成员仅能查看未归档的已发布记事。
4. 时间线默认从近到远，按发生年份分组，支持年份、人物、关键词、顺序和发布状态筛选。人物筛选可额外包括其直接父母、配偶和子女；每条记事按关联人物追溯，全家记事在“全家”范围显示。
5. 点击记事阅读详情或跳转原始报道；点击关联人物返回图谱和档案。人物档案可以再进入该人物的时间线，形成双向浏览。关系图默认不展开记事内容。
6. 归档保留数据；在“已归档”打开记录并编辑，取消归档后保存即可恢复。记事与人物、关系共用修订号，并发旧表单拒绝覆盖新版本。正文是纯文本，不执行 HTML 或嵌入第三方页面。

JSON 导出升级为格式 version 2，包含人物、关系和当前账号有权看到的记事。导出用于保存副本，尚无导入界面。外部报道只保存链接和用户填写的内容，不自动抓取网页；链接失效时，已填写的正文仍保存在本机。

### 升级及数据

启动时幂等创建 `family_events` 表，无需修改既有人物、账号、摄像头或录像记录。部署前使用 SQLite backup API 备份数据库。还原备份会回退备份后的数据，旧版本看不到记事表；应保留升级后的数据库备份，不以旧版本界面作为记事恢复工具。源码中不含真实家族记事和人物信息。

### 代理缓存兼容（v0.1.17）

入口 HTML 禁止缓存；页面引用的脚本和样式自动带上发布版本号，避免 NPM 等反向代理为旧资源设置长缓存后，新页面混用旧脚本。升级时普通重新载入即可获取与页面一致的资源。

## 逻辑一致性修复（v0.1.18）

- 记事正文实际支持 12000 字中文、摘要支持换行；该接口的 JSON 请求上限为 128 KiB，其他接口保持 16 KiB，并拒绝无效 Content-Length。
- 编辑已发布记事默认“保存修改”保持发布状态，Enter 保存也不会撤回。撤回为草稿使用独立按钮；首次发布时间在撤回、重发和归档恢复之间保留。
- 遇到家谱并发修订冲突，当前输入保留；复制需要保留的内容后，可明确点击“读取最新版本（覆盖本次输入）”继续编辑。服务器保存成功而页面重新读取失败时，提示已保存，避免误以为需要再次提交。
- 从记事跳到归档人物时自动显示归档人物。当前账号的本人标记与关系参照人物区分；变更本人关联会重新布局。
- 新建、恢复亲生关系及修改人物出生日期时，已知父母出生日期必须早于子女；日期未知以及收养、继亲关系不据此推断或拒绝。
- 退出或切换账号后，旧请求不得重新写入私有视图；过时的状态刷新不会覆盖较新的结果。共享浏览器标签页切换账号时，在下一次状态刷新或会话检查中清理前一账号的视图。
- 日期表单按人物或记事分别校验，编辑记事不会清除另一张人物表单的去世日期。


## 摄像机参数、版本留存与账号自助（v0.1.19）

### 摄像机设置

管理员在实时画面或镜头通道中点击“摄像机设置”。服务通过已保存的设备凭据读取能力，精确匹配当前镜头的主 / 子码流路径（包括查询参数）。不接受客户端提供的任意设备服务地址。

- 显示设备型号、固件、镜头视频源及编码。图像设置作用于该物理镜头，主、子码流共用。
- 按设备实际支持范围提供亮度、对比度、饱和度、锐度、日夜模式、背光补偿、宽动态及白平衡。
- 主、子码流分别提供分辨率、帧率、码率上限、画质和关键帧间隔；未开放的参数不会出现。
- 保留现有视频编码及设备扩展字段。有些设备使用 H264 兼容结构报告 H265，不能仅凭标准 Encoding 字段就改写编码。
- 保存前重新读取、验证范围并检查参数版本，同一物理设备串行保存。保存后回读实际值，未确认或不一致会提示重新核对，不自动反复写入。
- 修改码流可能短暂中断实时画面，并影响录像机收到的码流。当前设备参数写入仅管理员可用。
- 双向对讲、自动跟踪、告警灯 / 警笛、画面翻转、隐私遮蔽、云录像、消息推送尚未接入；界面明确列出这些边界。设备宣告支持某个 ONVIF 服务不等于本系统已经实现该功能。

协议依据：[ONVIF Imaging Service](https://www.onvif.org/specs/srv/img/ONVIF-Imaging-Service-Spec-v1606.pdf)、[ONVIF Media Service](https://www.onvif.org/specs/srv/media/ONVIF-Media-Service-Spec-v240.pdf)。本系统按设备返回的选项校验与设置，不依赖萤石云账号。

### 家谱修改记录

人物档案、亲属关系及记事详情都有历史入口。每次保存将修改前 / 后内容、操作者与时间、家谱版本号写入 `family_changes`，与实际记录一起提交。可以分页查阅、对照旧版并选择恢复；恢复会重新验证现有家谱约束，并生成新版本，不删除后续历史。不提供创建前的空版本恢复。

历史包含曾撤回的内容，只对家谱编辑者和管理员开放。读取版本后若家谱发生变化，恢复会拒绝并要求重新读取。历史从本版本开始记录；升级前的内容会在下一次修改时作为“修改前”保存。历史属于私有数据库，不进入公共源码或普通家谱 JSON 导出。

### 我的密码

所有登录账号都可通过侧栏“修改我的密码”填写当前密码、新密码及确认。服务器验证当前密码，并限制连续错误次数。成功后撤销该账号全部登录会话，其他账号不受影响；账号角色和人物关联不变。系统不会把密码记录到操作日志。

### 并发与数据一致性

设备对象的校验与保存串行执行；镜头数量限制不能被同时提交绕过。摄像头对象移动空间时，所有镜头归属在同一数据库事务更新。录像机地址或账号更新后，关联通道读取最新端点。无效对象编号、错误 Origin 和非法地址类型会返回明确错误。


### 实机验收完善（v0.1.20）

摄像机信息及参数改为紧凑布局；全屏监控隐藏管理参数入口。读取或保存时暂时锁定参数输入，避免正在编辑的值被返回结果覆盖。视频服务错误响应也会正确关闭，修复新 Python 版本提示的资源未释放问题。


## 云台常用位置、截图与录像续播（v0.1.21）

- “云台控制”中读取设备预置位。管理员可以保存当前位置、删除位置；有对应空间与云台权限的个人账号可以查看和转到已有位置。保存和删除前检查版本，保存后回读设备列表。位置保存在摄像机中，双镜头可能共用同一云台。名称最多 40 字。本版不提供覆盖已有位置：实测 H9c 当前固件拒绝标准更新请求，调整后可另存新位置，再由管理员决定是否删除旧位置。
- 云台操作按物理设备 / 节点互斥。预置位转动后查询设备状态，观察窗口为 10 秒，单次设备请求另有 5 秒超时；结束、超时或异常都尝试发送 Stop。停止按钮不排队，可取消正在等待的转动。设备网络失联时无法保证 Stop 送达，界面会明确提示核对画面。关闭面板或切换后台时，对正在执行的操作尝试停止。预置位位置和设备能力仍以具体型号、固件实际返回为准。
- 实时画面与录像回放增加“截图”。截取当前播放器已解码的一帧，可预览并下载 PNG。图片仅在当前浏览器内存中生成，不上传到服务器，关闭后释放。截图分辨率取决于当前预览码流；截取时间不是摄像机源时间，仍有播放缓冲延迟。
- 本机录像查询按所选日期裁剪、排序与合并重叠范围。每次转换最多一小时，播放结束可以继续下一段；真实空档会跳过并提示。可取消自动续播。未正常播完的片段不会自动略过，主动暂停不会触发续播。
- 录像页显示实际录像时间，支持以当前播放位置标记片段起止、手动修改起止时间、生成原始编码下载链接。片段最长一小时，不能跨越无录像空档；边界受原始关键帧影响，非逐帧无损剪辑。自动续播保留正在填写的自定义片段。
- 本版不创建新的家庭数据或修改已有账户和录像策略；新增界面及设备操作继续使用既有空间、管理与云台权限。录像机原有历史录像仍未适配，以上续播与片段工具用于小电脑本机录像。

预置位协议依据：[ONVIF PTZ Service 5.4](https://www.onvif.org/specs/srv/ptz/ONVIF-PTZ-Service-Spec.pdf)。自动回归包含权限、并发、版本冲突、设备拒绝或未确认写入、停止、回放空档、日期边界和退出账号后的异步响应清理；模拟设备测试不代表所有品牌均已实机验证。


## 家庭隔离与权限交接（v0.1.23）

- **超级管理员**（`admin` 角色）：可建立家庭、切换家庭和管理全部资料；现有 `admin` 账号保持此角色。
- **一家之主**：本家庭一位已启用的家庭管理员，由超级管理员首次指定。可管理本家庭设备、成员及其他家庭管理员，并办理家主交接。
- **家庭管理员**：管理本家庭设备、空间、家谱与普通成员；有家主后，其他管理员账号的设置由家主或超级管理员办理。
- **家庭成员**：仅能查看本家庭已授权空间的画面与录像；家谱、云台另行授权。新账号默认不获得设备和家谱权限。亲属称呼不授予权限。

在「家庭与场所」新建家庭、办公场所或工厂，进入该家庭，在「账号与关系」建立家庭管理员。回到「家庭与场所 → 负责人安排与交接」，指定一家之主和另一位备用负责人，填写说明并保存。**备用负责人已经拥有本家庭管理权限**，家主意外无法操作时可以继续管理设备和成员；家主身份由原家主或超级管理员正式交接，原家主保留家庭管理员权限。不会依据去世日期或未登录时长自动授权。不允许停用或降级尚在任的家主、备用负责人；须先更换安排。至少保留一位启用的家庭管理员。交接使用修订号防止并发覆盖，并保留最近 50 条记录。普通成员不能读取交接说明。

家庭隔离由服务器执行：账号、空间、对象、镜头、录像机、家谱人物、关系、事件与历史版本均有家庭归属。HLS 播放清单、分片、回放、下载及设备控制均逐请求核验；修改请求检查每个关联对象的家庭。普通账号伪造家庭请求头或猜测其他家庭的对象编号也不能获得资料。超级管理员具有跨家庭权限。家庭切换先清除播放器、表单和旧请求；各家庭独立计算家谱修订号。

升级前用 SQLite backup API 备份数据库。首次启动把旧数据归入「赵府」家庭，保留原 ID、密码散列、设备连接和会话；家主与备用负责人须在界面明确指定，不从姓名或辈分猜测。已有 `admin` 角色均保留超级权限，请按实际职责设为家庭管理员。**建立第二个家庭后，不能直接回退到 v0.1.22 或更早版本**，旧版本不执行家庭隔离；应修复前进，或连同升级前数据库及部署版本一起恢复并确保后续数据另有备份。

这是单台受信主机上的应用权限隔离。各家庭的设备仍共享媒体服务和存储容量，家庭管理员不具有操作系统权限；尚未提供按家庭磁盘配额、独立网络、硬盘加密或无人审批的自动继承。


### 多维设备分类与区域树（v0.1.23）

- 在「家庭与场所」选择管理归属，再在「区域与空间」添加区域；选择上级区域即可继续细分，例如「厂区 → 车间 → 产线 → 工位」。名称、区域类别、地址按需填写，程序没有固定层数上限。不能把区域放到自身或后代下，也不能跨家庭/场所挂接。
- 在「设备管理」登记设备。摄像机与录像机保留已有接入、通道功能，其他设备使用可自定的类型；同一设备只存一份档案。所有人、负责人是责任信息，不会自动授予账号查看或控制权限。
- 调整「依次分组」，可保存「类型 → 区域」「区域 → 类型」「负责人 → 类型 → 区域」等顺序为当前归属的默认视图。支持五种维度自由组合：类型、区域、负责人、所有人、标签。区域维度按完整自定义层级展示；五种维度不限制区域本身层数。设备可在多个标签组出现，总设备数仍按档案计算。
- 区域筛选默认包含其后代。账号权限另行设置：默认只授权明确勾选的区域，可显式勾选「包含所有下级区域（含以后新增）」。服务器实时计算后代集合；移动区域会立即改变其继承的访问范围。跨家庭/场所隔离始终生效。
- 灯、手机、冰箱等目前支持档案、位置、责任归属及标签管理，不能通过登记档案直接控制硬件。需按设备实际协议接入控制功能。


## 智能数字管家的入口与传承档案（v0.1.24）

系统从「我的家庭与场所」开始。进入一个家庭、办公室或工厂后，左侧才显示该归属下的「场所总览」「区域与设备」「成员与权限」「区域设置」。家庭另有「家庭传承」。平台存储与审计仅向超级管理员开放。

### 从设备进入功能

在「区域与设备」点击设备名称：摄像头内部提供「设备档案 / 实时画面 / 录像回放 / 镜头设置」；实时画面与回放仅列出该摄像头的已授权镜头。普通成员没有镜头设置入口。录像机同样作为设备存在，展示明确关联的通道；通用设备先提供档案。场所总览的「本场所监控墙」可集中查看本场所已授权镜头，分屏与顺序按账号、归属及设备分别保存。

切换设备会释放之前的播放与云台会话；切换归属会清空私有视图并使旧请求失效。新版入口不自动拉取所有摄像头视频。原始摄像机接入参数、媒体配置和录像策略保持原值。

### 家庭传承

- 「人物与家谱」打开关系图，「家庭记事」直接进入时间线。
- 「文化与家风」保存故事、家训、手艺、整理人、日期、正文及资料链接。
- 「家庭物品与财产档案」保存来历、所有人或共有说明、保管人、意向接收人和交接说明，可关联本家庭已有设备。
- 档案支持搜索、查看详情、编辑、归档和恢复。编辑时检查修订号，拒绝用旧表单覆盖新内容。资料按家庭隔离；仅保存文字及链接，不上传或备份链接目标文件。
- 在「成员与权限」独立设置「文化与财产档案权限」为不开放、查看或编辑。家庭管理员管理本家庭全部档案；普通成员已有的家谱权限不会自动开放财产资料。改变该权限会撤销该账号现有会话。

交接说明只是记录意愿，不自动改变财产所有权、设备责任人、账号角色或家主安排。实际系统权限交接继续走「我的家庭与场所 → 负责人安排与交接」。当前非超级管理员账号仍只属于一个家庭或场所，多归属成员身份尚未实现。

升级幂等创建 `heritage_entries` 表，不自动修改现有账号、设备或家谱。未新增授权的普通成员默认无法读取此表。仍需在升级前备份数据库。录像机历史录像适配、通用设备实际控制、物品正式交接流程尚待后续实现；本版不宣称解决摄像机源流全部卡顿问题。


## 统一发布配置与个人后台（v0.1.25）

“设置中心”提供两层设置：

- **我的后台**：每个账号独立选择庭院书卷、清爽明亮或静夜墨色主题，左侧/顶部目录、疏密、山水/纯色背景、标题字体及登录首页。保存至服务器后跨设备沿用；未保存预览在离开设置时撤销。“跟随平台默认”会使用管理员的当前默认值。
- **发布与品牌配置**：仅超级管理员可改系统名称、副标题、题词、登录文案、页脚、Logo 与浏览器图标。Logo、favicon 可分别上传或恢复默认。导出/导入仅包含品牌和默认外观，不包含账号、家庭资料、设备凭据或备份目录；导入先填入表单，核对后才保存。

家庭/场所档案增加省份、地级市、区县及封面照片。卡片按省份和地级市归组，没有填写的归入“未填写地级市”。分组不改变家庭授权。封面原图最多 5 MB，浏览器转成最长边 960 像素以内的 PNG，必要时继续缩小；Logo 最长边 256，favicon 96。图片保存在数据库内；家庭封面接口须登录并拥有该归属权限。无照片时显示默认文字封面。

## 数据库自动备份（v0.1.25）

超级管理员进入“设置中心 → 数据库备份”，可立即备份，或启用按北京时间执行的每日计划。默认关闭计划、网络目录留空，每个目录保留本实例最近 14 份，可设置 1–90 份。

1. SQLite online backup API 生成一致性副本，不停止视频服务；副本完整性检查后移除会话，计算 SHA-256 并以临时文件原子改名完成本机保存。
2. 本机目录为 `VISION_DATA/managed-backups`。副本包含所有家庭、密码散列、设备连接凭据、家谱、记事、照片和设置；**不包含录像文件，未对副本进行额外加密**，按敏感数据保管。恢复后须重新登录。
3. 网络目录必须是服务器已经挂载且服务账号可写的绝对目录。默认 systemd 服务只允许写 `/var/lib/zhaovision`，建议把网络盘挂载在其下的 `network-backup` 目录。服务启动后新增挂载需确认该挂载在服务的文件系统视图中可见；必要时重启应用服务。
4. 本版不内置百度网盘登录/API。百度网页地址或分享链接不能作为备份路径；需要主机已有可用的网络挂载/同步服务。识别受支持的网络文件系统并确认网络目录副本字节校验一致，**不能证明百度云端已同步完成**。只有普通本机同步目录而无挂载时，可让外部同步程序读取本机备份目录，其云端状态由外部程序负责。
5. 网络盘不存在或没有检测到受支持的网络挂载时明确报错；本机成功副本仍保留。本机保留策略独立执行，网络失败不会让本机备份无限累积。只清理本实例命名的旧副本，不清理目录内其他文件。同一时间只运行一次，计划每天最多尝试一次，失败可手动重试。
6. 数据库恢复由主机管理员进行：停止 `zhaovision` 和 `zhaovision-media`，先保存当前完整数据目录；校验选定副本的 SHA-256 与 SQLite integrity_check，将它恢复为 `/var/lib/zhaovision/vision.db` 并正确处理旧数据库的 WAL/SHM 文件，修正服务账号所有权，再启动服务。选用不早于副本生成版本的程序；数据库副本不会恢复录像文件或 `/etc/zhaovision.env`、Tailscale/反向代理配置。

### v0.1.26 备份目录识别修正

Linux 按目标目录最近一层挂载识别网络文件系统，支持 NFS、SMB、WebDAV、SSHFS、rclone、s3fs/goofys；本机 ext4、tmpfs 等不作为网络目标。Windows 可使用已连接的 UNC 共享目录。网络类型校验不代替云服务同步状态确认。