silver_pose/docs/ui/silver-pose-ui-ux-spec.md

# Silver Pose V1 UI/UX 原型规格

## 目标与边界

本规格定义一个用于客户演示的 Windows 桌面端视觉原型。它展示 V1 单路海康 RTSP 监控的操作闭环：人员姿态可见、正常状态可读、确认摔倒后有红色画面、一次性声音/弹窗提示和截图证据。

- 目标框架：Windows 上的 PyQt5；HTML 仅作离线交互视觉原型，不替代生产 UI。
- 默认窗口：1280 × 800 epx；支持最小 960 × 640、Windows Snap 宽度和 125%/150% 缩放。
- 语言：简体中文；数据均为虚构演示数据，不包含 RTSP 地址、账号、客户图像或真实事件。
- 范围：单路摄像头、实时监控、确认摔倒告警、连接异常提示和最近事件。
- 不在范围：真实 RTSP、模型推理、音频播放、文件系统写入、设置编辑、云端通知及历史事件库。

## 信息架构与窗口模型

使用一个主窗口和一个只在首次确认事件出现时显示的警报弹窗。主窗口不使用多级导航：客户演示的主要任务是观看实时画面并理解事件证据，设置与历史管理不是此轮原型的重点。

```text
主窗口
├── 标题与来源栏：产品名、摄像头名称、连接状态、当前时间
├── 演示状态切换：正常监控 / 确认摔倒 / 连接异常
├── 实时画面：视频占位、人员 ID、骨架、每人状态与 FPS
├── 事件证据栏：状态说明、触发条件、报警副作用、截图路径
└── 最近事件：最近一次事件、保存结果和操作入口

确认摔倒弹窗
├── 明确的“确认摔倒”标题和人员 ID
├── 确认时间、确认延迟、截图结果
└── “我已知晓”按钮；不产生新的事件或改变状态机
```

## 布局与响应式行为

大于等于 1008 epx 时，内容采用 8:4 双栏：左侧为固定 16:9 比例的实时画面，右侧为状态和证据卡；最近事件横跨底部。641–1007 epx 时，右栏缩窄并保留画面优先级；小于等于 640 epx 时，右栏移至画面下方，顶部操作换行，保证状态与主操作仍可见。

- 顶部栏高度 56 epx；使用系统标题栏相近的紧凑密度。
- 内容间距使用 4 epx 网格，常用间距为 8、12、16、24 epx。
- 状态切换按钮显式带文字，普通鼠标、触摸、键盘均可触发。
- 确认状态在画面上放置红色边框、文字标签和事件编号，不仅改变颜色。
- 连接异常不显示摔倒标签；画面保留最后一帧占位并覆盖“正在重连”的明确文字。

## 控件与命令

| 目的 | 原型控件 | 最终 PyQt5 对应 | 行为 |
| --- | --- | --- | --- |
| 切换展示状态 | 三个有文字的按钮 | `QPushButton` 组 | 鼠标、Enter/Space、数字键 1/2/3 切换。 |
| 启动/停止监控 | 主操作按钮 | `QPushButton` | 原型只变更按钮文案；正式版调用视频源线程。 |
| 查看截图位置 | 普通按钮 | `QPushButton` | 原型显示路径提示；正式版打开事件目录。 |
| 关闭告警弹窗 | “我已知晓” | `QDialogButtonBox` / `QPushButton` | 只关闭视图，不清除事件或停止报警记录。 |
| 最近事件 | 只读列表 | `QListView` 或轻量卡片 | 正式版读取 JSONL 摘要，不作为数据库表格。 |

## 视觉令牌

采用克制的深色控制台主题，以视频画面和告警信息为主。最终 PyQt5 应将这些令牌集中到 QSS/主题资源，不在控件中散落硬编码色值。

| 语义 | 值 | 用途 |
| --- | --- | --- |
| `surface.base` | `#0B1220` | 窗口背景 |
| `surface.layer` | `#131F32` | 卡片与工具栏 |
| `surface.overlay` | `#19283D` | 弹窗与画面信息层 |
| `text.primary` | `#F5F8FC` | 标题与正文 |
| `text.secondary` | `#A9B8CC` | 辅助说明 |
| `status.success` | `#49D17D` | 在线 / NORMAL |
| `status.caution` | `#F4C95D` | SUSPECT |
| `status.critical` | `#FF5C6C` | CONFIRMED / 截图失败 |
| `status.offline` | `#99A5B6` | 断流 / 不可用 |
| `accent.default` | `#70A5FF` | 非危险主操作与键盘焦点 |

字体采用 `Segoe UI Variable`、`Microsoft YaHei UI`、sans-serif 回退；数字采用等宽特性。圆角为 8 epx，焦点描边为 2 epx 蓝色，不使用装饰性动效或 emoji 图标。

## 状态与交互矩阵

| 状态 | 画面 | 右栏 | 弹窗与声音 | 用户下一步 |
| --- | --- | --- | --- | --- |
| 正常监控 | 深色视频占位、绿色骨架、`NORMAL` 标签 | 来源在线、人员 ID、FPS、无待处理事件 | 无 | 持续观察或切换展示状态。 |
| 确认摔倒 | 红色外框、红色骨架、`CONFIRMED` 与事件 ID | 显示证据、确认延迟、声音已触发、截图已保存 | 首次进入时显示一次弹窗；之后不重复 | 知晓警报、查看截图位置、继续监控。 |
| 连接异常 | 灰色画面与“正在重连”说明 | 显示重试计时与“不触发摔倒报警” | 无 | 等待或停止监控；恢复后回到正常。 |

切换展示状态不代表真正的算法判定；原型的页内说明必须明确“演示数据”。确认状态下关闭弹窗后，红色状态和事件证据仍保留，模拟事件状态的可追溯性。

## 无障碍与输入

- 所有状态同时包含颜色、图标形状和中文文字；状态文字对比度不低于 4.5:1。
- Tab 顺序：状态切换 → 启动/停止 → 查看截图 → 最近事件 → 弹窗确认按钮。
- `1`、`2`、`3` 是原型专用演示快捷键；Escape 只关闭可关闭的弹窗。
- 状态变化通过 `aria-live="polite"` 说明；弹窗打开时焦点置于“我已知晓”，关闭后返回切换按钮。
- 按钮最小高度 40 epx；支持 200% 缩放下文字换行与内容垂直滚动。

## 实现与验收

原型输出为 `docs/ui/silver-pose-v1-prototype.html`，单文件、无网络依赖。CSS 令牌、示意画面 SVG 和 JavaScript 状态数据均内联；JavaScript 只负责状态切换、弹窗和快捷键，不能伪装成视频或模型推理。

验收条件：

1. 双击 HTML 可离线打开；默认显示正常监控。
2. 点击“确认摔倒”或按 `2` 后，显示红色画面、告警证据和一次弹窗；关闭弹窗后不丢失事件证据。
3. 点击“连接异常”或按 `3` 后，仅显示重连状态，且明确说明未触发报警。
4. 宽屏、约 900 epx 宽和约 600 epx 宽均不出现横向溢出或无法触达的主操作。
5. 仅用键盘可切换三种状态、关闭弹窗并看到可见焦点。