docs: document Sense MVP operations (#22-#27)

2026-08-12 17:33:09 +08:00
parent e2e18b0380
commit 5177861c7c
4 changed files with 69 additions and 8 deletions
@@ -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: f16f2956d3d0f260501a356b5fe1087abdc5eaf5
-synchronized_at: 2026-08-12T08:50:52Z
+wiki_revision: 45c9a75d6044a918d7da6b236cb7b1625c5713e3
+synchronized_at: 2026-08-12T09:32:01Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -93,3 +93,18 @@ Sense/Brain 生成事件

 默认只注册工作台、健康检查和系统信息；go-admin 演示与代码生成菜单、路由和后端接口均未注册。正式启动默认要求独立 PostgreSQL；`memory` 只用于自动化测试和本地 smoke。
 <!-- sense-runtime:end -->
+
+<!-- sense-mvp:start -->
+## Sense MVP 模块地图
+
+Sense 后端功能以 `Sense/server/app/sense/` 为根，并通过 `Sense/server/cmd/sense/modules_<feature>.go` 独立注册：
+
+- `identity/`：Sense 独立账户、bcrypt 密码、会话、四角色 RBAC 与统一审计；签发者和受众只属于 Sense。
+- `device/`：Device 台账、状态、分页和 AES-256-GCM 凭据保险箱；读取模型只返回 `credential_configured`。
+- `adapters/onvif/`、`adapters/rtsp/`、`admission/`：获准网卡上的受控发现、手工 ONVIF 接入、Profile/StreamUri 读取和 RTSP 验证。
+- `adapters/mediamtx/`、`media/`：外部 MediaMTX 进程所有权、localhost Control API、媒体期望态与实际态对账。
+- `liveview/`：绑定当前用户、最长两分钟的单路播放会话；只投影媒体路径，不暴露源 URI 或摄像机秘密。
+- `area/`：归一化多边形/方向警戒线、不可变版本、并发版本校验和分辨率变化后的重新校准。
+
+前端在 `Sense/ui/src/{api,views,router/modules,components}/sense/` 使用对应模块；通用页面复用 Element Plus 表单、表格、分页、Dialog、Tag 和应用容器，只为播放器与区域画布新增局部业务组件。项目内 `identity.RecordAudit`、`device.ReadCredential`、`admission.VerifiedProfile`、`media.PlaybackRoute` 和 `area.ExportCurrent` 是窄适配端口，不是跨项目契约。
+<!-- sense-mvp:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 7a9645a7ca7f4b3478d27afb2d441238431f501e
-synchronized_at: 2026-08-11T10:30:38Z
+wiki_revision: 36a49f985cdd6ebd93759273fbc53158ba13b152
+synchronized_at: 2026-08-12T09:32:06Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -66,3 +66,17 @@ synchronized_at: 2026-08-11T10:30:38Z
 - 三个交付单元的正式版本与发布流程。

 未确认项不得从旧代码或模板默认值推断为当前事实。
+
+<!-- sense-mvp:start -->
+## Sense MVP 业务与安全规则
+
+- **Sense 账户**：只登录 Sense；不得接受 Bell JWT、Cookie 或用户数据。角色为系统管理员、实施/运维、站点管理员和只读用户，后端权限是最终边界。
+- **安全初始化**：系统不提供默认账户、默认密码或默认签名密钥；首次管理员由仓库外一次性令牌创建。
+- **Device**：设备不可变逻辑 ID 是后续 Profile、媒体和区域的内部引用。非视频适配器未实现时必须显示 `adapter_not_ready`。
+- **摄像机凭据**：只写不读，使用仓库外 32 字节密钥加密；不得进入 URL、日志、审计、工单或响应。
+- **受控发现**：ONVIF Discovery 默认关闭，只有显式设置获准本机 IP 才能发送发现；不得扫描未授权网段。
+- **Profile**：主辅码流按分辨率分类并分别验证；认证失败、不可达、超时与校时问题使用可定位状态。
+- **MediaMTX**：保持外部进程。Sense 只停止自己启动并持有句柄的进程，最多自动重启三次；摄像机凭据只在 localhost 控制请求中瞬时组装，不持久化、不返回。
+- **播放会话**：由当前 Sense 用户创建，最长两分钟；设备分页和媒体路径不以 16 路作为硬上限，页面一次只打开一路流。
+- **区域版本**：坐标为 0..1 归一化值，并绑定 Device、Profile、宽高。每次发布或停用形成新版本；范围、点数、自交、退化、方向和期望版本由后端校验。Profile 分辨率变化后旧版本必须标记为需要重新校准。
+<!-- sense-mvp:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: 632e07b6cd22f6e3ae07c23ed58439ea2beecff2
-synchronized_at: 2026-08-11T10:30:46Z
+wiki_revision: 3ee073ae07bb2ab04f02b1178b6d289f6f5a2063
+synchronized_at: 2026-08-12T09:32:15Z
 <!-- gitea-wiki-mirror:end -->

 # 故障排查
@@ -39,3 +39,22 @@ synchronized_at: 2026-08-11T10:30:46Z
 - 契约破坏性变化没有新版本、迁移和回退方案；
 - 涉及删除、不可逆迁移、发布或生产变更但没有明确授权；
 - 工作区出现来源不明且与当前任务重叠的修改。
+
+<!-- sense-mvp:start -->
+## Sense MVP 排错
+
+| 现象/状态 | 检查与处理 |
+|---|---|
+| 启动提示缺少 `SENSE_DATABASE_URL` | 正式模式必须提供独立 PostgreSQL URL；只有测试/smoke 可显式使用 `memory`。 |
+| 登录统一提示用户名或密码错误 | 为避免枚举账户，失败响应不区分用户不存在、密码错误或账户停用；由管理员查看审计。 |
+| `adapter_not_ready` | 当前设备类型尚无适配器，不代表网络故障；首期完整支持 video。 |
+| `discovery_unavailable` | 未设置获准的 `SENSE_ONVIF_DISCOVERY_IP`，或该 IP 不属于本机网卡。可改用手工 ONVIF 地址。 |
+| `authentication_failed` | 在设备管理中重新写入凭据后再次执行接入检查；不要把凭据写进地址。 |
+| `clock_skew` | 校准摄像机时间后重新探测。 |
+| `process_failed` | 检查仓库外 `SENSE_MEDIAMTX_BINARY`、基础配置和进程退出原因；达到三次重启上限后需人工处理。 |
+| `apply_failed` / `unconverged` | 检查 localhost Control API 是否启用并为 v3；确认媒体路径和外部进程状态。 |
+| 画面等待、断开或会话过期 | 先在视频服务执行对账，再重新连接；播放会话最长两分钟。 |
+| 区域提示需要重新校准 | Profile 分辨率已变化，按新画面重新绘制并发布新版本，不能静默复用旧坐标。 |
+
+自动测试不访问真实摄像头或未授权网络。PostgreSQL、MediaMTX、目标浏览器与实验室摄像机的联合验证必须在获准部署环境完成。
+<!-- sense-mvp:end -->
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Delivery-Documentation-Guide
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Delivery-Documentation-Guide.-
-wiki_revision: e0b43bfada515ff95831debc4378de41a8ad969a
-synchronized_at: 2026-08-11T10:31:06Z
+wiki_revision: 9847e4c065e513107f8f79617c6529a8300874cb
+synchronized_at: 2026-08-12T09:32:40Z
 <!-- gitea-wiki-mirror:end -->

 # 交付文档指南
@@ -78,3 +78,16 @@ synchronized_at: 2026-08-11T10:31:06Z
 ## 不在本页解决的内容

 开发任务怎样建单、实施和归档见[开发工作流](Development-Workflow.-)；代码结构和维护入口见[架构与代码地图](Architecture-and-Code-Map.-)。本页不规定市场宣传、合同、法务或商务承诺。
+
+<!-- sense-mvp:start -->
+## Sense MVP 岗位操作路径
+
+Sense 面向网管、实施人员和非技术现场人员，菜单按日常任务组织：工作台 → 设备管理 → 视频接入 → 视频服务 → 实时监看 → 区域与警戒线。普通操作优先展示中文状态与下一步，不要求用户理解 ONVIF、RTSP 或 MediaMTX 内部模型。
+
+- 系统管理员：完成一次性安全初始化，维护 Sense 用户与角色，查看操作记录。
+- 实施/运维：添加设备、只写更新凭据、在获准网卡发现或手工接入、检查主辅码流、处理媒体进程与对账。
+- 站点管理员：查看/维护站点设备，实时监看，绘制和发布区域版本；无权创建系统管理员。
+- 只读用户：查看设备、媒体状态、实时画面和区域，不能修改。
+
+交付验收必须使用仓库外测试账户和获准实验室设备；文档、截图、工单和日志不得包含摄像机密码、Cookie、令牌、含凭据 URI 或客户真实画面。当前自动化已覆盖内部状态和安全边界；真实 PostgreSQL、MediaMTX、摄像机兼容与目标浏览器画面仍需实施人员验证。
+<!-- sense-mvp:end -->