From afd4dab56743f2eb75fc4e9110d184f10fc80e68 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Sat, 15 Aug 2026 09:17:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=20Sense=20=E5=8C=BA?= =?UTF-8?q?=E5=9F=9F=E9=85=8D=E7=BD=AE=E5=B7=A5=E5=8D=95=20(#69)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...多边形区域与方向警戒线配置.md | 78 +++++++++++++++++++ wiki-docs.json | 4 + 2 files changed, 82 insertions(+) create mode 100644 docs/task/69-Sense多边形区域与方向警戒线配置.md diff --git a/docs/task/69-Sense多边形区域与方向警戒线配置.md b/docs/task/69-Sense多边形区域与方向警戒线配置.md new file mode 100644 index 0000000..822cfcd --- /dev/null +++ b/docs/task/69-Sense多边形区域与方向警戒线配置.md @@ -0,0 +1,78 @@ + +generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) +wiki_page: Task-69-Sense多边形区域与方向警戒线配置 +wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-69-Sense%E5%A4%9A%E8%BE%B9%E5%BD%A2%E5%8C%BA%E5%9F%9F%E4%B8%8E%E6%96%B9%E5%90%91%E8%AD%A6%E6%88%92%E7%BA%BF%E9%85%8D%E7%BD%AE.- +wiki_revision: 53b292035e7748aece5cf0884ecf1d9690533346 +synchronized_at: 2026-08-15T01:19:36Z + + +# 69 Sense 多边形区域与方向警戒线配置 + +- 类型：需求 +- 所属 Epic：#7 +- 所属 MVP：#8 +- 状态：待验收 +- 日期：2026-08-15 +- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/69 +- 评审 PR：https://git.ilapage.cn/ila/yovision/pulls/87 + +## 背景与目标 + +在 #61 冻结的 GoAdmin/go-admin-ui 源码派生基线上，为网管和非技术实施人员提供绑定 Device/Profile/分辨率的危险区域与方向警戒线配置。配置必须可追溯、能识别视频 Profile 变化，并且 Brain、Bell 不启动时可独立管理和预览。 + +## 最终方案 + +- 新增当前区域定义与不可变版本表；创建为 v1，编辑、启停和重新校准均追加版本，不覆盖历史。 +- 服务层在 PostgreSQL 事务内锁定当前定义并校验 `expectedVersion`；并发保存只允许一方成功，另一方返回稳定 409 冲突。 +- 服务端根据监看路由解析 Device/Profile，保存归一化坐标和冻结的 Profile token、分辨率、编码等非敏感快照；不信任客户端提交的绑定元数据。 +- 多边形支持 3–64 个点并拒绝越界、零面积、自交和重叠边；方向线固定两个点并记录正向/反向。 +- admission 完成 Profile 替换后按 token、分辨率和编码比较，主动标记 `needs_recalibration`；读取时也保守识别 Profile 缺失、未验证或发生变化。 +- 前端复用 go-admin-ui 的 BasicLayout、Axios、Element Plus 搜索、表格、分页、表单、Dialog、Tag、Alert 和权限按钮，仅新增视频坐标几何编辑器。 +- 编辑器支持鼠标点选/拖动，以及键盘 Enter/Space 加点、方向键移动、Delete/Backspace 删除；提供可见焦点、文字错误、撤销、清空和未保存关闭确认。 +- 权限沿用 GoAdmin Casbin：viewer 只读，implementation_operator/site_admin 可写；页面预览复用 #68 的实时监看会话。 + +## 修改文件 + +- `Sense/server/app/sense/area/**`：模型、DTO、几何校验、服务、API 与测试。 +- `Sense/server/cmd/migrate/migration/version/2026081509000_area*`：表、菜单、权限迁移及测试。 +- `Sense/server/app/admin/router/sense_area.go`：区域 API 路由。 +- `Sense/server/app/sense/admission/service*.go`：Profile 替换触发重新校准。 +- `Sense/ui/src/views/sense/area/**`、`Sense/ui/src/api/sense/area.js`：区域管理页面、请求与载荷。 +- `Sense/ui/src/components/sense/geometry-editor/**`：业务专用几何编辑器。 +- `Sense/ui/tests/unit/sense/area*.spec.js`：载荷、几何和页面行为单测。 +- Wiki 的 Architecture、Business Rules、Local Development、Troubleshooting：记录架构、规则、验证和排错；`docs/` 为同步镜像。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 多边形与方向线几何校验、版本并发和审计成立 | 通过 | +| 配置绑定明确的 Device/Profile/分辨率 | 通过 | +| Profile、分辨率或能力变化触发 needs_recalibration | 通过 | +| 旧版本可追溯且不能被静默覆盖 | 通过 | +| 画布键盘/鼠标操作、错误反馈和视觉风格一致 | 通过 | +| Brain/Bell 未启动时可独立保存、读取和预览配置 | 通过 | + +## 测试 + +- `go test ./...`：通过。 +- `go vet ./...`：通过。 +- `go build ./...`：通过。 +- `go test -race ./app/sense/area ./app/sense/admission`：通过。 +- PostgreSQL 17 实库：迁移、3 个菜单、10 条 Casbin 策略及并发更新测试通过；并发结果为一次成功、一次冲突、两个版本。 +- `pnpm lint`：通过，0 error；保留 32 个冻结上游 warning。 +- `pnpm test:unit`：16 suites / 45 tests 通过。 +- `pnpm build:prod`：通过，保留 6 个冻结上游 warning。 +- Edge/Playwright 浏览器烟测：鼠标绘制、键盘移动/删除和 ARIA 错误提示通过。 +- Brain、Bell 未启动，独立后端与前端验证通过。 +- **未验证部分**：客户现场授权摄像头、实际部署反向代理及目标客户浏览器上的端到端人工操作尚未验证，留给本工单人工验收或后续集成验收。 + +## 遗留问题 + +- Sense→Brain 的版本化区域配置发布属于后续共享契约工单，本工单未写入 `contracts/`，不阻塞 Sense 独立配置能力。 + +## 相关提交 + +- `17bd383` feat: 重建 Sense 区域与警戒线配置 (#69) +- `f82dd51` docs: 记录 Sense 区域配置架构 (#69) +- `bb964ac` docs: 归档 Sense 区域配置工单 (#69)（本次归档提交，随后同步完整 Wiki 内容） diff --git a/wiki-docs.json b/wiki-docs.json index f251e76..9eab71e 100644 --- a/wiki-docs.json +++ b/wiki-docs.json @@ -123,6 +123,10 @@ { "page": "Task-68-Sense单路实时监看与播放状态反馈", "path": "docs/task/68-Sense单路实时监看与播放状态反馈.md" + }, + { + "page": "Task-69-Sense多边形区域与方向警戒线配置", + "path": "docs/task/69-Sense多边形区域与方向警戒线配置.md" } ] }