From 966633d1cc80d55c2ca5bb04daee963b34f8aff6 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Thu, 27 Aug 2026 19:14:01 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E4=B8=89=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=B9=B6=E8=A1=8C=E5=AE=9E=E6=96=BD=E4=BA=8B=E5=AE=9E?= =?UTF-8?q?=20(#113)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/00-project-profile.md | 22 +++--- docs/02-architecture-and-code-map.md | 34 ++++++++-- docs/04-local-development-and-verification.md | 68 +++++++++++++++++-- 3 files changed, 104 insertions(+), 20 deletions(-) diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index 0c0576e..55a9ad3 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Project-Profile.- -wiki_revision: 5e6d18991d69aad15311aae811f35206aa0b5ee6 -synchronized_at: 2026-08-27T09:04:26Z +wiki_revision: 08df06204a840a5eca0139ae711f11d9c100817e +synchronized_at: 2026-08-27T11:07:33Z # 项目档案 @@ -19,7 +19,7 @@ synchronized_at: 2026-08-27T09:04:26Z | 首期客户场景 | 民办寄宿学校，默认 16 路高风险点位 | | 首期规则 | 越线、危险区域、聚集等匿名安全规则；不启用人脸 | | 产品形态 | Sense 与 Bell 两个独立销售产品，Brain 为独立推理交付单元 | -| 当前阶段 | 进入 GoAdmin 源码派生重建：旧实现归档于 `explore`，`main` 为审核基线，`dev` 为集成开发分支 | +| 当前阶段 | Sense 独立纵切、Brain Python 骨架、Bell GoAdmin 产品骨架已合入 `dev` 并待用户验收；旧实现归档于 `explore`，`main` 仍为审核基线 | | 历史来源 | `D:\OPC\yovision_old`，只读追溯 | ## DevHarness 来源与基线 @@ -54,7 +54,7 @@ YoVision 采用 DevHarness 的共同工作流、统一 `harness.py` 命令、Git - 证据：客户侧 MinIO/S3 兼容对象存储；常态录像优先留在客户已有 NVR。 - 首期验证平台：NVIDIA x86/Jetson；M1-M3 不承诺 GB/T 28181、信创或原生 App。 -2026-08-14 起，原 Sense、Bell 实现只在 `explore` 和原功能分支中作为迁移参考，不再作为新开发基础。新的 Sense、Bell 必须从下述冻结 go-admin/go-admin-ui 完整提交派生；实施时必须核对冻结 go-admin-doc。Brain 尚未初始化。 +2026-08-14 起，原 Sense、Bell 实现只在 `explore` 和原功能分支中作为迁移参考，不再作为新开发基础。当前 `dev` 中的 Sense、Bell 已分别从下述冻结 go-admin/go-admin-ui 完整提交派生；实施时仍必须核对冻结 go-admin-doc。Brain 已建立独立 Python/PyTorch 包骨架，但尚未包含推理业务能力。 ## 阅读入口 @@ -66,7 +66,7 @@ YoVision 采用 DevHarness 的共同工作流、统一 `harness.py` 命令、Git ## 常用命令 -当前初始化阶段可执行： +仓库级检查可执行： ```powershell python dev_scripts/harness.py check --strict @@ -75,7 +75,7 @@ python dev_scripts/harness.py sync --check git diff --check ``` -Sense、Brain、Bell 的构建、运行和测试命令尚待各自骨架工单建立，不以旧仓库命令冒充新仓库事实。 +Sense、Brain、Bell 的当前构建、运行和测试命令已分别记录在各自 README 与 `Local-Development-and-Verification`；不得以旧仓库命令替代。 ## 环境、配置与凭据 @@ -108,16 +108,22 @@ Sense、Bell 共用的可复现技术基线记录在仓库根 `goadmin-baseline. ## Sense 重建状态 -当前可运行的旧 Sense 实现保存在 `explore`，不进入新 `main` / `dev` 基线。新 Sense 尚未初始化；后续必须从冻结的 go-admin 后端和 go-admin-ui 前端源码派生，保留上游骨架、许可证和来源证据，并在工单记录实际参考的 go-admin-doc 页面。 +Sense 已从冻结 go-admin/go-admin-ui 源码独立派生，并完成设备、视频接入、MediaMTX、单路监看、区域配置与 Windows 交付的独立纵切。工单 #71 已从当前源码重新打包并通过隔离 PostgreSQL 17、Digest ONVIF/合成 RTSP、独立 MediaMTX、Chrome 外壳和冷启动回归；当前成果已合入 `dev`，仍等待用户验收。现场真机、16 路长稳和跨项目链路不在本轮结论内。 ## Bell 重建状态 -当前 Bell MVP 实现在 `explore` 和原功能分支中保留，只作需求、行为和迁移对照。新 Bell 尚未初始化；后续必须从与 Sense 相同的冻结 go-admin/go-admin-ui 基线独立派生，不能复制旧自研基础框架或共享 Sense 的认证与数据库。 +Bell 已从与 Sense 相同的冻结 go-admin/go-admin-ui 基线独立派生到 `Bell/server/` 与 `Bell/ui/`，保留来源和 MIT 许可证证据，以及独立 PostgreSQL、JWT、token key 和首次管理员边界。当前最小启用骨架已通过后端、前端和隔离 PostgreSQL smoke 并合入 `dev`，仍等待用户验收；事件、规则、Alert 等业务能力继续按独立工单迁移。 + +## Brain 初始化状态 + +Brain 已建立 CPython 3.11.15 / PyTorch 2.12.1 的无界面包骨架，提供安装、版本、runtime-info 与 CPU/CUDA smoke 入口。CPU wheel、包测试和 CPU tensor smoke 已通过并合入 `dev`，仍等待用户验收；CUDA wheel、真实 GPU、视频、模型、规则、事件与部署尚未验证或实现。 + + ## 分支治理 - `explore`：2026-08-14 前实现的只读聚合快照；不接受新功能。 diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index be60b3b..9568bcc 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -2,8 +2,8 @@ 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: ee5b5507bf8a8a834e07f223f1a90c2f67a70d6f -synchronized_at: 2026-08-27T09:14:31Z +wiki_revision: 3c95336ab96aa1e245f67c598299f2904f0e4437 +synchronized_at: 2026-08-27T11:07:58Z # 架构与代码地图 @@ -32,14 +32,14 @@ Bell 也可接收合成事件、传感器平台或第三方系统事件；Sense | 能力 | 路径 | 首个阅读入口 | 验证位置 | 风险 | |---|---|---|---|---| | 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/` 内测试与契约测试 | 高：模型、GPU、隐私、事件语义 | -| Bell 产品 | `Bell/` | `Bell/AGENTS.md`；待 GoAdmin 派生工单建立 README/入口 | 待新骨架建立 | 高：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` 快照，不是 `main` / `dev` 当前代码地图。三个项目的新入口必须随新骨架工单建立；不得把旧自研基础框架复制回 `dev`。 +旧 Sense、Bell 实现仅作为 `explore` 需求与行为证据；`dev` 当前已包含从冻结 GoAdmin 基线分别派生的 Sense、Bell 入口，以及 Brain 的独立 Python 包骨架。后续业务迁移仍不得把旧自研基础框架复制回 `dev`。 ## 两条主要执行路径 @@ -115,6 +115,22 @@ ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Strea + +## 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 对照 @@ -133,6 +149,14 @@ ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Strea 认证 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 交付运行链 diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 6b7653b..6ad7ded 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.- -wiki_revision: 7ede95108304cec08572d9da5ce1f41116e4970d -synchronized_at: 2026-08-27T09:05:09Z +wiki_revision: 09106b8f9352a0eb9ba7a8cc5f4a4143ae0ba3d2 +synchronized_at: 2026-08-27T11:08:14Z # 本地开发与验证 @@ -17,7 +17,7 @@ synchronized_at: 2026-08-27T09:05:09Z | Gitea | 工单与 Wiki | 浏览仓库或调用 MCP | | Gitea PAT | Wiki 写入 | 仅由 MCP 或 `GITEA_TOKEN` 提供，不打印 | -Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/CUDA 以及 PostgreSQL、MediaMTX 精确版本仍将在对应骨架工单冻结。旧仓库环境不自动成为新项目事实。 +Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/PyTorch 基线也已由骨架工单固定。PostgreSQL、MediaMTX 的交付版本仍按各产品工单与部署环境冻结，旧仓库环境不自动成为新项目事实。 ## Windows PowerShell 与 UTF-8 @@ -63,9 +63,9 @@ Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 | 项目 | 构建 | 测试 | 运行 | 当前状态 | |---|---|---|---|---| -| Sense | `cd Sense/server; go build ./...`、`cd Sense/ui; corepack pnpm@9.15.1 build:prod` | `go test ./...`、`go vet ./...`、前端 lint/单测 | `sense server -c <仓库外配置>` | GoAdmin 源码骨架已建立；业务模块待后续工单 | -| Brain | 待骨架工单冻结 | 待冻结 | 待冻结 | 未初始化业务代码 | -| Bell | 待 GoAdmin 派生工单建立 | 待建立 | 待建立 | 旧实现仅在 `explore`；新基线未初始化 | +| Sense | `cd Sense/server; go build ./...`、`cd Sense/ui; corepack pnpm@9.15.1 build:prod` | `go test ./...`、`go vet ./...`、前端 lint/单测、独立 E2E | `sense server -c <仓库外配置>` | GoAdmin 产品骨架与独立纵切已建立，待用户验收 | +| Brain | `Brain\.venv\Scripts\python.exe -m pip install -e "Brain[dev]"` | `python -m pytest Brain/tests/test_package.py -q`、CPU/CUDA smoke | `python -m yovision_brain --runtime-info` | Python/PyTorch 骨架已建立；CPU 已验证，CUDA 未验证 | +| Bell | `cd Bell/server; go build ./...`、`cd Bell/ui; corepack pnpm@9.15.1 build:prod` | `go test ./...`、`go vet ./...`、前端 lint/单测 | `go run . server -c config/settings.yml` | 冻结 GoAdmin 产品骨架已建立，待用户验收 | 不得复制旧仓库命令来填空。每个骨架工单必须同时建立 README、可复制命令和最小测试。 @@ -231,12 +231,66 @@ corepack pnpm@9.15.1 build:prod + +## Brain 本地环境与验证 + +Brain 固定使用 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 与 CUDA wheel 必须使用不同虚拟环境，不能混装： + +```powershell +uv python install 3.11.15 +uv venv --python 3.11.15 Brain/.venv +Brain\.venv\Scripts\python.exe -m pip install pip==26.2.1 --index-url https://pypi.org/simple +Brain\.venv\Scripts\python.exe -m pip install -e "Brain[dev]" --index-url https://pypi.org/simple +Brain\.venv\Scripts\python.exe -m pip install numpy==2.3.3 --index-url https://pypi.org/simple +Brain\.venv\Scripts\python.exe -m pip install torch==2.12.1 --index-url https://download.pytorch.org/whl/cpu + +Brain\.venv\Scripts\python.exe -m pytest Brain/tests/test_package.py -q +Brain\.venv\Scripts\python.exe -m yovision_brain --runtime-info +Brain\.venv\Scripts\python.exe -m yovision_brain --smoke cpu +``` + +NVIDIA 环境将最后一个索引替换为 `https://download.pytorch.org/whl/cu126`，再执行 `--smoke cuda`。本轮只验证了 CPU wheel 与 CPU tensor smoke；不得在未执行真实 CUDA smoke 时声明 GPU 可用。 + + ## Bell 本地构建与验证 -新 Bell 尚未初始化。骨架工单必须从冻结 GoAdmin 源码建立并验证独立构建、数据库、认证和前端流程；旧 Bell 命令只在 `explore` 对应提交中适用。 +Bell 已从冻结 GoAdmin 基线独立派生。运行前只在进程环境提供独立的 `BELL_DATABASE_URL`、至少 32 字符的 `BELL_JWT_SECRET`，以及仅首次迁移使用的 `BELL_BOOTSTRAP_USERNAME` / `BELL_BOOTSTRAP_PASSWORD`；不得提交真实值。 + +```powershell +Set-Location Bell/server +$env:GOTOOLCHAIN='go1.26.5' +go test ./... +go vet ./... +go build ./... +go run . migrate -c config/settings.yml +go run . server -c config/settings.yml + +Set-Location ../../Bell/ui +corepack pnpm@9.15.1 install --frozen-lockfile +corepack pnpm@9.15.1 lint +corepack pnpm@9.15.1 test:unit +corepack pnpm@9.15.1 build:prod +``` + +默认监听为 `127.0.0.1:18090`，可用 `BELL_HOST` / `BELL_PORT` 覆盖。当前已验证隔离 PostgreSQL 17 的迁移、健康检查、登录、未认证拒绝和 RBAC 菜单；浏览器级前后端登录、生产 PostgreSQL 部署与发布打包尚未验证。 + +## Sense 独立端到端验收 + +从仓库根目录执行： + +```powershell +& Sense\tests\compatibility\run-static-regression.ps1 +& Sense\tests\e2e\run-isolated-e2e.ps1 +``` + +详细矩阵见 `Sense/ACCEPTANCE.md`。隔离 E2E 默认需要 PostgreSQL 17 工具目录、已审核的 MediaMTX、FFmpeg 与 Chrome；路径不同时用参数显式指定。所有运行数据、随机凭据、数据库、日志、截图和构建副本位于系统临时目录，只有排错时才使用 `-KeepTemporary`，并须把保留目录当作敏感数据及时清理。 + +PowerShell 7 调用入口时会自动转入 Windows PowerShell 5.1 执行本地 HTTP 回归，源码打包仍显式使用 PowerShell 7。这是当前 Windows 交付宿主边界。现场真机、客户新主机、16 路长稳、硬件解码及 Brain/Bell 跨项目链路不在本验收覆盖内。 + + ## Sense Windows 打包与验证 -- 2.34.1