diff --git a/.scratch/rework-ux-adjust-20261014/issues/07-review-opinion-target-interaction.md b/.scratch/rework-ux-adjust-20261014/issues/07-review-opinion-target-interaction.md index a5b7c3d3..430c9bc6 100644 --- a/.scratch/rework-ux-adjust-20261014/issues/07-review-opinion-target-interaction.md +++ b/.scratch/rework-ux-adjust-20261014/issues/07-review-opinion-target-interaction.md @@ -1,6 +1,6 @@ # Ticket 07: 审核意见目标交互重做 + 四面模式头调整 -Status: ready(依赖 06 合入后开工) +Status: resolved(2026-10-14,`codex/rua-07` @ `7df73dbc`,基线 4b00fba3 未漂移无合并,闸门全绿见 Answer) Priority: P1(第二轮增补,用户 2026-10-14 晚拍板) Spec: D5(修订版)、D9、US26/US27 @@ -21,13 +21,56 @@ Spec: D5(修订版)、D9、US26/US27 ## 验收 -- [ ] Ctrl+↑/↓ 三档切换到头停住;目标随播放头位置正确推导(跨片/跨动作边界移动后刷新) -- [ ] F 直写零弹窗;Ctrl+Enter 提交成功;重复/非法校验行为不回退 -- [ ] 作用域选择弹层全删;四面(审核普通/专注、返工普通/专注)无死入口、帮助行新语义一致 -- [ ] G / J/K / 1/2 键行为不回退;既有意见列表键盘遍历已移除 -- [ ] 纯函数 seam:目标推导+切换次序表驱动;键位映射表新语义断言;四面模式头源码守卫 -- [ ] 双闸门按名对比基线零新增;lint/format 干净 +- [x] Ctrl+↑/↓ 三档切换到头停住;目标随播放头位置正确推导(跨片/跨动作边界移动后刷新) +- [x] F 直写零弹窗;Ctrl+Enter 提交成功;重复/非法校验行为不回退 +- [x] 作用域选择弹层全删;四面(审核普通/专注、返工普通/专注)无死入口、帮助行新语义一致 +- [x] G / J/K / 1/2 键行为不回退;既有意见列表键盘遍历已移除 +- [x] 纯函数 seam:目标推导+切换次序表驱动;键位映射表新语义断言;四面模式头源码守卫 +- [x] 双闸门按名对比基线零新增;lint/format 干净 ## Answer -(实施后填写) +**实施**:`codex/rua-07` @ `7df73dbc`(基线=集成分支 tip `4b00fba3`,收尾复核未漂移、无合并;未 push)。提交:`7e700c4c` 认领 → `7df73dbc` 实现+测试(TDD 红→绿)。 + +### 改动文件与决策落点 + +| 文件 | 决策落点 | +|---|---| +| `src/lib/review-navigation.js` | 目标模型纯函数(票 05 导航序骨架重写):`reviewTargetScopes` 三档次序;`reviewTargetOptions(position)` 播放头→可用档(切片需画面就绪、动作另需含播放头、时间点需画面+数值时间,与 opinionTarget 契约最小镜像);`nextReviewTargetScope` 档位循环(↓ 正向 切片→动作→时间点、↑ 反向;**空档就近跳过**;两端停住返回 null;未知档按方向进入序列);`reviewTargetPosition` 时间点档=冻结锚点、其余=实时画面、无锚点退回实时;`defaultReviewScope` 沿用 05 | +| `src/hooks/useReviewDraft.ts` | **picker 全删**(`m.picker`/`ReviewScopePicker`/`confirmScope`/`moveScope`/`cancelScope`/`scopeOptions`/`scopeChoices`/`scopePicker` 及全部守卫);新增 `m.targetAnchor`(时间点档冻结画面);`beginProblem(position, scope?)`=F 直写:暂停定位→当前选中档(未选按画面默认)→该档无目标按画面兜底→直接开编辑器聚焦;`switchTarget(direction)` 取代 `navigateSelection`(纯函数切档+park 驻留未保存文字+切入时间点档冻结锚点);`selectProblem` 选中时间点条目即以该意见记录位置设锚;`selectScope`/`requestDelete`/`editSelected`/`residentEditor` 全部锚点感知;`m.selectedProblem` 随条目遍历一并移除 | +| `src/components/ReviewProblemPanel.tsx` | radiogroup 弹层与 scopeRef 焦点效应删除;常驻编辑区显示「当前目标:当前切片/当前动作/当前时间点 · {目标说明}」(`targetTierNames`);卡片 aria-selected 认有效档(显式选中或常驻绑定档);清除按钮可用性跟有效档 | +| `src/lib/review-shortcuts.js` | 命令 `previous-problem`/`next-problem` → `previous-target`/`next-target`;帮助表重写(D9):Ctrl+↑/↓=切换意见目标、F=直接填写、Ctrl+Enter=提交、Esc 去「退出范围选择」、G 行去过时的「不占用卡片导航」注 | +| `src/components/review-viewing.ts` | 契约:`onReviewProblemNavigate` → `onReviewTargetSwitch`(注释改目标切换语义);`onReviewProblem` 增可选 `scope`(供显式入口指定目标档) | +| `src/components/CaptureAnnotationWorkbench.tsx` / `FinalAcceptanceWorkspace.tsx` | 分发改名接线;「切片问题备注」按钮显式传 `scope="slice"`(防当前档为时间点时误入错档) | +| `src/pages/AnnotationOperations.tsx` | 两处接线 `onReviewTargetSwitch={reviewDraft.switchTarget}` | + +### 判断性决定(供 review 检验) + +1. **空档跳过**:播放头不在任何动作内时动作档不可用,切换就近跳到下一可用档(沿用旧弹层 scopeOptions 过滤先例),不停在无目标档上。 +2. **锚点=切入时刻**(WYSIWYG):切入时间点档的瞬间冻结画面(Ctrl+↑/↓ 切入、F 首次落入、选中时间点条目各按当时画面/记录位置);已在时间点档时编辑所显示的锚定目标、不随播放头漂移——重新锚定=切走再切回。无显式切入前(页面初载)时间点档退回实时画面,目标随播放头。 +3. **F 不重冻结**:时间点档已显示锚定目标时,F 编辑该目标(所见即所编);「发起时锚定」体现在切入时刻而非 F 时刻。 +4. **命令改名**:键表命令与 prop 随语义改名(previous-target/onReviewTargetSwitch),防过时命名误导后续维护。 +5. **四面对齐方式**:四面共用工作台帮助对话框的 `reviewShortcutHelp` 单源(专注/普通、首检/返工双板同渲染路径),改一处即四面一致;源码守卫钉住帮助表三行新语义+全 src 无过时文案。 + +### 被取代断言清单(scope-cycle-inline-editor.test.mjs 迁移记录) + +- **删除**(被 review-target-interaction.test.mjs 的目标档表驱动取代):`navigation order: target-bearing cards first…`、`next entry: walks slice→action→timestamps…` 两例。 +- **保留原样**:`default scope: action→action…`(defaultReviewScope 未变);`expander, summary UI…removed`;`resident inline editor promotes…on focus`。 +- **改写**:`source guard: hook wires D5 navigation order…` → 目标模型接线(reviewTargetPosition/锚点/档位);`shortcut help describes the slice→action→timestamp cycle` → 新语义(切换意见目标/零弹窗)。 +- 另更新 `review-shortcuts.test.mjs` 3 处命令名断言(previous/next-problem → previous/next-target)。 + +### 闸门(真实退出码,最终提交态复跑) + +| 闸门 | 结果 | +|---|---| +| `npm run test:frontend:gate` | **exit 0**,14 failures all in baseline(按名对比零新增) | +| `npm run lint:web`(tsc --noEmit) | **exit 0** | +| `npm run format:check` | **exit 0**(含改动文件零新增告警) | +| Go 闸门 | **有据跳过**——`4b00fba3..HEAD` 零 `.go` 文件改动 | +| 新钉子单跑(3 文件) | **20 pass / 0 fail**(review-target-interaction 9 例 + scope-cycle-inline-editor 5 例 + review-shortcuts 6 例) | + +### 给 merger 的提示 + +- 与 03/05 同文件(useReviewDraft.ts / ReviewProblemPanel.tsx / review-shortcuts.js),本票基于含 05 的集成 tip 开工,语义**取代** 05 的条目导航——合并顺序必须在 05 之后;03 的作用域收敛(slice/action/timestamp)与本票正交。 +- 契约面变更:`ReviewViewingProps.onReviewProblemNavigate` 改名 `onReviewTargetSwitch`、`onReviewProblem` 增可选第二参——若有分支沿用旧名,tsc 会直接报出。 +- 后端契约零改动(三档作用域早已存在);时间点意见身份(来源+规范帧)不变,冻结锚点只影响前端目标解析。 diff --git a/src/components/CaptureAnnotationWorkbench.tsx b/src/components/CaptureAnnotationWorkbench.tsx index b4ad3dab..dc8995f8 100644 --- a/src/components/CaptureAnnotationWorkbench.tsx +++ b/src/components/CaptureAnnotationWorkbench.tsx @@ -367,7 +367,7 @@ export function CaptureAnnotationWorkbench({ onReviewController, onReviewProblem, onReviewSave, - onReviewProblemNavigate, + onReviewTargetSwitch, onReviewReworkNavigate, onReviewReworkVerdict, onReviewTimestampJump, @@ -3123,8 +3123,9 @@ export function CaptureAnnotationWorkbench({ const position = reviewController.pauseAndLocate(); if (position) onReviewProblem?.(position); } else if (command === "save-note") onReviewSave?.(); - else if (command === "previous-problem" || command === "next-problem") - onReviewProblemNavigate?.(command === "previous-problem" ? -1 : 1); + else if (command === "previous-target" || command === "next-target") + // 票 07(D5 修订版):Ctrl/⌘+↑/↓ 切换写意见的目标档(页面侧解析三档与锚点)。 + onReviewTargetSwitch?.(command === "previous-target" ? -1 : 1); else if (command === "jump-timestamp-problem") onReviewTimestampJump?.(); else if (command === "next-rework-opinion" || command === "previous-rework-opinion") // 返修接收视图 J/K:定位由页面绑 ReviewViewingController 原语(票 08)。 @@ -4165,7 +4166,7 @@ export function CaptureAnnotationWorkbench({ disabled={reviewWriteLocked} onClick={() => { if (reviewProblemPanel) { - onReviewProblem?.({ ...reviewPosition, actionId: null }); + onReviewProblem?.({ ...reviewPosition, actionId: null }, "slice"); return; } const note = parsedQAComments.find( diff --git a/src/components/FinalAcceptanceWorkspace.tsx b/src/components/FinalAcceptanceWorkspace.tsx index 8cec2049..cc6e8065 100644 --- a/src/components/FinalAcceptanceWorkspace.tsx +++ b/src/components/FinalAcceptanceWorkspace.tsx @@ -89,7 +89,7 @@ export function FinalAcceptanceWorkspace({ onReviewController, onReviewProblem, onReviewSave, - onReviewProblemNavigate, + onReviewTargetSwitch, onReviewTimestampJump, onReviewProblemEdit, onReviewProblemDelete, @@ -551,8 +551,8 @@ export function FinalAcceptanceWorkspace({ const position = finalController.pauseAndLocate(); if (position) onReviewProblem?.(position); } else if (command === "save-note") onReviewSave?.(); - else if (command === "previous-problem" || command === "next-problem") - onReviewProblemNavigate?.(command === "previous-problem" ? -1 : 1); + else if (command === "previous-target" || command === "next-target") + onReviewTargetSwitch?.(command === "previous-target" ? -1 : 1); else if (command === "jump-timestamp-problem") onReviewTimestampJump?.(); else if (command === "edit-problem") onReviewProblemEdit?.(); else if (command === "delete-problem") onReviewProblemDelete?.(); @@ -670,7 +670,7 @@ export function FinalAcceptanceWorkspace({ onReviewPositionChange={mappedPosition} onReviewProblem={(position) => onReviewProblem?.(mapReviewPosition(position))} onReviewSave={onReviewSave} - onReviewProblemNavigate={onReviewProblemNavigate} + onReviewTargetSwitch={onReviewTargetSwitch} onReviewTimestampJump={onReviewTimestampJump} onReviewProblemEdit={onReviewProblemEdit} onReviewProblemDelete={onReviewProblemDelete} diff --git a/src/components/ReviewProblemPanel.tsx b/src/components/ReviewProblemPanel.tsx index a6757801..b2f807b7 100644 --- a/src/components/ReviewProblemPanel.tsx +++ b/src/components/ReviewProblemPanel.tsx @@ -11,19 +11,16 @@ type Props = { focusedProblemId?: string | null; }; const names = { task: "整体意见", slice: "当前切片意见", action: "当前动作意见", timestamp: "时间点意见" }; -const scopes = { task: "整体", slice: "切片", action: "动作", timestamp: "时间点" }; +// 票 07(D5 修订版):常驻编辑区的目标档位标签——切到哪档显示哪档。 +const targetTierNames = { slice: "当前切片", action: "当前动作", timestamp: "当前时间点" }; export function ReviewProblemPanel({ review, label, writeLocked = false, focusedProblemId = null }: Props) { const locked = writeLocked || !review.writable || review.loading || !review.draft; - const scopeRef = useRef(null), - clearRef = useRef(null); - useLayoutEffect(() => { - scopeRef.current?.querySelector('[aria-checked="true"]')?.focus(); - }, [review.scopePicker]); + const clearRef = useRef(null); useLayoutEffect(() => { if (review.confirmClear) clearRef.current?.querySelector("[data-cancel]")?.focus(); }, [review.confirmClear]); - // D5(票 05):编辑器常驻内联——无打开编辑器时绑定默认作用域(按当前目标自动匹配)。 - const resident = review.editor || review.scopePicker || review.confirmClear || locked ? null : review.residentEditor; + // 票 07:编辑器常驻内联,绑定当前所选目标档(未选按画面默认);无弹层。 + const resident = review.editor || review.confirmClear || locked ? null : review.residentEditor; return (
review.selectScope(card.scope, true)} ref={cardFocused ? (node) => node?.scrollIntoView({ block: "nearest" }) : undefined} @@ -112,49 +109,13 @@ export function ReviewProblemPanel({ review, label, writeLocked = false, focused
- {review.scopePicker && ( -
{ - if (e.nativeEvent.isComposing || e.keyCode === 229 || e.repeat) return; - e.stopPropagation(); - if (e.key === "ArrowUp" || e.key === "ArrowDown") { - e.preventDefault(); - review.moveScope(e.key === "ArrowUp" ? -1 : 1); - } else if (e.key === "Enter" || e.key === " ") { - e.preventDefault(); - review.confirmScope(); - } else if (e.key === "Escape") { - e.preventDefault(); - review.cancelScope(); - } - }} - > - {(review.scopeChoices ?? review.cards.map((c) => c.scope)).map((scope) => ( - - ))} -
- )} {review.editor ? ( <>

@@ -208,7 +169,7 @@ export function ReviewProblemPanel({ review, label, writeLocked = false, focused resident && ( <>

- 当前对象:{label(resident.target)} + 当前目标:{targetTierNames[resident.scope]} · {label(resident.target)}