优化资源栏目悬浮分页交互

将资源栏目大纲改为不占画布宽度的悬浮 Dock，并统一栏目名称。实现有界滚轮分页队列，显式切页和拖动时取消待处理跳转。补充栏目切换、拖动取消和资源实时集成回归测试。同步更新资源自由画板技术方案与验收口径。
2026-08-23 18:47:07 +08:00
parent f3092c8bbc
commit d1e2daace7
6 changed files with 360 additions and 84 deletions
@@ -2,7 +2,7 @@

 ## 目标

-资源管理在空项目中展示现有按类型式分区展览。任一栏目出现资源后，“按依赖”和“按类型”共用同一套栏目分页画布：每个非空栏目拥有一个铺满资源管理区域的独立画布，左侧显示飞书文档式栏目大纲，顶部显示当前栏目标题，底部显示下一页标题；普通滚轮切换栏目，按住 Ctrl/Meta 的滚轮以指针为锚点缩放当前画布。两种模式唯一差异是“按依赖”在当前栏目内绘制引导线。资源详情是叠加在资源画板之上的非模态卡片；打开、切换和关闭详情都不得卸载背景工具栏、资源卡、依赖连线或重置 viewport、搜索和排序模式。
+资源管理在空项目中展示现有按类型式分区展览。任一栏目出现资源后，“按依赖”和“按类型”共用同一套栏目分页画布：每个非空栏目拥有一个铺满资源管理区域的独立画布，栏目大纲悬浮在画布左侧中间，只显示图标和栏目名称，不占用画布布局宽度；顶部显示当前栏目标题，底部显示下一页标题。普通滚轮切换栏目，按住 Ctrl/Meta 的滚轮以指针为锚点缩放当前画布。两种模式唯一差异是“按依赖”在当前栏目内绘制引导线。资源详情是叠加在资源画板之上的非模态卡片；打开、切换和关闭详情都不得卸载背景工具栏、资源卡、依赖连线或重置 viewport、搜索和排序模式。

 图片资源从“编辑资源”进入持续精修草稿后，点击任意图片直接在图片下方显示快速编辑卡。每次快速编辑创建新的候选图，不覆盖来源图层；生成任务立即在画布中创建占位并进入任务侧栏。用户显式选择候选图“设为最终图”后，保持原资产 ID 不变，以事务方式切换 manifest 指向的正式 PNG；精修草稿和其它候选图继续保留。

@@ -10,10 +10,10 @@

 ## 权威数据与持久化

-### 栏目分页投影与文档缺失边界
+### 栏目分页投影与设计文档缺失边界

 - 非空栏目页只由当前权威资源投影构造：manifest assets、已完成任务的 artifacts、用户已导入附件和持久化 Agent 文本回执。前端不得扫描项目目录自行发明资源。
- 文档栏因此只有在上述来源存在 Markdown / TXT / JSON / YAML 等文档类条目，或存在 Agent 文本回执时才出现。若 manifest 没有文档资产、任务 artifacts 未完成且没有附件 / 回执，资源页不显示文档页；这是生成或登记缺失，不由 UI 补假数据。
+- 设计文档栏因此只有在上述来源存在 Markdown / TXT / JSON / YAML 等文档类条目，或存在 Agent 文本回执时才出现。若 manifest 没有文档资产、任务 artifacts 未完成且没有附件 / 回执，资源页不显示设计文档页；这是生成或登记缺失，不由 UI 补假数据。
 - Direct Codex 的游戏生成链路以 `game/index.html`、`game/style.css`、`game/game.js` 作为代码资产登记；是否额外产出设计文档由当前任务和 Agent 决定，资源页只消费已登记结果。

 ### 持续精修草稿
@@ -81,8 +81,8 @@

 ## 操作边界

