yovision/docs/04-local-development-and-verification.md

<!-- gitea-wiki-mirror:start -->
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: 09106b8f9352a0eb9ba7a8cc5f4a4143ae0ba3d2
synchronized_at: 2026-08-27T11:08:14Z
<!-- gitea-wiki-mirror:end -->

# 本地开发与验证

## 环境要求

| 工具 | 当前用途 | 检查命令 |
|---|---|---|
| Git | 版本和工作区保护 | `git --version` |
| Python 3 | Harness 脚本和测试 | `python --version` |
| Gitea | 工单与 Wiki | 浏览仓库或调用 MCP |
| Gitea PAT | Wiki 写入 | 仅由 MCP 或 `GITEA_TOKEN` 提供，不打印 |

Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/PyTorch 基线也已由骨架工单固定。PostgreSQL、MediaMTX 的交付版本仍按各产品工单与部署环境冻结，旧仓库环境不自动成为新项目事实。

## Windows PowerShell 与 UTF-8

- Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不为设置编码重复启动一层 PowerShell。
- 文本文件读写在命令支持时显式指定 UTF-8。文件解码与控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才调整当前进程输出编码或 Python UTF-8 环境变量。
- 不默认使用 `-ExecutionPolicy Bypass`。只有可信脚本确实被策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。

## 第一次运行

1. 检查工作区：

   ```powershell
   git status --short --branch
   ```

   预期：显示 `main` 和本任务创建的引导文件，没有来源不明改动。

2. 检查 Harness：

   ```powershell
   python dev_scripts/harness.py check --strict
   ```

   预期：输出“DevHarness 检查通过”。

3. 运行 Harness 测试：

   ```powershell
   python -m unittest discover -s tests -v
   ```

   预期：全部测试为 `ok`。

4. 对照 Wiki：

   ```powershell
   python dev_scripts/harness.py sync --check
   ```

   预期：全部映射一致。

## 子项目命令状态

| 项目 | 构建 | 测试 | 运行 | 当前状态 |
|---|---|---|---|---|
| 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、可复制命令和最小测试。

## 常用调试方式

- Harness 语法：`python -m compileall -q dev_scripts tests`。
- 单测：`python -m unittest tests.test_harness_docs -v`。
- 查看差异：`git diff --check`、`git diff`。
- 查看 Wiki 配置：只查看 `wiki-docs.json`，不得打印 token。
- 跨项目问题先验证契约，再分别验证生产者和消费者，不直接修改两端猜测修复。

## 测试数据与日志

- 只使用合成或脱敏事件、合成 RTSP 和明确授权的实验室设备。ONVIF 自动化测试需覆盖 Basic、Digest challenge、Media 服务发现、跨主机地址归一化、拒绝地址凭据和禁止重定向。
- 不提交真实视频、客户名称、地址、手机号、摄像头密码或通知凭据；真实设备验证只记录状态与 Profile 数量，不记录设备地址、Authorization 或 Stream URI。
- 日志必须可按 request/event/alert ID 追踪，但不得记录 Authorization、Cookie 或连接密钥。

## 完成修改前

```powershell
python -m unittest discover -s tests -v
python dev_scripts/harness.py check --strict
python dev_scripts/harness.py sync --check
git diff --check
git status --short
```

业务工单还必须运行其声明的子项目测试；跨契约工单必须运行所有受影响项目的契约测试。未执行部分写入工单。

## Sense/Bell 固定工具链与只读参考源

根 `goadmin-baseline.json` 是机器可读基线。开始 Sense/Bell 骨架或升级工作前，先核对：

```powershell
Get-Content .\goadmin-baseline.json

git -C D:\github\goadmin\go-admin rev-parse HEAD
git -C D:\github\goadmin\go-admin-ui rev-parse HEAD
git -C D:\github\goadmin\go-admin-doc rev-parse HEAD

go version
node --version
pnpm --version
```

`D:\github\goadmin` 下三个仓库只允许读取和核对，不允许在其中开发或提交 yovision 产品代码。本机路径不是跨机器事实；缺少该路径时，应从清单中的上游 URL 检出相同 commit 到仓库外目录。

截至 2026-08-12，系统 Go 1.23.0 仍不满足基线；开发机已在仓库外安装并校验隔离 Go 1.26.5，并通过 Corepack 使用 pnpm 9.15.1。Sense、Bell 的后端测试/构建与前端 lint/build 已在该隔离工具链完成。隔离目录是开发机临时事实，不得写入部署配置；其他机器应从官方来源安装相同精确版本。

