ila/yovision
1
0
Fork 0
Code Issues 14 Pull Requests 14 Actions Packages Projects Releases Wiki Activity
Files
49aa79f3b9685aad803d3c6b7208016be532830a
yovision/docs/02-architecture-and-code-map.md
T

30 KiB
Raw Blame History

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Architecture-and-Code-Map wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.- wiki_revision: 14b961599d6954357142713a5667fb37d38e86b7 synchronized_at: 2026-08-29T12:37:31Z

架构与代码地图

项目定位

YoVision 采用单仓三项目、两个销售产品的结构。单仓用于保持共享契约和端到端验证一致，不代表共享认证、数据库或发布生命周期。

摄像头 / RTSP / ONVIF
        │
        v
Sense（设备、媒体、区域、运维）
        │ 版本化媒体/配置契约
        v
Brain（推理、跟踪、区域判定、事件 mapper）
        │ 标准事件契约
        v
Bell（事件入站、规则、Alert、ack/close、升级、通知）

Bell 也可接收合成事件、传感器平台或第三方系统事件；Sense 与 Brain 不得成为 Bell 的启动依赖。Sense 未配置 Bell 时仍可完成设备接入、实时监看、区域配置、运维和本地事件查看。

代码地图

能力 路径 首个阅读入口 验证位置 风险
Sense 产品 Sense/ Sense/AGENTS.md、Sense/README.md、Sense/server/main.go、Sense/ui/src/main.js Sense/server/ Go 测试；Sense/ui/ lint/单测/构建 高：GoAdmin 派生、设备、媒体、凭据
Brain 推理 Brain/ Brain/AGENTS.md、Brain/README.md、Brain/src/yovision_brain/__main__.py Brain/tests/test_package.py、CLI runtime/smoke 高：模型、GPU、隐私、事件语义
Bell 产品 Bell/ Bell/AGENTS.md、Bell/README.md、Bell/server/main.go、Bell/ui/src/main.js Bell/server/ Go 测试；Bell/ui/ lint/单测/构建 高：GoAdmin 派生、认证、事件与告警状态机
共享契约 contracts/ contracts/AGENTS.md 三端消费者/生产者测试 高：兼容性与跨项目影响
Harness dev_scripts/ harness.py check --strict tests/ 中
工单模板 .gitea/issue_template/ task.md Harness 严格检查 中
Wiki 镜像 docs/ docs/README.md harness.py sync --check 低；禁止直接编辑

旧 Sense、Bell 实现仅作为 explore 需求与行为证据；dev 当前已包含从冻结 GoAdmin 基线分别派生的 Sense、Bell 入口，以及 Brain 的独立 Python 包骨架。后续业务迁移仍不得把旧自研基础框架复制回 dev。

两条主要执行路径

独立产品路径

Sense：独立登录 → 添加摄像头 → ONVIF/RTSP 验证 → 实时画面 → 绘制区域

Bell：独立登录 → 接收合成/第三方事件 → 规则匹配 → Alert → ack → close

可选集成路径

Sense/Brain 生成事件
→ Sense 持久 Outbox 或 Brain 可靠投递
→ Bell 版本化事件 API
→ (producer_id, source_event_id) 幂等入站
→ Rule → Alert → Delivery/Escalation → ack/close

集成断开不得阻断任一产品核心能力；恢复后按 Outbox 和幂等收据继续。

数据与安全边界

  • Sense 与 Bell 拥有独立账户、会话、RBAC、审计、数据库角色和备份恢复。
  • Brain 业务无状态，不持有用户、Alert 或通知真相。
  • 产品间不做跨库 SQL，不共享 JWT/Cookie，不发送摄像头凭据或内部文件路径。
  • contracts/ 是跨项目字段与语义唯一事实来源；发布契约不可原地破坏。
  • MediaMTX 是数据面独立进程；GoAdmin/GORM 只承担管理面和普通 CRUD。

不可破坏的边界

  • 16 是默认配额，不是数组、数据库、分页或循环硬上限。
  • Event 与 Alert 分离；Event 不可变，状态变化与处置结果只追加。
  • 模型输出观测，规则作业务判定；模型升级不能暗改事件语义。
  • 业务预警与运维告警分开。
  • Area/设备/规则在各独立产品内有自己的业务投影，不以共享数据库同步。
  • 单项目工单不得顺带修改其他项目；共享契约变更必须由协调工单统筹。

Sense 新代码入口

