Files

T

QiuSW efb48b4030 docs: document Sense Windows package workflow (#37 )

2026-08-12 18:28:22 +08:00

7.3 KiB

Raw Blame History

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: 3bf0987ec9d7ddf543602e465faa088aead46531 synchronized_at: 2026-08-12T10:22:02Z

本地开发与验证

环境要求

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

Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/CUDA 以及 PostgreSQL、MediaMTX 精确版本仍将在对应骨架工单冻结。旧仓库环境不自动成为新项目事实。

第一次运行

检查工作区：
```
git status --short --branch
```
预期：显示 main 和本任务创建的引导文件，没有来源不明改动。
检查 Harness：
```
python dev_scripts/check_harness.py --strict
```
预期：输出“DevHarness 检查通过”。
运行 Harness 测试：
```
python -m unittest discover -s tests -v
```
预期：全部测试为 ok。

对照 Wiki：

python dev_scripts/sync_wiki_docs.py --check

预期：全部映射一致。

子项目命令状态

项目	构建	测试	运行	当前状态
Sense	待骨架工单冻结	待冻结	待冻结	未初始化业务代码
Brain	待骨架工单冻结	待冻结	待冻结	未初始化业务代码
Bell	`go build ./...`；`pnpm build:prod`	`go test ./...`；`pnpm lint`	`go run . migrate`；`go run . serve`；`pnpm dev`	首个独立纵切已实现，待验收

不得复制旧仓库命令来填空。每个骨架工单必须同时建立 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 和明确授权的实验室设备。
不提交真实视频、客户名称、地址、手机号、摄像头密码或通知凭据。
日志必须可按 request/event/alert ID 追踪，但不得记录 Authorization、Cookie 或连接密钥。

完成修改前

python -m unittest discover -s tests -v
python dev_scripts/check_harness.py --strict
python dev_scripts/sync_wiki_docs.py --check
git diff --check
git status --short

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

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

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

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 本地构建与验证

使用根 goadmin-baseline.json 的精确版本。当前机器可用的隔离 Go 路径为开发机临时工具目录，不应写入部署配置。

$env:PATH = 'C:\Users\ila20\AppData\Local\Temp\yovision-tools\go1.26.5\go\bin;' + $env:PATH
powershell -ExecutionPolicy Bypass -File .\Sense\scripts\bootstrap\check-toolchain.ps1
cd Sense\server
go test ./...
go build ./...
cd ..\ui
corepack pnpm@9.15.1 install --frozen-lockfile
corepack pnpm@9.15.1 lint
corepack pnpm@9.15.1 build
cd ..\..
powershell -ExecutionPolicy Bypass -File .\Sense\scripts\bootstrap\smoke.ps1

正式后端启动必须设置 SENSE_DATABASE_MODE=postgres 和仓库外提供的 SENSE_DATABASE_URL。健康检查为 GET /healthz，就绪检查为 GET /readyz。本地 smoke 明确设置 SENSE_DATABASE_MODE=memory，不能代替 PostgreSQL 部署验证。

Bell 本地构建与验证

先从根 goadmin-baseline.json 核对精确版本，再从仓库外环境设置 Bell 专用数据库与会话密钥。命令中的值只能使用本地测试凭据，不得提交：

powershell -ExecutionPolicy Bypass -File .\Bell\scripts\bootstrap\check-toolchain.ps1
Set-Location Bell\server
go test ./...
go build ./...
go run . migrate
go run . serve
Set-Location ..\web
corepack pnpm@9.15.1 install --frozen-lockfile
corepack pnpm@9.15.1 lint
corepack pnpm@9.15.1 build:prod

后端启动前必须提供独立 BELL_DATABASE_URL 与至少 32 字符的 BELL_SESSION_SECRET；BELL_ENV 可取 development、test、production。健康检查为 GET /healthz，就绪检查为 GET /readyz。首次管理员用 go run . create-admin 创建，密码通过 BELL_BOOTSTRAP_PASSWORD 进程环境一次性提供。

在 Sense、Brain 停止时，development/test 可使用“合成事件测试”完成 Event 入站、规则匹配、Alert 关联、ack 和结果必填 close。production 必须验证 /api/v1/synthetic/* 返回 404。PostgreSQL 集成测试使用空的 Bell 专用测试数据库，禁止复用 Sense 或生产数据库。

Sense Windows 打包与产物验证

将冻结的 Go 1.26.5 放在 PATH 首位后，从仓库根目录运行：

cmd /c .\Sense\scripts\package-windows.bat
Get-FileHash .\Sense\dist\sense-windows-amd64.zip -Algorithm SHA256

脚本精确校验 Node 22.22.1 和 pnpm 9.15.1，冻结安装并构建前端，以 Windows amd64/CGO 关闭方式编译后端，然后生成被 Git 忽略的 Sense\dist\sense-windows-amd64\ 和 ZIP。可重复运行只会覆盖这两个固定产物。

解压后运行 start-sense.bat demo 可做内存模式临时预览；生产运行 start-sense.bat 前必须从仓库和运行包外注入 PostgreSQL URL、签名密钥、引导令牌和摄像头凭据加密密钥。包内不含 PostgreSQL、MediaMTX、系统服务、客户数据或秘密。

7.3 KiB Raw Blame History Unescape Escape