96 lines
4.8 KiB
Markdown
96 lines
4.8 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: f16f2956d3d0f260501a356b5fe1087abdc5eaf5
|
||
synchronized_at: 2026-08-12T08:50:52Z
|
||
<!-- 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`；后续 README/入口 | `Sense/` 内测试 | 高：设备、媒体、凭据、并发对账 |
|
||
| Brain 推理 | `Brain/` | `Brain/AGENTS.md`；后续包入口 | `Brain/` 内测试与契约测试 | 高：模型、GPU、隐私、事件语义 |
|
||
| Bell 产品 | `Bell/` | `Bell/AGENTS.md`；后续 README/入口 | `Bell/` 内测试 | 高：认证、事件、告警状态机、通知 |
|
||
| 共享契约 | `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` | 低；禁止直接编辑 |
|
||
|
||
业务代码尚未迁入；具体函数、路由和测试入口必须随各项目骨架工单更新，不复制旧仓库代码地图。
|
||
|
||
## 两条主要执行路径
|
||
|
||
### 独立产品路径
|
||
|
||
```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/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-runtime:end -->
|