Sense 已由工单 #61 从冻结 go-admin/go-admin-ui 源码建立：后端入口为 Sense/server/main.go，前端入口为 Sense/ui/src/main.js，来源和完整 commit 记录在 Sense/LICENSES/SOURCES.md。后端保留 Cobra、Gin、GORM、Casbin、JWT 和迁移体系，前端保留 Router、Store、API、Layout、动态菜单与权限指令。上游作业、代码生成、监控等源码暂留用于升级追溯，但路由及用户入口不启用。

Sense 业务菜单必须遵循冻结 GoAdmin 的路由树：顶层目录使用 MenuType=M、Component=Layout，设备管理、视频接入、视频服务、实时监看、区域与警戒线使用相对路径作为 MenuType=C 子页面，操作权限继续作为页面下的 MenuType=F 节点。这样动态路由只替换 Layout 的右侧内容区，左侧导航、顶部栏和标签页始终保留；旧数据库由 Sense/server/cmd/migrate/migration/version/2026081623100_sense_layout.go 新增迁移修正父子关系和完整 paths，页面 URL 与权限标识不变。

工单 #64 在该基线上重建 Sense 独立身份能力：Sense/server/app/admin/apis/identity_bootstrap.go 提供受外部高熵令牌保护的一次性首位管理员初始化，数据库迁移固定建立 admin、implementation_operator、site_admin、viewer 四个角色及最小 Casbin 权限；前端继续复用 go-admin-ui 动态菜单、权限按钮、请求封装与 Layout。仓库仍不提供默认账号、默认密码或可用 JWT 密钥。

Sense JWT realm 固定为 Sense；浏览器令牌 Cookie 为 Sense-Admin-Token，后端仅接受标准 Authorization Bearer 或独立的 sense_session Cookie，不接受查询参数令牌，也不得与 Bell 共享 JWT 密钥、Cookie 或账户库。Sense 默认登录有效期为固定 30 天：后端 JWT 使用 2,592,000 秒，前端 Token Cookie 使用 30 天持久化期限；不做滑动续期、Refresh Token 或服务端单 Token 撤销，退出只删除本机 Cookie。部署新版本后已有 Token 不会自动延长，用户必须重新登录取得新有效期。登录成功/失败、登出、密码变更和鉴权拒绝写入身份审计；审计内容必须剔除密码、令牌、Cookie、验证码和其他秘密。配置管理 CRUD、configKey、set-config、接口管理等非产品必要路由不注册，即使管理员直接调用也返回 404。登录外壳必需的匿名只读 GET /api/v1/app-config 是唯一例外：它复用 GoAdmin SysConfig.Get2SysApp，只投影标记为前端可见的配置，不提供写入或管理能力。

工单 #65 新增设备台账入口：后端按 models → dto → service → api → router 分层位于 Sense/server/app/sense/device/，管理路由在 Sense/server/app/admin/router/sense_device.go，前端页面位于 Sense/ui/src/views/sense/device/index.vue。设备凭据由 Sense/server/app/sense/credential/ 独立存储和 AES-256-GCM 加密，HTTP 只返回是否已配置，不提供凭据读取接口。

设备写入采用版本号乐观并发控制；视频设备适配器状态为可接入，雷达、门磁、按钮、穿戴和其他类型明确显示“适配器未就绪”，不得伪装成已接入。admin、implementation_operator、site_admin 可维护设备，viewer 只读；停用替代物理删除。

工单 #66 在 Sense/server/app/sense/onvif/、rtsp/ 与 admission/ 建立视频接入边界：WS-Discovery 只能绑定 SENSE_ONVIF_DISCOVERY_IP 指定的本机网卡，所有 ONVIF、Media XAddr 与 RTSP Stream URI 都必须落在 SENSE_ONVIF_ALLOWED_CIDRS 明确授权的网段。HTTP 客户端禁止代理和重定向，并在每次连接时重新解析、校验和固定目标 IP，防止 DNS 重绑定；URL 用户信息及敏感查询参数被拒绝。

ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Stream URI 持久化到 PostgreSQL。接入失败会记录可行动状态但保留最后一次已验证 Profile；成功接入清除凭据更新触发的重试标记。前端继续复用 GoAdmin 动态菜单、权限链、BasicLayout 和 Element Plus 表单、Dialog、Table、Tag。 工单 #67 在 Sense/server/app/sense/media/ 与 reconcile/ 建立 MediaMTX 管理面：cmd/api/server.go 随 Sense 生命周期启动后台对账并只停止本实例拥有的子进程；检测到外部实例时设置孤儿安全闸，不发送停止信号。MediaMTX Control API 只允许 loopback HTTP，禁用代理与重定向。

