docs: 归档 Sense 区域配置工单 (#69)

docs/task/69-Sense多边形区域与方向警戒线配置.md

@@ -0,0 +1,78 @@
+<!-- gitea-wiki-mirror:start -->
+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
+<!-- gitea-wiki-mirror:end -->
+
+# 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 内容）

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"
     }
   ]
 }