✨ feat: timestamp opinion axis markers (maintenance-backlog#02, spec §4.3)

- thin marker strip atop the review slice timeline: orange dots at
  capture-seconds positions; near-neighbours (<0.8% track width) cluster
  into a count badge; single marker click seeks via reviewController,
  cluster click expands a popover listing each opinion (time + text)
- parent slices are never painted red (markers live on their own strip,
  visually distinct from the playhead)
- data flows through the new reviewTimestampOpinions prop mapped from
  reviewDraft.timestampProblems (same source as G-jump and locate)
- browser-verified on the replica stack: two nearby opinions (0.09s/
  0.14s) cluster into one '2 条' marker, expansion lists both; frontend
  regressions identical to baseline (14), tsc clean
This commit is contained in:
d-robotics 2026-10-13 07:33:24 +05:30
parent a76390da86
commit 8cce5208c7
4 changed files with 81 additions and 1 deletions

View File

@ -1,6 +1,6 @@
# 02 时间点意见时间轴标记(§4.3 显示增强)
Status: needs-triage(backlog,不阻塞发布)
Status: resolved(2026-10-13 实现并浏览器验证通过)
Type: task
Blocked by: 无
@ -18,3 +18,16 @@ G 键跳转 + 定位钮(发现性已满足);时间轴上的点位标记(
## 来源
code-review spec 轴 a4(2026-10-12);与 D5 交互(同帧 F 编辑、G 循环跳转)不冲突。
## Answer(2026-10-13)
- 审查侧切片时间轴(`capture-slice-timeline`)顶部新增 4px 标记条(§4.3:点位标记不涂红父
切片、与播放头样式区分):橙点标记按 capture-seconds 定位;近邻(<0.8% 轨宽)聚合为计数
徽标;点击单点直达 `reviewController.seekTime`,聚合点展开浮层逐条选择(时间+文本)跳转;
悬停 title 列出全部意见。
- 数据通道:`reviewTimestampOpinions` prop(ReviewViewingProps)由 AnnotationOperations 从
`reviewDraft.timestampProblems` 映射;与 G 键跳转/定位按钮同一数据源。
- 浏览器验证(复现栈):两条近邻时间点意见(0.09s/0.14s)聚合为一个“时间点意见 2 条”标记,
点击展开 2 项;截图 /tmp/bl-markers.png。1413×615 无布局冲击(4px 覆盖条)。
- 回归:前端 14=14 零新增(含 video-load-stall 源码形状测试 4/4);tsc 零错误。

View File

@ -287,6 +287,7 @@ export function CaptureAnnotationWorkbench({
onReviewSave,
onReviewProblemNavigate,
onReviewTimestampJump,
reviewTimestampOpinions,
onReviewProblemEdit,
onReviewProblemDelete,
onReviewEscape,
@ -381,6 +382,7 @@ export function CaptureAnnotationWorkbench({
// Until then (or under the runtime kill-switch) it renders native <video>,
// which is exactly the E′ direct path — fully functional on its own.
const [moviVideoReady, setMoviVideoReady] = useState(() => moviElementReady());
const [opinionMarkerOpen, setOpinionMarkerOpen] = useState<string | null>(null);
useEffect(() => {
if (browserReadyMedia || moviRuntimeMode() !== "movi") return;
if (moviElementReady()) {
@ -3206,6 +3208,61 @@ export function CaptureAnnotationWorkbench({
}}
>
<div className="absolute inset-x-0 top-4 h-px bg-slate-200" />
{isReviewViewing && reviewTimestampOpinions && reviewTimestampOpinions.length > 0 && (
<div
aria-label="时间点意见标记"
className="absolute inset-x-0 top-0 z-20 h-4"
onPointerDown={(e) => e.stopPropagation()}
>
{(() => {
// §4.3:点位标记不涂红父切片;近邻聚合,重叠可展开选择。
const span = Math.max(sliceTimelineEnd - sliceTimelineStart, 0.001);
const sorted = [...reviewTimestampOpinions].sort((a, b) => a.atSeconds - b.atSeconds);
const clusters: { key: string; opinions: typeof sorted; left: number }[] = [];
for (const opinion of sorted) {
const left = Math.min(100, Math.max(0, ((opinion.atSeconds - sliceTimelineStart) / span) * 100));
const last = clusters[clusters.length - 1];
if (last && Math.abs(last.left - left) < 0.8) last.opinions.push(opinion);
else clusters.push({ key: opinion.id, opinions: [opinion], left });
}
return clusters.map((cluster) => (
<div key={cluster.key} className="absolute top-0" style={{ left: `${cluster.left}%` }}>
<button
type="button"
aria-label={`时间点意见 ${cluster.opinions.length > 1 ? `${cluster.opinions.length} 条` : cluster.opinions[0].text.slice(0, 12)}`}
title={cluster.opinions.map((o) => `${o.atSeconds.toFixed(2)}s ${o.text}`).join("\n")}
onClick={(e) => {
e.stopPropagation();
if (cluster.opinions.length > 1) setOpinionMarkerOpen(opinionMarkerOpen === cluster.key ? null : cluster.key);
else reviewController.seekTime(cluster.opinions[0].atSeconds);
}}
className="-translate-x-1/2 rounded-full border border-orange-500 bg-orange-400 px-1 text-[9px] font-bold leading-3 text-white shadow"
>
{cluster.opinions.length > 1 ? cluster.opinions.length : "•"}
</button>
{cluster.opinions.length > 1 && opinionMarkerOpen === cluster.key && (
<div className="absolute left-0 top-4 z-30 max-h-24 w-44 overflow-auto rounded border border-orange-300 bg-white p-1 text-left text-[10px] shadow-lg dark:border-orange-700 dark:bg-[#151619]">
{cluster.opinions.map((o) => (
<button
key={o.id}
type="button"
onClick={(e) => {
e.stopPropagation();
setOpinionMarkerOpen(null);
reviewController.seekTime(o.atSeconds);
}}
className="block w-full truncate rounded px-1 py-0.5 text-left text-slate-600 hover:bg-orange-50 dark:text-slate-300 dark:hover:bg-orange-950/30"
>
{o.atSeconds.toFixed(2)}s {o.text}
</button>
))}
</div>
)}
</div>
));
})()}
</div>
)}
<div className="timeline-block-track capture-slice-blocks absolute inset-x-0 top-4 h-16">
{visibleSlices.map((slice) => {
const index = slices.findIndex((item) => item.id === slice.id);

View File

@ -11,6 +11,12 @@ export type ReviewPosition = {
actionId: string | null;
selectedActionId: string | null;
};
export type ReviewTimestampOpinion = {
id: string;
atSeconds: number;
text: string;
};
export type ReviewViewingController = {
pause(): void;
pauseAndLocate(): ReviewPosition | null;
@ -36,6 +42,8 @@ export type ReviewViewingProps = {
/** Saved-problem list keyboard navigation: selects and seeks only, never enters text. */
onReviewProblemNavigate?: (direction: -1 | 1) => void;
onReviewTimestampJump?: () => void;
/** maintenance-backlog#02:审查侧时间点意见(切片时间轴顶部标记渲染;§4.3 点位不涂红父切片)。 */
reviewTimestampOpinions?: ReviewTimestampOpinion[];
/** Enter edits the explicitly selected saved problem. */
onReviewProblemEdit?: () => void;
/** Shift+Delete (Mac: also Shift+Backspace) asks confirmation for the selected problem. */

View File

@ -6018,6 +6018,7 @@ export default function AnnotationOperations({ workPage = false }: { workPage?:
if (!reviewDecision.pending) void reviewDraft.save();
}}
onReviewTimestampJump={reviewDraft.jumpTimestampProblem}
reviewTimestampOpinions={reviewDraft.timestampProblems.map((p) => ({ id: p.id, atSeconds: p.atSeconds ?? 0, text: p.text }))}
onReviewProblemNavigate={(direction) =>
reviewDraft.navigateSelection(direction, reviewProblemNavigationSlice)
}
@ -6388,6 +6389,7 @@ export default function AnnotationOperations({ workPage = false }: { workPage?:
if (!reviewDecision.pending) void reviewDraft.save();
}}
onReviewTimestampJump={reviewDraft.jumpTimestampProblem}
reviewTimestampOpinions={reviewDraft.timestampProblems.map((p) => ({ id: p.id, atSeconds: p.atSeconds ?? 0, text: p.text }))}
onReviewProblemNavigate={(direction) =>
reviewDraft.navigateSelection(direction, reviewProblemNavigationSlice)
}