- 栏目顺序固定为 `文档 -> 美术资源 -> 音乐音效资源 -> 游戏代码 -> 项目版本`。完全空项目显示全部栏目的分区展览；任一栏目出现资源后，分页大纲展示全部栏目，默认停留在该顺序中的第一个非空栏目，空栏目计数为 0 且可打开空画布。
- 普通滚轮向下切到下一栏目、向上切到上一栏目并循环；短时间连续滚轮事件需要节流，避免触控板一次惯性滚动跨多页。点击大纲或底部“下一页”标题是显式切页入口。
+- 栏目顺序固定为 `设计文档 -> 美术资源 -> 音乐音效 -> 游戏代码 -> 项目版本`。完全空项目显示全部栏目的分区展览；任一栏目出现资源后，分页大纲以左侧垂直居中的悬浮 Dock 展示全部栏目。常态缩小、降低不透明度并移除容器与选中项背景，只露出栏目文字；悬停或键盘聚焦时平滑恢复完整尺寸，显示栏目图标、Dock 背景和选中态视觉强调。默认停留在该顺序中的第一个非空栏目，空栏目仍可打开空画布。
+- 普通滚轮向下切到下一栏目、向上切到上一栏目并循环；持续滚动时将离散切页意图加入有界队列，浏览器合并形成的单个大幅滚轮事件也要按输入强度拆分为多个切页意图。同一节流窗口内的待处理步数必须合并为一次目标栏目切换，不能逐页挂载并加载中间栏目的资源，以免资源渲染阻塞后续滚轮输入；同时限制切页频率和最长排队距离，避免触控板惯性长时间自动翻页。点击大纲、底部“下一页”标题或自动定位资源属于显式切页，必须先取消尚未执行的滚轮队列，不能在显式切页后继续跳转；开始拖动画布或资源卡时也必须取消待处理切页，切页前必须终止旧栏目的画布拖动和 pointer capture，避免旧 viewport 写入新栏目。
 - 每个栏目画布保留独立 viewport；切换栏目后先按该栏目内容适配视口。空白处拖拽平移画布，资源卡拖拽移动卡片并更新依赖线，Ctrl/Meta 缩放只作用于当前栏目，不能牵动其它栏目。
 - 依赖画布复用 `@genarrative/image-canvas-core` 的 viewport 计算，并复用现有资源卡片、布局和依赖连线模型。
 - 非空状态不使用资源分区滚动条、分区缩放或分区高度操作作为主要导航；栏目通过大纲、底部下一页标题和滚轮切换。
@@ -108,8 +108,8 @@

 ## 验收

-1. 完全空项目在按依赖与按类型下都显示相同的分区展览；任一栏目出现资源后，两种模式都切换为栏目分页画布，大纲包含全部栏目，空栏目计数为 0 且可打开空画布。
-2. 栏目顺序为 `文档 -> 美术资源 -> 音乐音效资源 -> 游戏代码 -> 项目版本`，游戏代码不再固定在首位；普通滚轮可循环切换栏目，点击大纲和底部下一页标题也可切页。
+1. 完全空项目在按依赖与按类型下都显示相同的分区展览；任一栏目出现资源后，两种模式都切换为栏目分页画布，大纲以左侧垂直居中的悬浮 Dock 覆盖在全宽画布上，包含全部栏目的图标和文字、不显示数量，空栏目仍可打开空画布。
+2. 栏目顺序为 `设计文档 -> 美术资源 -> 音乐音效 -> 游戏代码 -> 项目版本`，游戏代码不再固定在首位；普通滚轮可循环切换栏目，点击大纲和底部下一页标题也可切页。
 3. 在当前栏目内拖拽空白可以无限平移画布，拖拽资源卡可以移动卡片并同步依赖线，Ctrl/Meta + 滚轮以指针位置为锚点缩放，复位按钮可以适配当前栏目内容；普通平移不会因资源 extent、图片测量或窗口 resize 被拉回，连续缩放仍停在共享画布的最小/最大比例范围内。
 4. 按依赖模式显示当前栏目内同类型两端资源的合法精确引用，并具有与当前可见连线一致的无障碍关系说明；按类型模式不显示引导线；搜索隐藏任一端点后连线和说明同时消失。
 5. 点击任意资源后“新增资源 / 按依赖 / 按类型 / 复位”仍保持挂载和原状态；详情为非模态独立卡片，背景画板 viewport、搜索、排序、卡片和连线不卸载、不重置。