`go-admin-doc` 只用于理解上游框架；项目自己的架构、开发规则和版本事实仍以 yovision Wiki、Agent 规则与 `goadmin-baseline.json` 为准。

<!-- sense-runtime:start -->
## Sense 本地构建与验证

Sense 后端与前端已从冻结源码建立。先确认 Go 1.26.5、Node 22.22.1 和 pnpm 9.15.1，再执行：

```powershell
cd Sense/server
go test ./...
go vet ./...
go build ./...

cd ../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
```

数据库固定为 PostgreSQL。复制 `Sense/server/config/settings.yml` 到仓库外，填写连接串和至少 32 个字符的随机 JWT 密钥；仓库模板本身不可直接启动生产服务。首次运行先执行 `sense migrate -c <配置路径>`，再通过只存在于当前进程的高熵令牌启动服务并创建首位管理员：

```powershell
$env:SENSE_BOOTSTRAP_TOKEN = Read-Host "输入至少 32 个字符的一次性初始化令牌"
sense server -c <配置路径>

# 在另一个 PowerShell 中输入相同令牌；不要把真实值写入脚本或命令历史
$bootstrapToken = Read-Host "输入一次性初始化令牌"
$bootstrapBody = @{
  username = "admin"
  password = Read-Host "输入至少 6 个字符的管理员密码"
  nickname = "系统管理员"
} | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:<端口>/api/v1/bootstrap" -Headers @{ "X-Sense-Bootstrap-Token" = $bootstrapToken } -ContentType "application/json" -Body $bootstrapBody
Remove-Variable bootstrapToken, bootstrapBody
```

初始化成功后停止服务，从启动环境中执行 `Remove-Item Env:SENSE_BOOTSTRAP_TOKEN`，再按正常生产方式启动。已有任一用户时初始化接口会拒绝请求。Sense 在 production、test、dev 模式均只提交账号和密码，不显示、不请求也不校验验证码；`/api/v1/captcha` 暂时保留作上游兼容接口，但登录页和登录 API 不依赖它。登录成功、错误密码和未认证拒绝仍必须写入脱敏身份审计，密码继续执行 6–72 字节策略。

Sense 默认登录有效期为固定 30 天。仓库配置和 Windows 运行脚本生成的 `jwt.timeout` 均为 `2592000` 秒，前端 `Sense-Admin-Token` Cookie 使用 30 天持久化期限。更新该版本后必须重新登录，已有 Token 不会自动延长。该有效期不是滑动续期；退出登录会删除本机 Cookie，但当前无状态 JWT 架构不提供服务端单 Token 撤销。如需立即使全部已签发 Token 失效，应在受控维护窗口轮换仓库外 JWT secret，并明确通知所有用户重新登录。

身份回归至少覆盖：admin 可管理账户及查看审计；implementation_operator 只能查看实施所需日志和字典支撑数据；site_admin 可维护账户并读取角色、部门、岗位、字典，但不能修改角色或菜单；viewer 不能访问管理接口。还要验证配置/接口管理路由返回 404、短密码被拒绝、6 位全小写密码可用，以及登录/登出/改密/拒绝审计中不含密码、令牌、Cookie 或验证码。身份审计直接写入 PostgreSQL，不依赖通用操作日志数据库开关。

详细来源与安全约束见 `Sense/LICENSES/SOURCES.md` 和 `Sense/README.md`。

设备台账启用凭据写入前，还必须在服务进程环境提供独立随机密钥；示例文件 `Sense/server/config/credential.env.example` 只保留空值：

```powershell
# 生成一次随机 32 字节密钥并以 Base64 形式注入当前进程；不要打印或写入仓库
$keyBytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Fill($keyBytes)
$env:SENSE_CREDENTIAL_KEY = [Convert]::ToBase64String($keyBytes)
[Array]::Clear($keyBytes, 0, $keyBytes.Length)
```

缺少或格式错误的密钥时，普通设备台账仍可读写，但凭据更新返回服务不可用且不得产生部分写入。设备回归至少覆盖：中文名称与位置、未知 JSON 字段拒绝、版本冲突返回 409、非视频设备显示适配器未就绪、viewer 只读、凭据响应/操作日志不含明文，以及 PostgreSQL 迁移重复执行不增加菜单或权限记录。