媒体路由只保存设备/Profile 引用、无秘密路径名、期望态、实际态、reader、退避和下次重试；摄像头凭据从内部端口按需解密，仅在 loopback Control API 请求内临时组装，不写入路由表、基础配置、日志或 Sense 响应。MediaMTX 故障和退避不改变 #66 的设备/Profile 验证状态。

工单 #68 在 Sense/server/app/sense/liveview/ 建立单路监看投影和短期播放会话：认证 API 只返回设备/Profile 展示字段、播放状态和同源短期播放器地址，不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。播放能力令牌使用 192 位随机值、绑定登录用户、同一用户只保留一个活动会话，登录页面持续轮询时按 2 分钟无活动窗口续期；关闭页面后停止续期。

Sense/server/app/admin/router/sense_liveview.go 将列表、创建会话和状态查询接入 GoAdmin JWT/Casbin，短期播放器包装页只凭不可猜测能力令牌访问，并设置 no-store、no-referrer、SAMEORIGIN 与 CSP。前端入口为 Sense/ui/src/views/sense/liveview/index.vue，复用 BasicLayout、Element Plus 表格/分页/Dialog/Tag 和权限指令；仅 Sense/ui/src/components/sense/video-player/ 是业务专用播放器组件，任一时刻只建立一路 reader。

Sense 旧 MVP 对照

旧设备、ONVIF/RTSP、MediaMTX、实时监看和区域配置实现保存在 explore。迁移时只提取已确认业务需求和必要业务适配器；通用认证、权限、菜单、请求封装和管理端外壳必须优先使用 GoAdmin/go-admin-ui。

Brain 当前代码入口

工单 #10 建立了无界面的独立 Python 包骨架：包入口为 Brain/src/yovision_brain/__main__.py，项目与依赖元数据位于 Brain/pyproject.toml，运行和验证说明位于 Brain/README.md。固定基线为 CPython 3.11.15、pip 26.2.1、setuptools 80.9.0、pytest 8.4.2、NumPy 2.3.3 和 PyTorch 2.12.1；CPU wheel 使用 PyTorch 官方 CPU 索引，NVIDIA 路径固定为官方 CUDA 12.6 wheel。

当前骨架只提供安装、版本、runtime-info 与 CPU/CUDA smoke 入口，不包含视频、模型、规则、事件或部署能力，也不依赖 Sense、Bell 在线。CPU wheel、4 项包测试和 CPU tensor smoke 已验证；本轮没有安装 CUDA wheel，也没有执行真实 GPU smoke，因此不得把驱动满足前提写成 CUDA 可用。

Bell 新代码入口

工单 #62 已从冻结 go-admin f06540883b41d03782bb6b2c4150f298f328c6b6 与 go-admin-ui 67d393d713877572fab0b897296a4c1d525fc81d 完整应用源码分别派生到 Bell/server/ 和 Bell/ui/；来源、排除项和 MIT 许可证位于 Bell/LICENSES/。后端保留 Cobra、Gin、GORM、Casbin、JWT、迁移和认证/RBAC，前端保留 Router、Store、Axios、Layout、动态菜单和权限指令。

Bell 使用独立 PostgreSQL、JWT realm、token key 和首次迁移管理员环境变量。当前只注册用户、角色、菜单等骨架必需管理路由；部门、岗位、字典、参数、日志、代码生成、任务和监控等上游源码为升级追溯保留，但不注册路由或显示入口。骨架已验证 Go test/vet/build、前端 lint/29 项单测/生产构建及隔离 PostgreSQL 的迁移、登录和 RBAC smoke；尚未完成浏览器级前后端登录联调、生产 PostgreSQL 部署或发布打包。

Bell 旧 MVP 对照

旧 Event → Rule → Alert → ack/close 实现在 explore。迁移时保留业务语义、不可变与幂等约束，但新的通用认证、RBAC、菜单、审计和管理端外壳必须基于冻结 GoAdmin 源码。

Sense 区域与警戒线代码入口

