From 8388e8aeaa428936a6dc8a5e9f72bb8d13f4a53e Mon Sep 17 00:00:00 2001
From: QiuSW <ila2002@qq.com>
Date: Mon, 20 Jul 2026 22:24:38 +0800
Subject: [PATCH] docs: add V1 UI UX prototype spec

---
 docs/current-state.md             |  1 +
 docs/ui/silver-pose-ui-ux-spec.md | 98 +++++++++++++++++++++++++++++++
 progress.md                       |  9 +++
 3 files changed, 108 insertions(+)
 create mode 100644 docs/ui/silver-pose-ui-ux-spec.md

diff --git a/docs/current-state.md b/docs/current-state.md
index 9d3710c..8bd802f 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -10,6 +10,7 @@
 - 旧生产基线：`demo/main.py`、`demo/fall_detection_gui.py`、`demo/detect_fall.py`、`demo/best.pt`。
 - V1 代码：`v1/` 目录存在但尚无实现。
 - V2 代码：`v2/` 目录存在但尚无实现。
+- 非代码设计工件：`docs/ui/silver-pose-ui-ux-spec.md` 已建立，定义客户演示的正常、确认摔倒和连接异常三种 UI 状态；等待用户审阅后才生成 HTML 原型，不改变 Phase 1 任务顺序。
 - 测试：暂无 pytest 测试；`python -m compileall -q demo` 已通过。
 - 模型：`demo/best.pt` 可加载为 YOLO Pose，类别 `person`，`kpt_shape=[17, 3]`；与 `D:\PythonP\fall_detection\best.pt` 哈希一致。
 - 当前标准启动：`./init.ps1`。
diff --git a/docs/ui/silver-pose-ui-ux-spec.md b/docs/ui/silver-pose-ui-ux-spec.md
new file mode 100644
index 0000000..fd10885
--- /dev/null
+++ b/docs/ui/silver-pose-ui-ux-spec.md
@@ -0,0 +1,98 @@
+# 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. 仅用键盘可切换三种状态、关闭弹窗并看到可见焦点。
diff --git a/progress.md b/progress.md
index c9b5b27..c123ee5 100644
--- a/progress.md
+++ b/progress.md
@@ -25,3 +25,12 @@
 - 阻塞：无代码 blocker；V1 依赖清单、RTSP 实流录像和现场验收录像尚未创建。
 - 决策：`demo/` 作为旧基线保留；V1 使用 Python + PyQt5 + OpenCV + Ultralytics；V2 使用 Go，且必须以 V1 的录像回归集和 ONNX 一致性测试为迁移门槛。
 - 下一步：T-101。
+
+## 【2026-07-20】DESIGN UI/UX 客户演示原型规格
+
+- 状态：PARTIAL
+- 变更：创建 `docs/ui/silver-pose-ui-ux-spec.md`，定义离线 HTML 原型的正常监控、确认摔倒、连接异常状态、布局、视觉令牌、键盘操作和无障碍验收条件。
+- 验证：`./init.ps1` 通过；规格共 98 行，未发现 `TBD`、`TODO` 或 `REPLACE` 占位符，`git diff --check` 通过。
+- 阻塞：等待用户审阅已提交的规格；未生成 HTML，未变更 `demo/`、`v1/` 或任务看板状态。
+- 决策：原型为单页、无网络依赖的视觉与交互演示，使用虚构摄像头和事件数据，不表现为真实 RTSP 或模型推理。
+- 下一步：用户确认规格后，创建 `docs/ui/silver-pose-v1-prototype.html` 并执行离线交互验收。