视频接入还需在仓库外配置 SENSE_ONVIF_DISCOVERY_IP（获准的本机网卡 IP）和 SENSE_ONVIF_ALLOWED_CIDRS（逗号分隔的获准摄像头网段）。不要使用 0.0.0.0/0 代替授权清单。

协议回归位于 app/sense/onvif、app/sense/rtsp、app/sense/admission；隔离 PostgreSQL 重启恢复测试通过 SENSE_ADMISSION_TEST_DATABASE_URL 显式启用。验证至少覆盖 Digest/Basic、无配置发现提示、URL 凭据和敏感查询拒绝、目标网段、重定向、Media/Stream 主机归一化、主子码流、失败重探保留已验证 Profile，以及 viewer 只读权限。
MediaMTX 保持仓库外独立二进制。运行前在进程环境设置：

```powershell
$env:SENSE_MEDIAMTX_BINARY = '<MediaMTX 可执行文件>'
$env:SENSE_MEDIAMTX_CONFIG = '<仓库外 mediamtx.yml>'
$env:SENSE_MEDIAMTX_API = 'http://127.0.0.1:9997'
```

配置文件不存在时 Sense 只生成 loopback API 和空 `paths: {}` 的无凭据基础配置；模板位于 `Sense/server/config/mediamtx/mediamtx.yml.example`。Control API 不允许非回环地址。真实集成验证使用：

```powershell
$env:SENSE_MEDIAMTX_TEST_BINARY = '<MediaMTX 可执行文件>'
go test ./tests/media -run TestRealMediaMTXControlLifecycle -v

$env:SENSE_MEDIA_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
go test ./tests/media -run TestPostgresColdStartRestoresDesiredRoute -v

$env:SENSE_MEDIA_MIGRATION_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
go test ./cmd/migrate/migration/version -run TestMediaMigrationOnPostgres -v
```

测试必须使用隔离端口和数据库；结束后停止测试进程。不得输出连接串或摄像头凭据。

### Sense 实时监看

浏览器直接访问 Sense 所在主机且 MediaMTX 使用默认 WebRTC 端口 8889 时无需额外变量。反向代理、HTTPS 或端口映射部署必须在 Sense 进程环境提供浏览器可达的基础地址；值只能是无用户信息、查询和片段的 HTTP(S) origin：

```powershell
$env:SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE = 'http://<浏览器可达主机>:8889'
```

不要填写 RTSP 地址、Control API 地址、摄像头凭据或服务器内部文件路径。HTTPS 页面不得嵌入 HTTP 视频地址；应为 MediaMTX WebRTC 配置 HTTPS 或受控同源代理后填写对应 HTTPS origin。

定向与回归验证：

```powershell
cd Sense/server
go test -race ./app/sense/liveview
go test ./...
go vet ./...
go build ./...

$env:SENSE_LIVEVIEW_MIGRATION_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
go test ./cmd/migrate/migration/version -run TestLiveviewMigrationOnPostgres -count=1 -v

cd ../ui
corepack pnpm@9.15.1 lint
corepack pnpm@9.15.1 test:unit
corepack pnpm@9.15.1 build:prod
```

真实 smoke 使用隔离端口、MediaMTX 和合成 RTSP：浏览器打开 WebRTC 播放地址后必须取得非零视频尺寸和可播放 readyState，并确认任一时刻只存在一个播放器。结束后停止测试 MediaMTX/FFmpeg/浏览器并删除临时目录。客户真实摄像机与现场网络仍需获得授权后验证，记录状态而不记录地址、URI 或凭据。

<!-- sense-runtime:end -->


<!-- brain-runtime:start -->
## 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 可用。
<!-- brain-runtime:end -->

<!-- bell-runtime:start -->
## Bell 本地构建与验证

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 部署与发布打包尚未验证。
<!-- bell-runtime:end -->

<!-- sense-acceptance:start -->
## 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-acceptance:end -->

<!-- sense-windows-package:start -->
## Sense Windows 打包与验证

在仓库根目录使用冻结工具链构建：

```powershell
Sense\scripts\build\build-windows.ps1 -MediaMTXPath D:\approved\mediamtx.exe
```