工单 #69 在 Sense/server/app/sense/area/ 建立区域配置业务层，GoAdmin 路由位于 Sense/server/app/admin/router/sense_area.go，前端页面位于 Sense/ui/src/views/sense/area/index.vue。页面继续复用 BasicLayout、Axios、Element Plus 表单/表格/分页/Dialog/Tag/Alert 和权限指令；Sense/ui/src/components/sense/geometry-editor/ 是唯一新增的业务专用绘制组件。

数据采用两层结构：sense_area_definitions 保存当前版本指针和当前校准状态，sense_area_versions 保存每次创建、编辑、启停或重校准形成的不可变快照。更新请求携带 expectedVersion，服务在 PostgreSQL 事务中锁定当前定义；并发保存只有一个成功，其余返回冲突。历史版本不覆盖、不删除。

几何坐标使用画面内 0–1 归一化值，同时每个版本固化 Device、Profile Token、分辨率和编码。视频接入成功替换 Profile 后，admission 服务比较 Token、分辨率和编码并主动标记当前定义 needs_recalibration；读取时也会对缺失或失效 Profile 进行保守校验。系统不自动重投影旧坐标，只有用户重新确认画面并保存新版本后才清除重校准状态。

认证 API 为 /api/v1/area/configurations 及其版本子资源，接入 GoAdmin JWT、Casbin、动态菜单和操作权限。API 只返回设备/Profile 展示字段、规格、归一化坐标和版本信息，不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。

Sense 独立验收入口

工单 #71 在 Sense/ACCEPTANCE.md 固化独立纵切验收矩阵，并提供 Sense/tests/compatibility/run-static-regression.ps1 与 Sense/tests/e2e/run-isolated-e2e.ps1。隔离 E2E 从当前源码重新打 Windows 包，只启动临时 PostgreSQL 17、Sense、Digest ONVIF/合成 RTSP 夹具、独立 MediaMTX 和 Chrome，不连接 Brain 或 Bell；随机凭据只进入子进程环境与系统临时目录。

当前开发机已验证空库迁移、登录/RBAC、中文请求、严格字段、分用途加密凭据、Digest ONVIF/RTSP、MediaMTX 按需拉流、实时监看、区域重校准、GoAdmin 五菜单外壳、Windows 停止与冷启动。PowerShell 7 调用入口时会转入 Windows PowerShell 5.1 执行本地 HTTP 回归，源码打包仍使用冻结的 PowerShell 7。现场真机、客户全新 Windows、16 路长稳和跨项目链路仍未验证。

Sense Windows 交付运行链

工单 #70 在 GoAdmin 派生入口上建立 Windows amd64 交付链。构建入口为 Sense/scripts/build/build-windows.ps1；运行包入口为 start-sense.bat，它先调用现有 sense.exe migrate -c data\runtime\settings.yml，迁移成功后再调用 sense.exe server -c ...。前端生产构建复制到包内 web/，后端只在显式配置 SENSE_WEB_ROOT 时提供同源静态资源和 SPA fallback，API 与健康检查不会被 fallback 覆盖。

运行脚本将 config\sense.env 当作数据解析，只接受白名单 SENSE_* 字段，不执行文件内容；同名非空进程环境变量优先。生成的 data\runtime\settings.yml 含运行秘密，只能留在部署目录。production 固定使用 PostgreSQL，要求至少 32 字符 JWT secret，且 MediaMTX 只能为 managed 或 external；managed 在 HTTP 启动前拉起包内二进制，external 在 HTTP 启动前确认回环 Control API 可达。Demo 使用独立配置和名称含 demo/test 的隔离数据库，默认禁用 MediaMTX，绝不回退 production 数据库。

交付包同时提供检查、迁移、管理员初始化、停止、备份和恢复入口。停止脚本只操作当前包且监听配置端口的 Sense 进程树；备份密码只进入子进程环境；恢复要求数据库名和二次短语确认。包不包含 PostgreSQL、生产数据、默认管理员、默认密码或客户秘密。

DevHarness 执行路径

  • dev_scripts/harness.py check --strict 检查核心结构、YoVision GoAdmin 基线和项目规则。
  • dev_scripts/harness.py sync 只从 Gitea Wiki 导出 wiki-docs.json 映射的核心镜像；sync --check 只检查一致性。
  • archive、export 和 export --all 只在人工明确要求时处理可选任务快照，任务快照不进入核心映射。
  • dev_scripts/wiki_docs.py 负责 Gitea Wiki 读取、revision、镜像头、脏文件保护和安全路径校验。

