📋 slice-edit-ux-rework: publish round-2 spec (19 decisions) and glossary updates

This commit is contained in:
d-robotics 2026-10-13 19:44:06 +05:30
parent c98d631634
commit 879fc57b5d
2 changed files with 120 additions and 1 deletions

View File

@ -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 术语(已更新)随代码同批提交。

View File

@ -63,7 +63,10 @@ _Avoid_:历史操作日志(本列表不展示修改前的旧版本)
**越界处置**:切片边界移动时,按受影响动作与边界的几何关系当场决定动作归属的判定。完全落入新归属侧的动作自动跟随;被边界穿过的动作由标注员当场三选(截断 / 挪片 / 判无效);恰好贴边的动作按语义区分——无效动作自动跟随伸缩,有效动作两选(跟随伸缩或保持原边界)。任何动作不会因边界移动被静默删除;存在未当场处置的动作时,边界保持不动。
_Avoid_:待核对(越界处置取代旧“拆两段待核对”,该中间状态不复存在)
**切片编辑模式**:逐片标注阶段内进入的临时编辑状态,用于逐帧或粗步进挪动切片边界、在高亮边界间切换、舍弃当前片,退出后恢复常规标注键位;模式内不响应常规标注键。模式内与模式外的编辑属于同一套切片结构操作,首标与返修同样可用。
**切片重设面板**:逐片标注阶段按 E 进入的专注编辑界面:设置所选切片的首尾帧、切分、舍弃、修改切片字典描述。改动在面板内只作预览、不落库;Enter 应用,Esc 整体回退到进入面板时的结构。首标与返修同样可用,模式外键位不受影响。
_Avoid_:切片编辑模式(2026-10-13 交互重设计,原地挪边界模式升级为重设面板)
**冲突清单**:结构改动应用前对受影响动作的集中处置界面:逐条列出每个被穿过或贴边的动作,要求逐条选定处置(截断 / 挪片 / 判无效)后才应用改动;中途取消则整个待应用改动集回退。它取代逐边界现场弹卡,任何动作不会因结构改动被静默删除或丢弃区间。
**保存进度**:保留当前动作划分和完成状态,允许仍有待标注区间;不代表标注已经完成或已经送检。
@ -97,6 +100,9 @@ _Avoid_:公共可领取任务池(其中的任务尚未归属当前标注员
**审核意见**:审查者对整体任务、某个切片或某个动作的问题与修改要求。同一轮、同一被审版本中,每个对象只有一份当前有效意见,可编辑或清除;无意见不表示已经核对或通过。终审的整体意见属于整个终审任务,切片和动作意见按来源区分。它不改变原标注判断,也不等于已提交退回决定。
**退回意见**:随质检退回决定送达标注员、要求在返工中处理的意见集合。再退回时的新退回意见只由上一轮判"仍有问题"的旧意见与新增意见构成;已判定解决的旧意见不再进入后续轮次的退回意见(界面上不再显示),完整处理轨迹保留在正式审查记录中供追溯。
_Avoid_:回退意见(易与撤销操作混淆)
**旧版问题批注**:旧规则下同一对象的多条独立问题记录;尚未提交的重复意见需明确整理为一份最终意见,原文保留为历史。已正式提交的历史批注不因新规则而改写。
**审查字幕**:随当前播放位置展示被审动作描述、语义留空、无效或切片舍弃判断的文字,呈现原结果,不包含审查者正在填写的问题批注。