Files

T

ila 86b4dd7a07 feat: complete split camera credentials (#50 )

2026-08-13 12:24:00 +08:00

8.0 KiB

Raw Permalink 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: e6fc9d8663d8e9fb5ebfacb3c33a029b2659ae85 synchronized_at: 2026-08-13T04:16:00Z

架构与代码地图

项目定位

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

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

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

代码地图

能力	路径	首个阅读入口	验证位置	风险
Sense 产品	`Sense/`	`Sense/AGENTS.md`；后续 README/入口	`Sense/` 内测试	高：设备、媒体、凭据、并发对账
Brain 推理	`Brain/`	`Brain/AGENTS.md`；后续包入口	`Brain/` 内测试与契约测试	高：模型、GPU、隐私、事件语义
Bell 产品	`Bell/`	`Bell/README.md`、`Bell/server/main.go`、`Bell/web/src/main.js`	`Bell/server` Go 测试与 `Bell/web` lint/build	高：认证、不可变事件、告警状态机、并发处置
共享契约	`contracts/`	`contracts/AGENTS.md`	三端消费者/生产者测试	高：兼容性与跨项目影响
Harness	`dev_scripts/`	`check_harness.py`	`tests/`	中
工单模板	`.gitea/issue_template/`	`task.md`	Harness 严格检查	中
Wiki 镜像	`docs/`	`docs/README.md`	`sync_wiki_docs.py --check`	低；禁止直接编辑

Sense 与 Bell 已建立独立业务入口；Brain 的具体函数、路由和测试入口仍须随骨架工单更新，不复制旧仓库代码地图。

两条主要执行路径

独立产品路径

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/server/main.go：后端进程入口，调用 cmd/sense 启动。
Sense/server/cmd/sense/root.go：配置、数据库、迁移、模块注册和优雅退出编排；后续功能通过独立 modules_<feature>.go 注册，不反复修改共享入口。
Sense/server/internal/platform/：PostgreSQL、迁移、HTTP/JSON、健康检查与静态资源宿主。
Sense/ui/src/bootstrap/：Vue、路由、Vuex、请求封装和功能模块自动发现。
Sense/ui/src/layout/AppLayout.vue：基于 go-admin-ui 交互约定的侧栏、顶部导航、标签栏和页面容器。
Sense/config/：无秘密配置模板；真实数据库 URL 和后续签名密钥只能由仓库外环境提供。
Sense/scripts/bootstrap/：精确工具链检查和无需 Brain/Bell 的内存模式 smoke。

默认只注册工作台、健康检查和系统信息；go-admin 演示与代码生成菜单、路由和后端接口均未注册。正式启动默认要求独立 PostgreSQL；memory 只用于自动化测试和本地 smoke。

Sense MVP 模块地图

Sense 后端功能以 Sense/server/app/sense/ 为根，并通过 Sense/server/cmd/sense/modules_<feature>.go 独立注册：

identity/：Sense 独立账户、bcrypt 密码、会话、四角色 RBAC 与统一审计；签发者和受众只属于 Sense。
device/：Device 台账、状态、分页和 AES-256-GCM 凭据保险箱；ONVIF 与 RTSP 凭据可分离或显式复用，读取模型只返回两组凭据是否已配置。
adapters/onvif/、adapters/rtsp/、admission/：获准网卡上的受控发现、手工 ONVIF 接入、Media 服务发现、Basic/Digest 认证、Profile/StreamUri 读取和 RTSP 验证。跨主机 Media 地址固定回用户已授权的 Device Service origin；跨主机 RTSP URI 只替换为授权主机并保留报告端口与路径。接入结果和脱敏 Profile 持久化到 PostgreSQL，重启后可恢复。
adapters/mediamtx/、media/：外部 MediaMTX 进程所有权、localhost Control API、媒体期望态与实际态对账。
liveview/：绑定当前用户、最长两分钟的单路播放会话；只投影媒体路径，不暴露源 URI 或摄像机秘密。
area/：归一化多边形/方向警戒线、不可变版本、并发版本校验和分辨率变化后的重新校准。

前端在 Sense/ui/src/{api,views,router/modules,components}/sense/ 使用对应模块；通用页面复用 Element Plus 表单、表格、分页、Dialog、Tag 和应用容器，只为播放器与区域画布新增局部业务组件。项目内 identity.RecordAudit、device.ReadCredential、admission.VerifiedProfile、media.PlaybackRoute 和 area.ExportCurrent 是窄适配端口，不是跨项目契约。

Bell MVP 模块地图

Bell/server/main.go 与 cmd/bell/root.go：命令入口、配置、迁移、HTTP 注册和优雅退出。
Bell/server/app/auth/、rbac/、audit/：Bell 独立账户、bcrypt 密码、服务端会话、管理员/操作员/只读角色与只追加审计。
Bell/server/app/event/、receipt/：不可变 Event、(producer_id, source_event_id) 永久幂等回执和游标查询。
Bell/server/app/synthetic/ 与 server/testdata/events/：只在 development/test 注册的匿名合成事件，复用正式 Event 服务。
Bell/server/app/rule/：规则版本、每次评估解释、实际规则快照和按规则/地点关联 Alert。
Bell/server/app/alert/query/、alert/lifecycle/：Event/Alert 双向追溯、单一 ack 获胜者、结果必填的 close、幂等重复和只追加时间线。
Bell/server/migrations/：事务迁移与数据库不可变触发器；所有表只属于 Bell 数据库。
Bell/web/src/{api,views,store,layout}/：Vue 3 + Element Plus 管理端，一级导航为工作台、预警管理、事件查询、规则配置；系统与合成入口按权限/环境出现。

Event 写入、幂等 Receipt、规则评估和 Alert 创建/关联处于同一数据库事务；规则或关联失败时不保留半成品 Event。一个 Event 可匹配多个规则，一个未关闭 Alert 可聚合相同规则与地点的多个 Event。

8.0 KiB Raw Permalink Blame History Unescape Escape