Sense 批量开通代码入口

工单 #72 的领域代码位于 Sense/server/app/sense/provisioning/，GoAdmin JWT/Casbin/PermissionAction 路由注册在 Sense/server/app/admin/router/sense_provisioning.go，迁移位于 Sense/server/cmd/migrate/migration/version/2026082809000_provisioning.go。前端页面为 Sense/ui/src/views/sense/provisioning/index.vue，API 封装为 Sense/ui/src/api/sense/provisioning.js；页面复用 BasicLayout、动态菜单、Axios、Element Plus Steps/Upload/Form/Table/Pagination/Dialog/Tag/Alert/Button 和权限指令。

PostgreSQL 表 sense_provisioning_batches 保存幂等键、配额快照和汇总状态，sense_provisioning_items 保存行号、设备信息、逐项状态、失败原因、尝试次数和已建立的设备引用；两表都没有凭据字段。执行链按条目条件领取 ready/failed 状态，调用既有 Device、Credential Vault 与 Admission 服务，成功项不整体回滚。API 根路径为 /api/v1/provisioning/batches，覆盖创建/预校验、列表、详情、执行、失败项重试、单项重试和无秘密 CSV 导出。

Sense 本地事件只读链路

  • 内部模型、DTO、服务、API 与合成夹具：Sense/server/app/sense/local_event/。
  • GoAdmin 路由：Sense/server/app/admin/router/sense_local_event.go，仅开放 GET /api/v1/local-events 和 GET /api/v1/local-events/:id。
  • PostgreSQL 表：sense_local_event_candidates；迁移同时建立“本地事件”菜单、详情功能权限和 implementation_operator/site_admin/viewer 的只读 Casbin 策略。
  • go-admin-ui 页面：Sense/ui/src/views/sense/local-event/index.vue；复用 BasicLayout、Element Plus 表单、表格、分页、Dialog、Tag、权限指令与 Axios 封装。
  • API 响应只包含 Sense 内部候选、匿名源引用、规则引用、证据状态和保留信息，不包含 Bell/Brain schema 或送达字段。页面上的 Bell 送达状态固定解释为“不适用”，避免把本地候选冒充外部预警。
  • 列表和详情成功/失败读取会同步写入脱敏的 sys_opera_log，不依赖可关闭的全局数据库日志开关；记录只含动作、路由、操作者、结果和候选 ID，不保存筛选值、响应或证据内容。拒绝访问继续由认证/RBAC 身份审计记录。

Sense 运维中心代码路径

  • 后端入口：Sense/server/app/admin/router/sense_operations.go。
  • 领域投影：Sense/server/app/sense/operations/，只读聚合 sense_devices、sense_admission_results 和 sense_media_routes，不建立第二套运维状态表。
  • API：GET /api/v1/operations、GET /api/v1/operations/:id、POST /api/v1/operations/:id/retry；均复用 GoAdmin JWT、Casbin、PermissionAction 和响应封装。
  • 设备重试先用版本 CAS 取得在途所有权，再调用既有 admission Probe；失败时释放在途闸。媒体重试以 CAS 写入 retry_pending 和到期时间，由既有 MediaMTX 对账循环执行。
  • 前端：Sense/ui/src/views/sense/operations/ 与 Sense/ui/src/api/sense/operations.js，复用 BasicLayout、Element Plus 表单、表格、分页、Dialog、Tag 和权限按钮。
  • 本模块不导入 Brain/Bell 模型，不访问其数据库，不定义共享契约。

Sense 容量与配额代码路径

  • 领域模型、DTO、服务、API 与测试：Sense/server/app/sense/quota/。
  • GoAdmin 路由：Sense/server/app/admin/router/sense_quota.go；API 为 GET /api/v1/quota 和 PUT /api/v1/quota，复用 JWT、Casbin、PermissionAction 和 GoAdmin 响应封装。
  • PostgreSQL 表：sense_quota_settings 保存单行配置与版本，sense_quota_changes 保存不可变变更记录。迁移 2026082812000_quota.go 初始化默认 16、动态菜单、最小权限及设备启用权限。
  • 设备新增和重新启用由 quota.WithAvailableSlot 在事务内锁定配置行、计算非停用设备占用并执行写入；设备服务与批量开通服务共用该事实源。
  • 前端：Sense/ui/src/views/sense/quota/ 与 Sense/ui/src/api/sense/quota.js；复用 BasicLayout、Axios、Element Plus Alert/Row/Progress/Form/Table/Pagination/Dialog/Tag/Button 和权限指令。
  • 本模块不导入 Brain/Bell 模型，不访问其数据库，也不定义跨项目配额契约。

