# Design Plan — Perfowl Mac v1

## 1. Subject

- 产品：Perfowl 原生 macOS 无侵入性能测试客户端。
- 受众：iOS 性能测试人员、研发和性能质量团队。
- 本文件/首批页面的单一任务：在一个 PerfDog 式工作台中连接 iOS 设备、获取 User App、选定目标并开始/结束一次无侵入性能测试，同时用低频设备截图和共享时间轴持续确认测试上下文。
- 第二阶段增量：开始按钮已开放；目标 App 由用户自行运行，Perfowl 等待并按 executable/PID/generation 绑定，不主动启动目标 App。
- 2026-09-03 设计增量：加入 USB 连接/断开瞬时反馈、顶部设备截图区、PerfDog 同名指标选择面板、右下角悬浮 `＋`，并将默认图表固定为 `FPS / CPU Usage / Network`。

## 2. Tone

- surface: b_end
- 气质：utilitarian-enterprise，但作为桌面工具使用深色实时监控工作台语言。
- 参考气质：参考图的左侧选择链 + 右侧共享时间轴，去掉账号、多平台和工具箱噪音。

## 3. Token

### Color

- primary: `#2F83FF`
- brand_watch: `#55D2C1`
- page_bg: `#0B1020`
- sidebar_bg: `#0D1424`
- surface: `#141C2E`
- surface_raised: `#19233A`
- border: `#29344D`
- divider: `#202A40`
- text_primary: `#E8EEFF`
- text_secondary: `#9EABC6`
- text_tertiary: `#6F7C98`
- success: `#45C486`
- warning: `#F2B84B`
- danger: `#F0646E`

说明：B 端默认是浅色，本产品因长时间实时曲线监看和已给参考图，有理由改为深色工作台；不使用酸绿、紫蓝渐变或营销式高光。

### Typography

- body: PingFang SC 14/22
- data: SF Mono 12/18
- scale: 11 / 12 / 13 / 14 / 16 / 20
- 曲线数值与 Bundle ID 用 SF Mono，界面与中文用 PingFang SC。

### Spacing / Radius

- spacing_allowed: [4, 8, 12, 16, 24, 32]
- radius: button 6 / card 8 / max 8
- sidebar_width: 340px（桌面单屏工具的选择和详情复合栏，不是通用后台导航栏）
- default_shadow: none，分层靠描边和明度差

## 4. Layout

### mac-test-workbench — 测试工作台

- 页型: b_dashboard
- ASCII:

```text
┌─窗口标题 / Perfowl 标识 / 连接状态─────────────────┐
│ 左侧上下文 340                     │ 测试画布                    │
│ [设备选择器            ▾]          │ [场景名]               [▶]      │
│ [常规测试][深度分析][网络测试]    │ ┌─ 设备截图预览 ─────────┐ │
│ [测试应用选择器        ▾]          │ │ [USB 状态瞬时浮层]       │ │
│ [设备] [设置] [关于]                │ └──────────────────────┘ │
│ 信息            数值              │ ┌─ FPS / fps ───────────┐ │
│ Device / Target / Capture          │ ├─ CPU Usage ───────────┤ │
│ Samples / Route ...                │ │ APPCpu / TotalCPU       │ │
│ [状态 / 错误 / Session]            │ ├─ Network / Send / Recv ┤ │
│                                    │                       [＋]│
│                                    │ [日志栏 / sample count]          │
└───────────────────────────────────────────────┘
```

- regions: titlebar, context_sidebar, device_selector, mode_tabs, app_selector, details_tabs, device_summary, session_canvas, screenshot_preview, usb_status_toast, capture_control, live_metric_charts, metric_add_fab, metric_selector, status_bar

### 2026-09-03 交互增量