构建脚本严格检查 Go 1.26.5、Node 22.22.1 和 pnpm 9.15.1，执行前端生产构建与 Windows 后端构建，并生成 `Sense\dist\sense-windows-amd64\` 和同名 ZIP。未传 `-MediaMTXPath` 时只生成占位说明，交付前必须另外提供已审核的 Windows amd64 MediaMTX。构建末尾会执行包审计，并清理源码目录的 `Sense/ui/node_modules` 与 `Sense/ui/dist`。

提交前验证：

```powershell
cd Sense\server
go test ./...
go vet ./...
go build ./...
go test -race ./app/sense/media ./cmd/api

cd ..\..
Sense\scripts\build\test-package.ps1 -PackageRoot Sense\dist\sense-windows-amd64
```

包内验证从解压目录执行：

```bat
check-sense.bat
start-sense.bat
stop-sense.bat
```

检查项至少覆盖配置解析与进程环境优先级、特殊字符不被执行、production/demo 数据库隔离、迁移失败不启动服务、首页 SPA fallback、`/healthz`、MediaMTX Control API、包外工作目录启动与停止、PostgreSQL custom-format 备份及恢复到独立数据库。真实摄像机、目标客户数据库账号、目标浏览器与干净客户机器仍须在授权交付环境验收。
<!-- sense-windows-package:end -->


## GoAdmin 派生前置检查

每个 Sense/Bell 骨架或基础能力工单在修改前必须：

1. 核对 `goadmin-baseline.json` 中三个完整 commit。
2. 核对本机只读副本或重新检出的上游仓库 HEAD。
3. 阅读任务相关的 go-admin-doc 主题/文件，并把参考项记录到工单。
4. 记录计划继承的 go-admin/go-admin-ui 路径、计划隐藏/禁用的模块和许可证处理。
5. 验证最终产品树确实包含上游派生结构；只使用 Go、Vue、Element Plus 或相似视觉不算通过。

<!-- sense-area:start -->
### Sense 区域与警戒线验证

后端定向与全量验证：

```powershell
cd Sense/server
go test ./app/sense/area ./app/sense/admission
go test -race ./app/sense/area ./app/sense/admission
go test ./...
go vet ./...
go build ./...
```

使用隔离 PostgreSQL 验证迁移和真实并发；连接值只放当前进程环境，不写入仓库或日志：

```powershell
$env:SENSE_AREA_MIGRATION_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
go test ./cmd/migrate/migration/version -run TestAreaMigrationOnPostgres -count=1 -v

$env:SENSE_AREA_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
go test ./app/sense/area -run TestConcurrentUpdateOnPostgresReturnsConflict -count=1 -v
```

前端验证：

```powershell
cd Sense/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
```

浏览器 smoke 至少覆盖：鼠标添加和拖动顶点；键盘 Enter 添加、方向键移动、Delete 删除；错误文字可见并具有 aria-live/alert 语义；刷新后版本、启停和重新校准状态仍可追溯。真实摄像机校准只使用明确授权设备，不记录地址、URI、凭据或视频内容。Brain、Bell 不启动时必须能独立保存、读取和预览。
<!-- sense-area:end -->

<!-- sense-supervisor:start -->
## Sense 本机 Supervisor 托管

本机开发/演示环境可由 `D:\supervisor` 托管已经构建的 Sense Windows 交付包。实例配置位于仓库外的 `D:\supervisor\programs\yovision.conf`，实例名为 `yovision-sense`；工作目录固定为 `D:\OPC\yovision\Sense\dist\sense-windows-amd64`。

Supervisor 配置只调用包内 `scripts\runtime\start-sense.ps1`，运行参数继续从包内 `config\sense.env` 读取。不得把数据库连接、JWT 密钥、摄像头凭据或其他秘密复制到 Supervisor 配置或工单。

常用命令：

```powershell
D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf status yovision-sense
D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf restart yovision-sense
D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf stop yovision-sense
D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf start yovision-sense
Get-Content D:\supervisor\logs\yovision-sense.log -Tail 100
```

新增或修改 `programs/*.conf` 后执行：

```powershell
D:\supervisor\supervisord.exe ctl /c D:\supervisor\supervisord.conf reload
```

当前 Go Supervisor 的 `reload` 会重新读取独立配置；实际受影响实例必须以命令输出和 reload 前后 PID 为准。切换托管前先停止占用 Sense 端口的非 Supervisor 实例，防止自动启动进入 Backoff。验证至少包含 Supervisor 状态为 Running、`http://127.0.0.1:18080/health` 与首页返回 200，以及受控重启后 Sense 和受管 MediaMTX PID 均更新。
<!-- sense-supervisor:end -->