Sense 边缘节点代码路径

  • 领域投影、DTO、服务、审计、合成夹具与测试：Sense/server/app/sense/edge_node/。
  • GoAdmin 路由：Sense/server/app/admin/router/sense_edge_node.go；只开放 GET /api/v1/edge-nodes 与 GET /api/v1/edge-nodes/:id，复用 JWT、Casbin、PermissionAction 和统一响应封装。
  • PostgreSQL 表：sense_edge_nodes 保存最后已知投影，sense_edge_node_events 保存不可变状态转换；迁移 2026082813000_edge_node.go 建立动态菜单及 implementation_operator/site_admin/viewer 的只读权限，不写入夹具。
  • go-admin-ui 页面：Sense/ui/src/views/sense/edge-node/；API 封装：Sense/ui/src/api/sense/edge-node.js。页面复用 BasicLayout、Element Plus 表格/分页/Dialog/Tag/Alert 和权限指令。
  • 内部 ApplyHeartbeat 是未来 Sense 适配器的投影写入口，本工单不把它暴露为 HTTP API，也不定义跨项目契约。

Sense MediaMTX 分片代码路径

  • 分片模型、容量分配、健康探测、故障影响和只读迁移预检位于 Sense/server/app/sense/media_shard/；既有媒体路由仍由 Sense/server/app/sense/media/ 管理。
  • PostgreSQL 表 sense_media_shards 保存运行配置投影和健康状态，sense_media_shard_assignments 保存路径到分片的稳定归属；sense_media_routes 继续作为路径状态事实源。
  • 新路径在健康且有剩余配置容量的分片间使用 rendezvous-v1 确定性分配。已有归属在分片故障时保持不变，不自动迁移。
  • 主分片继续复用既有 MediaMTX Supervisor；额外分片通过仓库外 JSON 配置接入本机回环 Control API，并按 external 实例管理，不由 Sense 启停。
  • GoAdmin 路由位于 Sense/server/app/admin/router/sense_media_shard.go，只开放列表、详情和迁移预检三个 GET 接口。go-admin-ui 页面位于 Sense/ui/src/views/sense/media-shard/，复用 BasicLayout、Element Plus 表格、进度、Dialog、Tag、Alert 和权限指令。
  • 迁移 2026082814000_media_shard.go 建表、注册动态菜单并为 implementation_operator、site_admin、viewer 建立只读权限；生产迁移和启动不写入合成分片。

Sense 内部可靠投递入口

工单 #78 在 Sense/server/app/sense/outbox/ 建立内部事务 Outbox。业务写入通过同一 GORM 事务创建领域记录与 outbox；Sense/server/app/sense/local_event/outbox.go 是当前首个原子写入入口。GoAdmin 路由位于 Sense/server/app/admin/router/sense_outbox.go，迁移与菜单/RBAC 位于 Sense/server/cmd/migrate/migration/version/2026082815000_outbox.go，前端页面位于 Sense/ui/src/views/sense/outbox/index.vue。

内部状态为 pending、processing、retry、dead、delivered。relay 使用数据库 claim、lease 和版本号避免并发重复领取；失败按退避进入 retry，超过上限进入 dead，租约过期可恢复。成功投递写入永久幂等收据。当前模块不定义 Brain/Bell 正式 schema、connector 或机器身份，内部 payload 也不通过管理 API 暴露。

Sense 运维告警代码路径

工单 #79 在 Sense/server/app/sense/ops_alert/ 建立持久化运维告警：sense_ops_alerts 以“告警类型 + 对象类型 + 对象 ID”唯一指纹保存当前生命周期，sense_ops_alert_transitions 追加发现、确认、健康恢复、恢复确认、恢复失败和再次发生历史。健康事实只读取既有设备接入、媒体路由、媒体分片和边缘节点投影，不建立第二套设备或媒体状态事实源。

GoAdmin 路由位于 Sense/server/app/admin/router/sense_ops_alert.go，API 为 GET /api/v1/ops-alerts、GET /api/v1/ops-alerts/:id、POST /api/v1/ops-alerts/evaluate、POST /api/v1/ops-alerts/:id/acknowledge 和 POST /api/v1/ops-alerts/:id/recover。前端入口为 Sense/ui/src/views/sense/ops-alert/index.vue，继续复用 GoAdmin BasicLayout、动态菜单、Axios、Element Plus 表格/表单/分页/Dialog/Tag/Alert 和权限指令。