- **USB 状态浮层**：启动发现设备、连接成功、断开三个事件均使用顶端截图区中央浮层。事件确认后完整停留 1 秒再淡出；连续事件以后一个事件覆盖前一个并重置计时。浮层只做瞬时反馈，标题栏连接徽标和左侧设备上下文继续承担持久状态。
- **截图区**：位于 Scene 工具栏与指标区之间，保持设备纵横比并 `aspectFit`；无设备时显示明确空态。首版目标为 1 秒低频截图预览，不将它描述为实时视频镜像。只有启用 `ScreenShot` 指标时才写入 Session 媒体目录。
- **默认图表**：不论设备是否连接，首屏固定保留 `FPS`（`fps`）、`CPU Usage`（`APPCpu`、`TotalCPU`）、`Network`（`Send`、`Recv`）。未连接显示“等待设备”；已连接但数据源未实现或不可用显示 `Unsupported` 及原因，缺值不绘制为 0。
- **添加指标**：仅连接设备后在右下角显示悬浮 `＋`。点击打开覆盖式大面板；每行由复选框、彩色圆形图标、名称、说明构成；已选行用蓝色底；未支持项保留但禁用并标记“暂未支持”。`ScreenShot` 行额外显示 `采样频率 1 s`。
- **指标建模**：从“一项指标对应一条曲线”改为 `MetricPanelDefinition → [MetricSeriesDefinition]`。展示名与协议 `metricID` 分离，同一面板可组合多条曲线并逐条呈现质量状态。

### device-picker — 设备选择弹层

- 页型: b_list_page
- ASCII:

```text
┌─设备─────────────┐
│ Mobile                 │
│  设备名          [USB]  │
│  设备名          [Wi-Fi]│
│                         │
│ 仅显示当前发现的 iOS 设备 │
└─────────────────────────┘
```

- regions: picker_header, mobile_group, device_rows, device_empty_state

### app-picker — 应用选择弹层

- 页型: b_list_page
- ASCII:

```text
┌─应用─────────────┐
│ [查找应用             ] │
│ 已安装的应用        [↻] │
│ [图标] App Name          │
│ [图标] App Name          │
│ ...                     │
└─────────────────────────┘
```

- regions: search_field, installed_header, refresh_action, app_rows, app_loading_state, app_empty_state, app_error_state

## 5. Signature

- 元素：“猫头鹰观测眼”状态标识——两个眼形之间贯穿一条性能曲线。
- 落地规则：只出现在标题栏和连接空态；已连接时右眼点亮 brand_watch，不在每个面板重复。

## 6. Differentiation

相对 AI 默认 dashboard，本方案不用 KPI 卡片墙，而是用“设备 → App → 开测 → 结束并保存”的固定操作链驱动左侧上下文，右侧共享时间轴只呈现真实样本或明确等待态。

---

## Anti-Slop Review

- 日期: 2026-09-02
- surface: b_end
- 命中: B4（参考图是宽复合侧栏）。
- 修订: 将 340px 明确定义为“选择器 + 设备详情”复合操作区，不套用通用后台导航栏；删除账号卡、多平台分组、右上角四个无关工具和大面积装饰。
- A1: PASS——中文使用 PingFang SC，数据使用 SF Mono。
- A2: PASS——主色为 `#2F83FF`，无紫蓝渐变。
- A3: PASS——未使用 AI 默认三套皮。
- A4/A5: PASS——布局与猫头鹰观测眼直接服务 Perfowl 工作流。
- A6: PASS——差异化可用设备 → App → 开测操作链概括。
- B1: PASS——应用和设备均为扁平列表。
- B2: PASS——无 KPI 卡片。
- B3: PASS——无卡片阴影墙。
- B4: PASS——例外已由单屏复合操作区约束。
- B5: PASS——保持性能工具信息密度。
- B6: PASS——每屏仅“开始/结束测试”一个状态化 primary；采集中锁定设备与 App，避免目标上下文漂移。
- 香奈儿法则: 已删除参考界面中与首阶段无关的账号卡和右上角工具组。
- 2026-09-03 增量复审：截图区服务测试上下文确认；Toast 只在状态变化时出现；`＋` 是唯一新增浮动主动作；指标面板不新增 KPI 卡片、不使用装饰性渐变，未支持项不伪造数据。
- 结论: PASS