yovision/deploy/postgres/README.md

YoVision PostgreSQL 初始化

本目录实现 T-009～T-012、T-015～T-016、T-019～T-020 的 PostgreSQL 17.10 schema。SQL 必须按文件名前缀顺序执行：001～004 创建 NOLOGIN 权限角色、Bell/Sense 初始对象和配额权限；005～007 增量增加 Area 与本地审计；008～009 增加 Control API 状态；010～011 增加调和 fencing、MediaMTX Path 历史归属、孤儿报告/受控处置结果；012～013 增加 Bell 不可变事件、append-only outcome 和独立 bell_runtime 最小权限；014～015 增加审计 relay；016～017 增加 Brain 事件身份绑定、永久来源收据、短期 nonce 和最小权限；018～019 增加不可变规则版本、durable evaluation、Alert/Event 关联、append-only 状态迁移、永久命令收据和最小权限。全部 SQL 可重放。对象 owner/迁移角色为 bell_app/sense_app；应用登录角色及密码由部署环境或密钥系统创建，Sense 登录加入 sense_app，Bell 运行登录只加入 bell_runtime，仓库不保存登录凭据。

生产/共享实例必须由管理员先备份并在 YoVision 专用数据库中执行。Sense 进程不会用高权限自动建库或建角色。示例只使用私有环境变量，不把实际 DSN 写入脚本或日志：

安装 008 前必须先查询并为全部历史 sense.devices.area_id IS NULL/blank 记录完成经批准的 Area 归属；migration 会失败关闭而不会猜测或自动搬迁这些设备。

$env:YOVISION_PG_ADMIN_DSN = '由管理员私下设置'
Get-ChildItem deploy/postgres/[0-9][0-9][0-9]_*.sql |
  Sort-Object Name |
  ForEach-Object { & 'D:\pgsql17\bin\psql.exe' -X -v ON_ERROR_STOP=1 -d $env:YOVISION_PG_ADMIN_DSN -f $_.FullName }

不要把该示例替换成真实连接串后提交。自动验收使用 scripts/test_postgres.ps1 启动隔离临时集群，不读取或修改 D:\pgsql17\data。

权限边界

• bell_app 拥有 bell.sites/bell.areas、版本 trigger、bell.site_quota_v1 和 bell.area_policy_v1。
• sense_app 拥有 sense schema，只获得 bell schema 的 USAGE 和两个投影视图的 SELECT。
• sense_app 对 Bell 源表、Bell migration 表和 trigger function 没有权限；启动检查发现权限过宽时拒绝运行。
• sense.device_operation_outbox 是本地持久化队列，Bell 全局审计真相只写入 bell.audit_events。Sense 只领取/确认本地行，不获得 Bell 表权限；Bell 只通过签名 HTTP ingress 收取，不读取 Outbox。
• bell.audit_events 与事件事实一样不可更新/删除；bell.audit_relay_receipts 只为 10 分钟 nonce 幂等窗口保留，Bell runtime 仅可在这张限定表中查询、插入和清理过期记录。
• bell.events 与 bell.event_outcomes 由 bell_app 拥有；bell_runtime 只获得 SELECT/INSERT，没有 owner、UPDATE、DELETE 或 TRUNCATE 权限，数据库 trigger 再拒绝 owner 路径的意外事实改写。
• bell.event_ingress_bindings 由管理员维护并引用当前 Bell Site/Area 和 Sense Device；Bell runtime 只读绑定及 Sense 设备的逻辑 ID/Area/modality 列，不可读取 endpoint、credential、profile token 或 MediaMTX path。event_ingress_receipts 永久只追加；只有 event_ingress_nonces 可按 10 分钟 TTL 清理。
• bell.rule_versions、sweep/evaluation、Alert/Event 关联、transition 和命令收据均由 bell_app 拥有；bell_runtime 只有 SELECT/INSERT，数据库 trigger 拒绝 UPDATE/DELETE。当前状态从最新 transition 推导，同一 evaluation 由唯一约束最多创建一个 Alert；命令收据永久保留以支持跨重启幂等。
• sense.control_idempotency_receipts 不保存原始 Idempotency-Key，只保存 scope/request SHA-256 和脱敏响应快照；batch_operations/items 只保存逻辑 ID、状态和稳定错误，不保存连接秘密。
• 调和与孤儿租约使用 PostgreSQL clock_timestamp() 和 fencing token；过期 worker 不能提交完成/失败或扫描报告。media_path_ownership、扫描和处置表不保存 endpoint、credential 或 source URI；数据库约束禁止为 unowned finding 写删除结果。
• PUBLIC 对两个业务 schema 的表和函数没有权限。

恢复

T-009～T-012 不迁移或删除现有 SQLite 数据，默认运行配置也仍为 SQLite。SQLite 不具备生产 Area/Outbox/Control API、多实例租约或孤儿处置一致性，业务路由不会在 SQLite 上注册。若 PostgreSQL 切换验证失败，先关闭 Control API 和孤儿扫描；需要实验室回退时停止 PostgreSQL 模式进程并恢复 SQLite DSN，不得误报为生产语义等价。schema 不提供自动 down migration；需要移除时由管理员先备份，再只删除明确确认的 YoVision 专用数据库，禁止对共享实例做模糊或递归清理。