177 lines
17 KiB
Markdown
177 lines
17 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
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: 3c95336ab96aa1e245f67c598299f2904f0e4437
|
||
synchronized_at: 2026-08-27T11:07:58Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 架构与代码地图
|
||
|
||
## 项目定位
|
||
|
||
YoVision 采用单仓三项目、两个销售产品的结构。单仓用于保持共享契约和端到端验证一致，不代表共享认证、数据库或发布生命周期。
|
||
|
||
```text
|
||
摄像头 / 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`。
|
||
|
||
## 两条主要执行路径
|
||
|
||
### 独立产品路径
|
||
|
||
```text
|
||
Sense：独立登录 → 添加摄像头 → ONVIF/RTSP 验证 → 实时画面 → 绘制区域
|
||
|
||
Bell：独立登录 → 接收合成/第三方事件 → 规则匹配 → Alert → ack → close
|
||
```
|
||
|
||
### 可选集成路径
|
||
|
||
```text
|
||
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-runtime:start -->
|
||
## 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-runtime:end -->
|
||
|
||
<!-- sense-mvp:start -->
|
||
## Sense 旧 MVP 对照
|
||
|
||
旧设备、ONVIF/RTSP、MediaMTX、实时监看和区域配置实现保存在 `explore`。迁移时只提取已确认业务需求和必要业务适配器；通用认证、权限、菜单、请求封装和管理端外壳必须优先使用 GoAdmin/go-admin-ui。
|
||
<!-- sense-mvp:end -->
|
||
|
||
|
||
<!-- brain-runtime:start -->
|
||
## 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 可用。
|
||
<!-- brain-runtime:end -->
|
||
|
||
<!-- bell-runtime:start -->
|
||
## 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-runtime:end -->
|
||
|
||
<!-- bell-mvp:start -->
|
||
## Bell 旧 MVP 对照
|
||
|
||
旧 Event → Rule → Alert → ack/close 实现在 `explore`。迁移时保留业务语义、不可变与幂等约束，但新的通用认证、RBAC、菜单、审计和管理端外壳必须基于冻结 GoAdmin 源码。
|
||
<!-- bell-mvp:end -->
|
||
|
||
<!-- sense-area:start -->
|
||
## 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-area:end -->
|
||
|
||
<!-- sense-acceptance:start -->
|
||
## 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-acceptance:end -->
|
||
|
||
<!-- sense-windows-delivery:start -->
|
||
## 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、生产数据、默认管理员、默认密码或客户秘密。
|
||
<!-- sense-windows-delivery:end -->
|
||
|
||
|
||
## 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、镜像头、脏文件保护和安全路径校验。
|