本模块只写 Sense 运维告警和 GoAdmin 操作审计，不导入或写入本地安全事件、Brain、Bell、Outbox 或共享契约模型。viewer 只读；implementation_operator 与 site_admin 可刷新健康事实、确认和恢复。

Brain 内部输入与配置边界

Brain 的首个独立输入边界位于 Brain/src/yovision_brain/input/，项目内配置模型位于 Brain/src/yovision_brain/config/。配置显式标记为 brain.internal.input/v1，只用于 Brain 独立开发与测试，不是 Sense→Brain 共享契约。

输入端口当前提供确定性 RGB 合成源和显式本地文件源。两者携带逻辑设备、Profile 与分辨率元数据；合成源提供固定种子、帧序列和确定性时间基准，本地文件源提供可替换解码器消费的容器字节、EOF 和协作取消边界。错误只暴露安全文件标签，不把机器绝对路径、凭据或客户数据写入日志/事件。

正式 RTSP、Sense 源配置、共享区域契约和跨项目投递仍由协调工单建立版本化 contracts/ 适配器，不得把本内部模型直接发布给 Sense 或 Bell。

Brain 可替换解码边界

Brain 解码层位于 Brain/src/yovision_brain/decode/，只依赖 #11 的内部 InputPacket 端口，向后续视觉模块输出顺序、纳秒时间戳、逻辑设备、Profile、分辨率、像素格式和尺寸变化标记明确的 DecodedFrame。具体后端通过 DecoderBackend 注册，不要求检测、跟踪或规则层依赖某个编解码 SDK。

当前独立纵切支持确定性 RGB24 合成帧，以及标准库实现的最小 YUV4MPEG2 C444 本地视频流。Y4M 只用于匿名本地/合成验证；生产 RTSP、FFmpeg/PyAV、NVIDIA 硬件解码、重连和多路调度仍是后续范围。损坏输入、不支持格式、Profile 尺寸不匹配和安全大小上限均产生明确错误；正常 EOF 与主动取消不伪装成失败。

Brain 匿名检测与单路跟踪边界

Brain/src/yovision_brain/vision/ 定义可替换 Detector、匿名边界框观测和会话内单路 IoU 跟踪。输出仅包含类别 anonymous_target、置信度、边界框、帧时间和当前进程内轨迹 ID；轨迹 ID 不跨进程、不跨摄像头，也不是自然人身份。

当前基线是版本 1.0.0 的 YoVision first-party 亮度连通区域算法，并提供 PyTorch 2.12.1 张量实现；不分发外部模型权重，PyTorch 许可已在 Brain 第三方清单记录。它用于验证匿名检测/跟踪链路，不代表人员检测效果，不承诺召回率或误报率。人脸、生物特征和跨摄像头 ReID 均未启用。

Brain 区域与方向越线规则边界

Brain/src/yovision_brain/rules/ 只消费匿名轨迹。轨迹框底边中心是归一化规则锚点；多边形边界视为区域内，状态区分 outside、entered、inside。有向警戒线按起点→终点的左右侧定义 left_to_right / right_to_left，deadband 内不触发且保留上一次显著侧。

每个结果绑定规则配置版本、Profile、分辨率、锚点和可解释原因。结果是 Brain 内部候选，不是标准事件或 Bell Alert；时段、持续时间、冷却、聚集和正式 Sense 配置契约不在本阶段。

Brain 独立纵切与内部事件边界

Brain/src/yovision_brain/app/ 编排输入、解码、匿名检测/跟踪和规则端口；Brain/src/yovision_brain/events/ 将触发结果映射为 brain.internal.event-candidate/v1 并写入可替换 JSON Lines sink。事件 ID 基于规范化输入事实与版本的 SHA-256，同一输入、配置和实现版本重复运行保持稳定。

内部候选包含逻辑输入引用、规则/模型版本、发生时间、匿名框和解释原因，不包含摄像头凭据、客户隐私、人脸、生物特征、机器绝对路径或证据引用。该格式不是 Brain→Bell 共享契约；Bell API、Outbox、机器身份、证据和跨项目投递必须由协调工单另行实现。

Reference in New Issue View Git Blame Copy Permalink