Mike-Solar
c486c853ff
Complete documentation set for the facade migration (B1-R6) and beyond: facade-migration-roadmap, handoffs v3-v6, R5 guides, R6 cleanup plan, R7 pure-ABI plan, long-term plans (riir/ai-agent/gtest/ui-redesign), updated Chinese README draft, UI design mockups, and the Google Test + struct-typedef rules in CONTRIBUTING.
214 lines
14 KiB
Markdown
214 lines
14 KiB
Markdown
# Oak 主界面 UI 改版计划
|
||
|
||
> 本文是主界面重新设计的执行手册，面向 DeepSeek Flash（**不识字图，本文全部
|
||
> 用文字精确定义目标形态**）。详细程度对齐 `../r5-app-migration-guide.md`。
|
||
> 工作分支：`c-abi-migration`。**启动前提：R5（C ABI app 侧迁移）验收完成之
|
||
> 后**；启动后可与 Google Test 统一迁移并行——协调规则见 §2。
|
||
> 依据：`design/Oak-UI设计图-主界面-标注版.png`、`...-效果栈版.png`、
|
||
> `...-节点编辑器版.png`（共 10 项关键改动，本文逐项落地）。
|
||
|
||
---
|
||
|
||
## 1. 目标布局（文字定义，照此实现）
|
||
|
||
```
|
||
┌ 菜单栏：文件(F) 编辑(E) 视图(V) 回放(P) 序列(S) 窗口(W) 工具(T) 帮助(H)
|
||
├ 工具条(31px)：14 个工具图标 + 吸附开关 + 缩放滑块 + 轨道高度滑块
|
||
├────────────────────────────────────────────────────────────────────
|
||
│ 素材查看器(源) │ 序列查看器(节目) │ 检查器│历史记录
|
||
│ ·适合/安全框 │ ·适合/安全框 │ ┌──────────────────┐
|
||
│ ·独立走带控制 │ ·节点编辑器(同组切换)│ 媒体 · xxx.mp4 │
|
||
│ ·1920×1080·25FPS │ ·分辨率·帧率信息 │ ▼ │
|
||
│ │ │ ≡ 变换 ✓ ×(卡片) │
|
||
│ │ 26px电平条(右缘) │ ≡ OCIO LUT ✓ ×(卡片)│
|
||
│ │ │ [+ 添加效果] │
|
||
│ │ │ └──────────────────┘
|
||
├────────────────────────────────────────────────────────────────────
|
||
│ 时间线(全宽贯通) │
|
||
│ 轨道头180px │ 轨道区 │
|
||
│ V2 视频轨道1 [锁定][显示] ████████ │
|
||
│ V1 视频轨道0 [锁定][显示] ████████████ │
|
||
│ A1 音频轨道0 [锁定][静音][独奏] ▁▂▃▅▂▁ │
|
||
│ A2 音频轨道1 [锁定][静音][独奏] ▁▂▁▃▂▁ │
|
||
├────────────────────────────────────────────────────────────────────
|
||
│ 状态栏：就绪 | 缓存:已启用 | 代理:关 | 自动保存:3分钟前 || 时间码/时长 | 25FPS | 1920×1080
|
||
└────────────────────────────────────────────────────────────────────
|
||
```
|
||
|
||
节点编辑器视图（与序列查看器同组切换、占中央最大面板）：
|
||
```
|
||
┌ 节点编辑器（中央最大面板）
|
||
│ [+] [-] [适配] ┌ 检查器(同效果栈) ┐
|
||
│ ┌ 第一稿.mp4[视频] · 00:00:00:00–00:04:18:18 ┐ │ │
|
||
│ │ [媒体]→[变换]→[OCIO LUT]→[输出] │ │ │
|
||
│ └───────────────────────────────────────┘ │ │
|
||
│ ┌ 第一稿.mp4[音频] · 00:00:00:00–00:04:18:18 ┐ │ │
|
||
│ │ [媒体]→[音量]→[输出] │ │ │
|
||
│ └───────────────────────────────────────┘ │ │
|
||
│ ┌ 小地图 ┐ │ │
|
||
└────────────────────────────────────────────────────────────────────
|
||
```
|
||
|
||
**核心原则：效果栈（检查器）与节点图是同一份节点数据的两种视图**——检查器按
|
||
「媒体 → 变换 → OCIO LUT → 输出」自上而下线性排卡片；节点编辑器把同一份数据
|
||
画成图。默认用户像传统软件一样在检查器里线性工作，需要分支合成时切到节点
|
||
编辑器。
|
||
|
||
## 2. 执行前提与并行协调
|
||
|
||
### 2.1 执行前提：R5 验收完成后启动
|
||
|
||
**本计划在 R5（C ABI app 侧迁移）验收完成之前不启动。** 这不是保守，是
|
||
依赖关系：
|
||
|
||
- WP4（检查器·效果栈）落在 `app/widget/nodeparamview/`、WP2（时间线轨道
|
||
头）落在 `app/widget/timelinewidget/`、WP5（节点编辑器移位）落在
|
||
`app/widget/nodeview/`——这些都是 R5 符号消除的主战场。R5 先把这些文件
|
||
的 engine 调用点换到 facade（行为不变），本计划再在其上做 UI 重构，
|
||
面对的才是干净的 facade 边界；提前动手只会和 R5 互相踩踏。
|
||
- R5 完成后不存在文件重叠问题，**全部 WP 无需错峰**，按 §4 顺序执行即可。
|
||
|
||
启动时仍需遵守的红线（R5 的成果，永久有效）：
|
||
|
||
- **禁止**：在本计划里改 `oakengine_*` 签名、新建 engine 命令类、或把
|
||
engine 源码再编进 app。
|
||
- 全部改动限 **app 侧 UI 代码**（`app/`），不加 engine 符号。
|
||
|
||
### 2.2 与 Google Test 统一迁移（`gtest-migration-guide.md`）的并行协调
|
||
|
||
**结论：可以完全并行，无错峰要求。** 两份计划的文件域不相交：
|
||
|
||
| 计划 | 动的文件 |
|
||
|---|---|
|
||
| UI 改版（本文） | `app/`（widget、panel、window、dialog、ts 翻译） |
|
||
| GTest 统一迁移 | `tests/`、`engine/tests/`、`core/tests/` 及三处测试 CMake |
|
||
|
||
唯一的接触点与规则：
|
||
|
||
- **`tests/gtest/`**：GTest 迁移明确"不动已有 gtest"；本计划 §5 要求新增
|
||
UI 逻辑用例，新用例**直接加进 `tests/gtest/` 现有 `olive-gtest` 目标**，
|
||
不新建测试二进制。两边若同时改 `tests/gtest/CMakeLists.txt`，后提交者
|
||
普通三路合并即可（都是追加行，不会语义冲突）。
|
||
- **ctest 基线**：GTest 迁移的硬门槛是"用例总数只增不减"；本计划只**新增**
|
||
用例、不删不改旧用例，天然满足。两边都以全量
|
||
`ctest --output-on-failure` 绿为提交前提，谁先跑谁后跑无所谓。
|
||
- **共享入口约定**：ctest 仍是唯一运行入口（gtest 仅编写框架），本计划
|
||
新增用例同样遵守，不引入别的测试框架或独立 runner。
|
||
- **已知 flaky**（`oak_cli_transcode`、`oakengine_export_test`、
|
||
`olive-gtest` 单次失败需单独重跑）是两个计划共同的背景噪音，判定规则
|
||
相同：单独重跑一次，连续两次失败才算回归。
|
||
|
||
## 3. 工作包（WP1–WP10，对应设计图 10 项）
|
||
|
||
### WP1 取消独立「工具」面板 → 31px 工具条
|
||
- **现状**：`app/panel/tool/tool.{h,cpp}` 是独立停靠面板，~8% 屏幕仅放 14 个图标。
|
||
- **目标**：删除该面板；在时间线（`app/widget/timelinewidget/`）上方加一条 31px
|
||
工具条，承载 14 个工具图标 + 吸附开关 + 缩放滑块 + 轨道高度滑块。
|
||
- **文件**：删/改 `app/panel/tool/`；`app/widget/timelinewidget/timelinewidget.{h,cpp}`
|
||
顶部加工具条；`app/panel/CMakeLists.txt`、`app/panel/panelmanager.cpp` 注册点。
|
||
- **验证**：工具条全部按钮功能与原面板一致；布局保存/恢复无该面板。
|
||
|
||
### WP2 时间线全宽贯通 + 轨道头 180px
|
||
- **现状**：时间线未全宽；轨道头窄，无统一的 显示/静音/独奏/锁定 与 V/A 编号命名。
|
||
- **目标**：时间线全宽；轨道头加宽至 180px 贴住轨道；视频轨「显示」、音频轨
|
||
「静音/独奏」、统一「锁定」；轨道以 `V2/V1/A1/A2` 编号 + 用途名（与主流 NLE 一致）。
|
||
- **文件**：`app/widget/timelinewidget/`（timelinewidget、trackview、trackviewitem、
|
||
timelineview）。**前提：R5 已完成 Track/ClipBlock facade 化，本 WP 在其上重构。**
|
||
- **验证**：轨道头控件改变 track 的 lock/mute/solo/show 状态；命名正确；全宽布局。
|
||
|
||
### WP3 双监看并列（源 + 节目）
|
||
- **现状**：`app/panel/footageviewer/`（源）与 `app/panel/sequenceviewer/`（节目）分开，
|
||
审素材对位需切换标签。
|
||
- **目标**：左右并排常显；素材查看器带独立走带控制（transport）。
|
||
- **文件**：`app/window/mainwindow/mainwindow.cpp` 布局；`app/panel/footageviewer/`、
|
||
`app/panel/sequenceviewer/`（KDDockWidgets 分组/dock 关系）。
|
||
- **验证**：两查看器同屏并列；源查看器独立走带；布局可保存/恢复。
|
||
|
||
### WP4 参数编辑器 → 「检查器·效果栈」
|
||
- **现状**：`app/widget/nodeparamview/` 是参数编辑器（item 列表 + 标题栏 + 关键帧控件）。
|
||
- **目标**：改为「检查器」面板（与「历史记录」同组标签）。自上而下线性排：
|
||
「媒体 · xxx.mp4」源卡 + 效果卡（变换、OCIO LUT、音量…）。**卡片规范**：
|
||
标题行 = ≡(拖拽排序) ▼(折叠) 名称 ✓(启停) ×(移除)；底部「+ 添加效果」即搜即加。
|
||
每属性行右侧保留关键帧按钮（现 `nodeparamviewkeyframecontrol`）。
|
||
- **文件**：`app/widget/nodeparamview/`（nodeparamview、nodeparamviewitem、
|
||
nodeparamviewitemtitlebar、nodeparamviewdockarea、nodeparamviewwidgetbridge）；
|
||
新增「检查器」容器/卡片模型。**前提：R5 已完成 Node 大族 facade 化，本 WP 在其上重构。**
|
||
- **验证**：卡片折叠/拖拽排序/启停/移除全部生效且写入节点图（undoable）；
|
||
与节点编辑器视图数据一致；「+ 添加效果」可搜可加。
|
||
|
||
### WP5 节点编辑器移至中央最大面板 + 缩放/小地图
|
||
- **现状**：`app/widget/nodeview/` 节点编辑器非中央主区，大图易迷路。
|
||
- **目标**：移到中央最大面板（与序列查看器同组切换）；新增缩放控件（+/−/适配）
|
||
与右下角小地图。
|
||
- **文件**：`app/widget/nodeview/`（nodeview、nodeviewcontext、nodeviewminimap）、
|
||
`app/panel/node/`、`app/window/mainwindow/mainwindow.cpp`。**前提：R5 已完成 Node 大族 facade 化，本 WP 在其上重构。**
|
||
- **验证**：节点编辑器占中央；缩放/适配/小地图可用；大图导航不迷路。
|
||
|
||
### WP6 音频监视器 → 26px 电平条
|
||
- **现状**：`app/widget/audiomonitor/`、`app/panel/audiomonitor/` 占一个完整面板。
|
||
- **目标**：改为 26px 超薄电平条，贴附在节目查看器右侧常显，释放一个面板。
|
||
- **文件**：`app/widget/audiomonitor/`、`app/panel/sequenceviewer/`（宿主）、
|
||
`app/panel/audiomonitor/`（去面板化）。
|
||
- **验证**：电平条 26px 常显、随播放电平跳动；原面板释放；布局可恢复。
|
||
|
||
### WP7 新增全局状态栏
|
||
- **现状**：`app/window/mainwindow/mainstatusbar.{h,cpp}` 仅显示 TaskManager 摘要。
|
||
- **目标**：全局状态栏显示：就绪状态、缓存、代理、自动保存时间（左）；
|
||
当前时间码/时长、帧率、分辨率（右）。
|
||
- **文件**：`app/window/mainwindow/mainstatusbar.{h,cpp}`、`app/window/mainwindow/
|
||
mainwindow.cpp`。
|
||
- **验证**：各项信息实时刷新；与序列状态/缓存/代理/自动保存一致。
|
||
|
||
### WP8 查看器细节
|
||
- **现状**：填充条为蓝色；缩放/安全框入口不全；信息芯片不全；有与时间线重复的标尺。
|
||
- **目标**：填充条改黑；查看器右上角提供缩放与安全框按钮；信息芯片标注
|
||
分辨率与帧率；移除与时间线重复的标尺。
|
||
- **文件**：`app/panel/footageviewer/`、`app/panel/sequenceviewer/`、
|
||
`app/widget/viewer/`（viewer、viewerdisplay）。
|
||
- **验证**：外观与信息符合 §1 描述；无重复标尺。
|
||
|
||
### WP9 菜单访问键补全
|
||
- **现状**：`app/window/mainwindow/mainmenu.{h,cpp}` 的「窗口」无访问键 (W)。
|
||
- **目标**：「窗口」加 `(W)`，与系统及其他菜单项一致。
|
||
- **文件**：`app/window/mainwindow/mainmenu.{h,cpp}`。
|
||
- **验证**：菜单访问键完整一致。
|
||
|
||
### WP10 文案与格式统一
|
||
- **现状**：History 未汉化；项目面板日期为英文格式；首选项有英文残留。
|
||
- **目标**：History → 历史记录；项目面板日期改 `YYYY-MM-DD HH:mm`（如
|
||
`2026-06-03 20:25`）；首选项英文残留（Behavior、Enable hover focus、
|
||
`1 minute(s)` 等）全部汉化。
|
||
- **文件**：`app/panel/history/`、项目面板（`app/widget/projectexplorer/`）、
|
||
首选项（`app/dialog/preferences/`）、`app/ts/*.ts` 翻译。
|
||
- **验证**：文案全部汉化、日期格式统一。
|
||
|
||
## 4. 执行顺序
|
||
|
||
R5 已验收完成（§2.1），无错峰约束。建议先做无依赖的布局项热身，再做
|
||
重构量大的三个 WP：
|
||
|
||
```
|
||
第一波（布局类，互相独立）: WP1 → WP3 → WP6 → WP7 → WP8 → WP9 → WP10
|
||
第二波（重构类，建议在 R5 facade 化后的干净边界上做）:
|
||
WP4（检查器）→ WP5（节点编辑器）→ WP2（时间线轨道头）
|
||
```
|
||
|
||
**每 WP 闭环**：现状 grep → 实现 → 全量构建 0 error → 全量 ctest 44/44 绿
|
||
（UI 改动不得引入回归）→ 立即提交 → roadmap 补记。
|
||
|
||
## 5. 测试要求（沿用项目规则）
|
||
|
||
- 所有测试用 **Google Test**（`CONTRIBUTING.md` 已立规）。
|
||
- 检查器卡片模型、效果栈↔节点图数据一致性、轨道头控件状态、状态栏信息、
|
||
工具条功能：补 Google Test 用例（`tests/gtest/`，`gtest_discover_tests`）。
|
||
- UI 行为改动以现有 `olive-gtest` 不回归为底线；新增可测逻辑（卡片模型、
|
||
视图模型）必须有单测。
|
||
- 需要显示的用例沿用 offscreen QPA；渲染相关用例沿用 `GTEST_SKIP` 模式。
|
||
|
||
## 6. 不做
|
||
|
||
- 不改 `oakengine_*` 公共 API（见 `riir.md` 的 API 冻结保证）。
|
||
- 不动 engine 内部实现、不动 R5 的 facade 工作。
|
||
- 不重写底层渲染/播放路径；本计划只改 UI 布局、容器与交互。
|
||
- 不做 AI 相关 UI（属 `ai-agent-design.md` 范围，另行）。
|