From 879fc57b5d2a73ec8b0531bf4efd055ce129ecdb Mon Sep 17 00:00:00 2001 From: d-robotics Date: Tue, 13 Oct 2026 19:44:06 +0530 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=8B=20slice-edit-ux-rework:=20publish?= =?UTF-8?q?=20round-2=20spec=20(19=20decisions)=20and=20glossary=20updates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .scratch/slice-edit-ux-rework/spec.md | 113 ++++++++++++++++++++++++++ CONTEXT.md | 8 +- 2 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 .scratch/slice-edit-ux-rework/spec.md diff --git a/.scratch/slice-edit-ux-rework/spec.md b/.scratch/slice-edit-ux-rework/spec.md new file mode 100644 index 00000000..a03cd58f --- /dev/null +++ b/.scratch/slice-edit-ux-rework/spec.md @@ -0,0 +1,113 @@ +# 切片编辑重设面板与质检复审页重设计(第二轮 UX 返修) + +Status: ready-for-agent + +更新:2026-10-13。本 spec 来自第二轮 grill 共 19 项用户裁决(R1 Q1–Q8 / R2 Q1–Q7 / R3 Q1–Q4,全部已拍板),依据两路只读调查(@ `c98d6316`,基线 `6cc53b8b`):① 布局/键位四项(I1–I4);② 三选状态处理三项(T1 残段丢弃等)。实现落工作树 `local-data/worktrees/ise-integration`(分支 `codex/inplace-slice-editing`)。 + +本 spec **取代** [inplace-slice-editing](../inplace-slice-editing/spec.md) 中被推翻的局部决策:Q6 的"模态切片编辑模式"(升级为切片重设面板)、R2-Q1/R2-Q2 的"现场三选卡"(被冲突清单取代)、R2-Q3 的"保留 ReworkComparisonPanel + 红灰对照双栏"(双双删除)。其余决策不变。 + +依据:[CONTEXT.md](../../CONTEXT.md)(词汇表已更新:切片重设面板 / 冲突清单 / 退回意见)、[ADR 0007](../../docs/adr/0007-inplace-slice-editing-replaces-reslice.md)、[返修手册](../../docs/rework-review-manual.zh-CN.md)、[演示走查](../../docs/manuals/ise-demo-walkthrough.zh-CN.md)。 + +## 1. 背景与问题 + +用户实测演示任务(A/B 双任务,`scripts/local/seed-ise-demo.mjs` 一键重建)后提出 10 项体验问题(标注员 5 + 质检员 5),调查结论: + +| # | 现象 | 判定 | +| --- | --- | --- | +| I1 | 切换切片/JK 跳意见后"编辑动作"面板收起 | 既有行为(与基线一致):编辑器随切片停放;键盘路径缺少"跳转后自动打开目标动作编辑器"(点击路径已有) | +| I2a | E 模式提示横幅挂载把轨道挤下 ~28px | **本 feature 真回归**:横幅为普通流布局 | +| I2b | 模式内 ←/→/Shift+←/→ "全动不了" | 无间隙铺满数据下每次挪动都命中动作→现场三选卡弹出且吞掉方向键(模态设计),观感失灵;另有单切片任务进 E 全键静默失效的死角 | +| I3 | 模式外 Shift+←/→ 挪动作边界"没了" | 绑定未动(需先打开动作编辑器);模式外=动作边界、模式内=切片边界两层易混淆 | +| I4 | 左侧动作栏消失 | 既有门槛:选中弃用切片时整个动作栏卸载;演示数据含弃用片(A:S5 / B:S3)且意见锚定其上 | +| T1 | 判无效后切片"缺一块" | 纯函数把跨界动作的几何残段直接丢弃 | +| T2 | 处置后动作/无效动作轨道重叠、上下操作失灵 | 三选产物状态 bug | +| T3 | 结构改动产物被提交守卫硬拦 | 残段丢弃导致覆盖不完整,触发"动作完整落在恰好一个切片"硬校验 | + +用户判断:**E 键三选的交互编排整体不对**,需要重设计而不是修补。质检侧红灰对照双栏与结构对比面板"没啥用",信息应上轨道。 + +## 2. 已确认决策(19 项,全部用户拍板) + +### 第一轮 + +| # | 决策 | +| --- | --- | +| R1-Q1 | **E = 切片重设面板**:专注浮层(视频+轨道仍可见),针对当前选中切片:①首尾帧数字输入 + ±1/±2 帧步进 ②`C` 拆分 ③`G` 舍弃 ④切片字典描述编辑 ⑤删除首/尾边界 = 与左/右邻合并。面板期间结构变更**只预览不落库**;`Enter` 应用、`Esc` 整体回退到打开前状态。应用时有冲突 → 冲突清单(见 R1-Q4) | +| R1-Q2 | **保留拖动手柄快路径**:单边界微调拖更顺手;松手后冲突同样进冲突清单统一处理 | +| R1-Q3 | **面板内保留 ←/→ 连续挪边界**(红块实时反馈)+ 面板数字精调,两条都要 | +| R1-Q4 | **冲突清单**:`Enter` 确认 → 有冲突才弹清单,逐条必选(默认截断,可改挪片/判无效),全部处理完才应用;`Esc` 随时取消整个待应用改动集;不支持部分应用 | +| R1-Q5 | **质检页双板块**:左「退回意见」(上轮基线)右「本轮审核意见」(本轮新写),各自滚动,都支持 J/K 定位视频(seekSlice/seekAction/seekTime)。术语:退回意见 / 本轮审核意见(弃"回退意见") | +| R1-Q6 | **删红灰对照双栏(ReworkContrastView)与结构对比面板(ReworkComparisonPanel)**;红/灰上轨道(与标注员同款视觉:红块/灰块/徽标,零新增轨道元素);结构变化明细压成摘要横幅一句话;意见字幕上屏(标注员同款三排) | +| R1-Q7 | **判定快捷键 `1`=已解决 / `2`=仍有问题**(2 必须弹现场意见输入,空不许提交),配合 J/K;与三选卡数字选择肌肉记忆一致 | +| R1-Q8 | **已解决意见彻底不显示**(用户改推荐:不折叠、彻底不显示)。再退回时新基线 = 未解决旧意见 + 新增意见;已解决意见完整轨迹保留在服务端正式审查记录,界面永不显示。服务端基线构造契约变更 → ADR 0008 | + +### 第二轮 + +| # | 决策 | +| --- | --- | +| R2-Q1 | **几何残段显式化,永不蒸发**:判无效 = 该动作整段截断几何全部转无效(含跨界两侧);挪片让出的空当自动生成无效段(可编辑/撤销)。覆盖永保完整,提交永不因结构改动被硬拦(根治 T1/T2/T3) | +| R2-Q2 | **冲突清单键盘模型**:`↑/↓` 条目间移动(回绕),`1/2/3` 选当前条目处置(1 截断 / 2 挪片 / 3 判无效;两选条目 1/2),选完自动跳下一条未决;`Enter` 应用(未决按默认截断批量处理);`Esc` 取消整个改动集 | +| R2-Q3 | **拖动确认时机**:无冲突 → 立即生效(不进面板不按 Enter,保住快路径);有冲突 → 清单就地弹出处理完即生效;`Esc` 回退本次拖动。E 面板内改动统一 `Enter` 确认 | +| R2-Q4 | **面板范围 = 当前选中切片**(见 R1-Q1 五项);共享边界两侧联动属自然结果 | +| R2-Q5 | **面板期间旁路锁定**:播放/逐帧/缩放自由;J/K 意见跳转、拖手柄、悬停+/垃圾桶锁定;点选其他切片提示先 Enter/Esc;面板常显 `Enter 应用 · Esc 取消` | +| R2-Q6 | **QC 字幕只显示退回意见**;本轮正在写的审核意见只在右栏列表,不上屏 | +| R2-Q7 | **"仍有问题"必填现场意见在标注员侧显示为一条意见**:原文本 + 质检备注追加(如"…【质检备注】改后区间仍多 2 秒"),基线条目数不变、J/K 不多跳 | + +### 第三轮 + +| # | 决策 | +| --- | --- | +| R3-Q1 | **自动无效段不带"系统生成"标记**:与手工无效动作完全同形(同灰、可编辑/撤销),来源从操作历史追溯,界面不加徽标 | +| R3-Q2 | **被替换旧组件全删不留开关旗**:现场三选卡、ReworkContrastView、ReworkComparisonPanel;git 历史可回溯 | +| R3-Q3 | **执行顺序三批**:stabilization 独立提交先行(用户即刻可在 5174 重测)→ 标注员面板批次 → QC 页批次。每批自带纯函数单测 + 走查文档对应场景改写 + 重播种验证,批间用户验收一次 | +| R3-Q4 | **ADR 0008 退回基线只含未解决意见**(与实现同批落库) | + +## 3. 执行计划(三批) + +### 批 0 · stabilization(独立提交,半天级) + +1. I2a:E 模式横幅改绝对定位浮层(批 1 将随模式整体移除,先修保当前可用)。 +2. I1:`jumpReworkProblem` 跨片跳转后自动打开意见锚定动作的编辑器(镜像 `locateReworkOpinion` 点击路径既有行为)。 +3. I4:弃用切片下动作栏保留挂载,只读展示归档动作(去掉 `!selectedDiscarded` 卸载门槛),标注员与 QC 两侧一致。 +4. I2b 死角:单切片任务禁用 E(提示"仅一个切片,无可调边界")。 + +### 批 1 · 标注员:切片重设面板 + 冲突清单 + 残段显式化 + +1. **切片重设面板**(E 进入,取代切片编辑模式与现场三选卡):R1-Q1 五项操作、R2-Q5 旁路锁定、预览不落库、Enter/Esc 语义。面板内 ←/→ 连续挪 + 数字精调。 +2. **冲突清单**组件:R1-Q4/R2-Q2 键盘模型;两选条目(贴边有效动作)1/2;应用前逐条必选。 +3. **拖动快路径**接入:R2-Q3 确认时机。 +4. **几何残段显式化**(R2-Q1,根治 T1/T2/T3):判无效整段转无效、挪片空当自动无效段、贴边跟随语义(无效自动跟随;有效两选)。轨道状态清理修复 T2 重叠。 +5. 删除:现场三选卡、切片编辑模式横幅与模式框架(E 改派面板)、`slice-edit-mode-banner`。 +6. 键位表更新(annotation-shortcuts):E=面板、面板内 C/G/←/→/Enter/Esc、J/K 不变。 +7. 走查文档场景 ①–⑧ 改写(面板/清单动线),重播种 A/B 回归。 + +### 批 2 · 质检:复审页重设计 + 退回基线契约 + +1. **双板块**:退回意见 / 本轮审核意见,各自滚动 + J/K 视频定位(R1-Q5)。 +2. **字幕上屏**:退回意见三排字幕(R1-Q6/R2-Q6);轨道红/灰复用标注员视觉;结构摘要横幅一句话保留;删除 ReworkContrastView + ReworkComparisonPanel(R1-Q6/R3-Q2)。 +3. **判定键**:`1`/`2`(R1-Q7,2 必填现场意见);复审只读不开放面板(默认假设已接受)。 +4. **服务端退回基线契约**(R1-Q8):再退回基线 = 未解决旧意见 + 新增;已解决轨迹入正式审查记录、界面不显示;标注员侧基线同步收窄。**ADR 0008** 同批。 +5. 走查文档场景 ⑨–⑩ 改写;B 任务(round-2 复审起点)重播种回归。 + +## 4. 测试 seam(沿用四 seam,扩展点) + +| Seam | 本轮扩展 | +| --- | --- | +| ① 领域纯函数(主) | 残段显式化几何(判无效整段/空当无效段/贴边两选)、冲突清单解析(改动集 → 条目 + 默认处置)、改动集整体回退 | +| ② Go 服务端校验 | 残段产物全为合法状态(覆盖完整、状态白名单)、退回基线构造(未解决+新增,已解决归档不进基线)表驱动 | +| ③ 键位映射纯函数 | E=面板新键表、面板内外互不串扰、QC `1`/`2` 判定键注册 | +| ④ 演示 fixture | A/B 双任务回归(脚本已就绪);UI 交互不自动化,按改写后场景清单人工验收 | + +## 5. Out of scope + +- QC 复审侧开放结构编辑(复审只读)。 +- 三选卡/双栏视图的兼容开关或特性旗。 +- UI 自动化测试脚手架。 +- reslice 写端点恢复(维持 ADR 0007 停用状态)。 +- 无效动作强制理由/描述(维持裸 invalid 合法)。 + +## 6. 验收 + +1. 批间验收:批 0 后用户在 5174 重测 I1/I2a/I4;批 1 后走 ①–⑧ 新动线;批 2 后走 ⑨–⑩。 +2. 纯函数单测 + Go 表驱动全绿;`npx tsc --noEmit`;前端 `node --test` 不低于现有 730/716/14。 +3. `node scripts/local/seed-ise-demo.mjs` 重播种双任务,A/B 终态断言不变。 +4. ADR 0008 与 CONTEXT.md 术语(已更新)随代码同批提交。 diff --git a/CONTEXT.md b/CONTEXT.md index 8cde03a7..30f38fce 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -63,7 +63,10 @@ _Avoid_:历史操作日志(本列表不展示修改前的旧版本) **越界处置**:切片边界移动时,按受影响动作与边界的几何关系当场决定动作归属的判定。完全落入新归属侧的动作自动跟随;被边界穿过的动作由标注员当场三选(截断 / 挪片 / 判无效);恰好贴边的动作按语义区分——无效动作自动跟随伸缩,有效动作两选(跟随伸缩或保持原边界)。任何动作不会因边界移动被静默删除;存在未当场处置的动作时,边界保持不动。 _Avoid_:待核对(越界处置取代旧“拆两段待核对”,该中间状态不复存在) -**切片编辑模式**:逐片标注阶段内进入的临时编辑状态,用于逐帧或粗步进挪动切片边界、在高亮边界间切换、舍弃当前片,退出后恢复常规标注键位;模式内不响应常规标注键。模式内与模式外的编辑属于同一套切片结构操作,首标与返修同样可用。 +**切片重设面板**:逐片标注阶段按 E 进入的专注编辑界面:设置所选切片的首尾帧、切分、舍弃、修改切片字典描述。改动在面板内只作预览、不落库;Enter 应用,Esc 整体回退到进入面板时的结构。首标与返修同样可用,模式外键位不受影响。 +_Avoid_:切片编辑模式(2026-10-13 交互重设计,原地挪边界模式升级为重设面板) + +**冲突清单**:结构改动应用前对受影响动作的集中处置界面:逐条列出每个被穿过或贴边的动作,要求逐条选定处置(截断 / 挪片 / 判无效)后才应用改动;中途取消则整个待应用改动集回退。它取代逐边界现场弹卡,任何动作不会因结构改动被静默删除或丢弃区间。 **保存进度**:保留当前动作划分和完成状态,允许仍有待标注区间;不代表标注已经完成或已经送检。 @@ -97,6 +100,9 @@ _Avoid_:公共可领取任务池(其中的任务尚未归属当前标注员 **审核意见**:审查者对整体任务、某个切片或某个动作的问题与修改要求。同一轮、同一被审版本中,每个对象只有一份当前有效意见,可编辑或清除;无意见不表示已经核对或通过。终审的整体意见属于整个终审任务,切片和动作意见按来源区分。它不改变原标注判断,也不等于已提交退回决定。 +**退回意见**:随质检退回决定送达标注员、要求在返工中处理的意见集合。再退回时的新退回意见只由上一轮判"仍有问题"的旧意见与新增意见构成;已判定解决的旧意见不再进入后续轮次的退回意见(界面上不再显示),完整处理轨迹保留在正式审查记录中供追溯。 +_Avoid_:回退意见(易与撤销操作混淆) + **旧版问题批注**:旧规则下同一对象的多条独立问题记录;尚未提交的重复意见需明确整理为一份最终意见,原文保留为历史。已正式提交的历史批注不因新规则而改写。 **审查字幕**:随当前播放位置展示被审动作描述、语义留空、无效或切片舍弃判断的文字,呈现原结果,不包含审查者正在填写的问题批注。