✨ Add focused annotation shell with lossless layout fallback

This commit is contained in:
d-robotics 2026-09-18 02:40:49 +08:00
parent ee2e355ba1
commit a575373167
6 changed files with 386 additions and 8 deletions

View File

@ -0,0 +1,19 @@
# 标注工作页的专注视图与原布局
从任务池选择项目并点击“开始工作”,仍使用现有的领取与继续任务链路,在当前标签页进入工作页。没有布局偏好的账号默认进入专注视图,收起平台导航和状态栏;“返回任务池”保留原有未保存修改确认。
工作页顶部的“切回原布局”恢复现有工作页及平台导航;“进入专注视图”再次收起导航。入口随编辑页面滚动保持可达。任务池原入口仍保持原有呈现。
布局选择只属于当前账号和当前浏览器,不是项目设置,也不会写入服务端。浏览器禁用本地存储时仍可切换,但无法保证刷新后记住选择。刷新、关闭或重新打开页面后仍需显式“继续工作”,仅恢复后端保存内容,不自动领取任务,也不恢复未保存草稿和撤销历史。
运行中切换布局只改变外壳。任务、阶段、播放位置、选中切片、各片草稿和撤销/重做共用原编辑会话;切换不会保存、释放或重新领取任务。正在处理的保存仍归属原会话,原有处理中限制继续生效。
本次交付为任务 01 的专注外壳与原布局回退;两阶段左右分栏、画面尺寸下限、长内容分页和免页面滚动由后续布局任务交付。
## 源码恢复与业务数据恢复
原键盘工作流的源码恢复点为本地标签 `codex/annotation-keyboard-baseline-20260918`,指向提交 `54a35afad95d77b1f23c955f9c4671cae83a664d`。本地忽略目录中的完整备份为 `local-data/backups/annotation-keyboard-baseline-20260918.bundle`。任务 01 核验标签指向与 `git bundle verify` 均通过;备份包含完整历史。
工作中的“切回原布局”与 Git 源码恢复是两件事:前者保留当前编辑会话,后者恢复整版代码。Git 标签和 bundle 不恢复数据库、下载媒体、浏览器未保存草稿或撤销记录;业务数据需要独立备份与恢复。本次没有恢复源码、回滚业务数据、推送或部署。
本地浏览器回归脚本:`tests/browser/annotation-workspace-shell.mjs`。使用隔离本地项目和已有认证会话文件,覆盖导航回退、刷新偏好、实际媒体/帧与草稿保留、延迟保存 API 回读以及撤销/重做。传入第二个真实本地账号的会话文件可额外验证同一浏览器存储中的账号隔离。会话文件和原始测试证据仅存放在忽略的 `local-data/` 中。

View File

@ -1,4 +1,9 @@
import React, { useEffect, useRef, useState } from "react";
import { useLocation } from "react-router-dom";
import {
AnnotationWorkspaceLayoutContext,
useAnnotationLayoutPreference,
} from "../context/AnnotationWorkspaceLayoutContext";
import { Loader2, Moon, Sun } from "lucide-react";
import { Sidebar } from "./Sidebar";
import { UserBootstrapPanel } from "./UserBootstrapPanel";
@ -42,6 +47,14 @@ export function Layout({ children }: LayoutProps) {
const lastHealthErrorRef = useRef("");
const { currentUser, isSuperAdmin, loading } = useUser();
const { theme, toggleTheme } = useTheme();
const { pathname } = useLocation();
const workspaceLayout = useAnnotationLayoutPreference(currentUser?.id || "");
const focusedWorkPage = Boolean(
currentUser &&
!isSuperAdmin &&
/^\/plugins\/annotation-qa\/workflows\/[^/]+\/work\/?$/.test(pathname) &&
workspaceLayout.layout === "focused",
);
useEffect(() => {
const mobileViewport = window.matchMedia("(max-width: 767px)");
@ -165,12 +178,19 @@ export function Layout({ children }: LayoutProps) {
: "服务在线,readiness 异常";
return (
<div className="flex h-screen bg-[color:var(--app-canvas)] font-sans text-[color:var(--app-text)]">
{currentUser && !isSuperAdmin ? (
<div
data-annotation-layout={focusedWorkPage ? "focused" : undefined}
className="flex h-screen bg-[color:var(--app-canvas)] font-sans text-[color:var(--app-text)]"
>
{currentUser && !isSuperAdmin && !focusedWorkPage ? (
<Sidebar isCollapsed={isCollapsed} onToggle={() => setIsCollapsed(!isCollapsed)} />
) : null}
<main className="relative flex min-w-0 flex-1 flex-col overflow-hidden">
<header aria-label="平台状态与主题" className="relative z-40 flex h-12 shrink-0 items-center justify-end gap-3 border-b border-[color:var(--app-border)] bg-[color:var(--app-canvas)] px-3">
<header
hidden={focusedWorkPage}
aria-label="平台状态与主题"
className="relative z-40 flex h-12 shrink-0 items-center justify-end gap-3 border-b border-[color:var(--app-border)] bg-[color:var(--app-canvas)] px-3"
>
<button
type="button"
onClick={toggleTheme}
@ -270,7 +290,9 @@ export function Layout({ children }: LayoutProps) {
</section>
</details>
</header>
<div className="min-h-0 flex-1 overflow-auto p-4 md:p-6">
<div
className={focusedWorkPage ? "min-h-0 flex-1 overflow-auto p-3" : "min-h-0 flex-1 overflow-auto p-4 md:p-6"}
>
{loading ? (
<div className="flex h-full items-center justify-center">
<div className="flex items-center gap-3 rounded-2xl border border-[color:var(--app-border)] bg-[color:var(--app-panel)] px-6 py-4 text-sm text-slate-600 shadow-sm dark:text-gray-400">
@ -281,7 +303,9 @@ export function Layout({ children }: LayoutProps) {
) : currentUser && isSuperAdmin ? (
<SuperAdminConsole />
) : currentUser ? (
children
<AnnotationWorkspaceLayoutContext.Provider value={workspaceLayout}>
{children}
</AnnotationWorkspaceLayoutContext.Provider>
) : (
<UserBootstrapPanel />
)}

View File

@ -0,0 +1,46 @@
import { createContext, useContext, useMemo, useState } from "react";
type WorkspaceLayout = "focused" | "original";
type LayoutPreference = { layout: WorkspaceLayout; toggleLayout: () => void };
export const AnnotationWorkspaceLayoutContext = createContext<LayoutPreference | null>(null);
function readPreference(userId: string): WorkspaceLayout {
if (!userId) return "focused";
try {
return window.localStorage.getItem(`droboticflow.annotation-layout:${userId}`) === "original"
? "original"
: "focused";
} catch {
return "focused";
}
}
// Presentation has no task/session identity. Account changes read that account's
// preference synchronously, so even the first render cannot reuse another user's.
export function useAnnotationLayoutPreference(userId: string): LayoutPreference {
const [choice, setChoice] = useState<{ userId: string; layout: WorkspaceLayout } | null>(null);
const layout = choice?.userId === userId ? choice.layout : readPreference(userId);
return useMemo(
() => ({
layout,
toggleLayout: () => {
if (!userId) return;
const next = layout === "focused" ? "original" : "focused";
setChoice({ userId, layout: next });
try {
window.localStorage.setItem(`droboticflow.annotation-layout:${userId}`, next);
} catch {
// Storage restrictions must not prevent an in-place fallback.
}
},
}),
[layout, userId],
);
}
export function useAnnotationWorkspaceLayout() {
const value = useContext(AnnotationWorkspaceLayoutContext);
if (!value) throw new Error("Annotation workspace layout requires the application shell");
return value;
}

View File

@ -1,4 +1,5 @@
import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useAnnotationWorkspaceLayout } from "../context/AnnotationWorkspaceLayoutContext";
import { memberCanClaim, memberPoolEmptyReason } from "../lib/member-scope.js";
import { newAnnotationClaimRequestID } from "../lib/annotation-random-claim.js";
import { createAnnotationHistory } from "../lib/annotation-history.js";
@ -483,6 +484,7 @@ function assignmentRoleLabel(role: HumanAssignmentRole) {
export default function AnnotationOperations({ workPage = false }: { workPage?: boolean }) {
const { users, role, currentUser } = useUser();
const { layout: workspaceLayout, toggleLayout } = useAnnotationWorkspaceLayout();
const { statuses: pluginStatuses } = usePlugins();
const { timeZone } = useTimeZone();
const [searchParams, setSearchParams] = useSearchParams();
@ -3456,6 +3458,7 @@ export default function AnnotationOperations({ workPage = false }: { workPage?:
className="annotation-operations-page space-y-4"
data-adaptive-slice={adaptiveSliceLayout || undefined}
data-work-page={workPage || undefined}
data-workspace-layout={workPage ? workspaceLayout : undefined}
>
{pendingTaskId !== null || leaveBlocker.state === "blocked" ? (
<div className="fixed inset-0 z-[70] flex items-center justify-center bg-black/70 p-4">
@ -3506,9 +3509,14 @@ export default function AnnotationOperations({ workPage = false }: { workPage?:
连续工作状态与停止选项见下方
</p>
</div>
<Link to={workPoolPath} className="rounded-lg border px-3 py-2 text-sm">
返回任务池
</Link>
<div className="flex items-center gap-2">
<button type="button" onClick={toggleLayout} className="rounded-lg border px-3 py-2 text-sm">
{workspaceLayout === "focused" ? "切回原布局" : "进入专注视图"}
</button>
<Link to={workPoolPath} className="rounded-lg border px-3 py-2 text-sm">
返回任务池
</Link>
</div>
</div>
) : (
<>

View File

@ -327,3 +327,16 @@
grid-template-rows: minmax(900px, 1fr);
}
}
/* Keep the presentation escape hatch reachable while the original editor scrolls.
These rules change chrome only; the editor and media retain their DOM identity. */
[data-annotation-layout="focused"] > main > header[hidden] {
display: none;
}
.annotation-operations-page[data-work-page] .annotation-workspace-heading {
position: sticky;
top: 0;
z-index: 45;
background: var(--app-canvas);
}

View File

@ -0,0 +1,268 @@
// Local integration acceptance. Uses an authenticated local browser session and
// existing isolated keyboard fixtures; never point this at a deployed service.
// Removing chrome isolation, remounting the editor, or dropping account preference
// must fail observable UI assertions here, independently of component internals.
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { chromium } from "playwright";
const baseURL = "http://127.0.0.1:5173";
assert.ok(process.env.ANNOTATION_STORAGE_STATE, "Set ANNOTATION_STORAGE_STATE to a local authenticated state file");
const browser = await chromium.launch({
executablePath:
process.env.PLAYWRIGHT_EXECUTABLE_PATH || "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
headless: true,
args: ["--no-proxy-server"],
});
const context = await browser.newContext({
storageState: process.env.ANNOTATION_STORAGE_STATE,
viewport: { width: 1440, height: 900 },
});
const page = await context.newPage();
page.setDefaultTimeout(15000);
const project = process.env.ANNOTATION_PROJECT_ID || "project-workspace-layout-acceptance";
const task = process.env.ANNOTATION_TASK_ID || "annotation-task-workspace-layout-acceptance-annotate-primary";
const pool = `/plugins/annotation-qa/workflows/all/annotate?projectId=${project}&taskId=${task}`;
const work = `/plugins/annotation-qa/workflows/all/work?projectId=${project}&taskId=${task}`;
const chrome = page.locator('header[aria-label="平台状态与主题"]');
try {
// The ordinary task entry remains the established workbench and platform shell.
await page.goto(baseURL + pool, { waitUntil: "domcontentloaded" });
await page.getByTestId("capture-annotation-workbench").waitFor();
assert.ok(await chrome.isVisible(), "original task entry has platform navigation");
assert.equal(await page.getByRole("button", { name: "切回原布局", exact: true }).count(), 0);
console.log("PASS original task entry baseline");
const writes = [];
page.on("request", (request) => {
if (request.method() !== "GET" && /random-claims|\/tasks\/|\/human-items\//.test(request.url()))
writes.push(request.url());
});
await page.getByRole("button", { name: "开始工作", exact: true }).click();
await page.waitForURL((url) => url.pathname.endsWith("/work"), { waitUntil: "domcontentloaded" });
await page.getByTestId("capture-annotation-workbench").waitFor();
assert.ok(new URL(page.url()).pathname.endsWith("/work"), "existing start-work entry opens focused work in this tab");
assert.equal(context.pages().length, 1, "work remains in the same tab");
await page.getByRole("button", { name: "完成当前任务后停止", exact: true }).click();
assert.equal(writes.length, 0, "start work resumes the owned task without a new claim");
console.log("PASS existing start-work entry, owned-first continuation and stop control");
await page.goto(baseURL + work, { waitUntil: "domcontentloaded" });
await page.getByRole("region", { name: "恢复工作会话" }).waitFor();
assert.equal(await chrome.isVisible(), false, "default focused layout hides platform chrome");
await page.getByRole("button", { name: "切回原布局", exact: true }).click();
assert.ok(await chrome.isVisible(), "original layout restores real platform chrome");
await page.reload({ waitUntil: "domcontentloaded" });
await page.getByRole("region", { name: "恢复工作会话" }).waitFor();
assert.ok(await chrome.isVisible(), "same-account original preference survives reload");
assert.equal(
await page.getByTestId("capture-annotation-workbench").count(),
0,
"refresh still requires explicit recovery",
);
assert.equal(writes.length, 0, "preference and refresh never acquire or write tasks");
await page.getByRole("button", { name: "进入专注视图", exact: true }).click();
assert.equal(await chrome.isVisible(), false);
console.log("PASS focused default, original fallback, preference and explicit refresh recovery");
await page.getByRole("button", { name: "继续工作", exact: true }).click();
const workbench = page.getByTestId("capture-annotation-workbench");
await workbench.waitFor();
await page.waitForFunction(
() =>
[...document.querySelectorAll("video")].length === 2 &&
[...document.querySelectorAll("video")].every((video) => video.readyState >= 2),
{ timeout: 60000 },
);
const videos = await page.locator("video").elementHandles();
const editorNode = await workbench.elementHandle();
await workbench.focus();
await page.keyboard.press("ArrowRight");
await page.waitForFunction(() => document.querySelector("video").currentTime > 0);
const frameBefore = await page
.locator("video")
.first()
.evaluate((video) => video.currentTime);
await page.getByTestId("annotation-description-block").first().click();
const description = page.getByRole("textbox", { name: "动作描述", exact: true });
const originalText = await description.inputValue();
const savedText = `Layout acceptance ${Date.now()}`;
await description.fill(savedText);
await description.scrollIntoViewIfNeeded();
const switchBounds = await page.getByRole("button", { name: "切回原布局", exact: true }).boundingBox();
assert.ok(
switchBounds && switchBounds.y >= 0 && switchBounds.y + switchBounds.height <= 900,
"layout fallback stays visible while editing lower content",
);
for (let index = 0; index < 3; index++) {
await page.getByRole("button", { name: "切回原布局", exact: true }).click();
await page.getByRole("button", { name: "进入专注视图", exact: true }).click();
}
assert.equal(await description.inputValue(), savedText);
assert.ok(await editorNode.evaluate((node) => node.isConnected), "same editor DOM remains mounted");
for (const video of videos)
assert.ok(await video.evaluate((node) => node.isConnected), "same media nodes remain mounted");
assert.equal(
await page
.locator("video")
.first()
.evaluate((video) => video.currentTime),
frameBefore,
);
assert.equal(writes.length, 0, "toggles never save or claim");
if (process.env.ANNOTATION_EVIDENCE_DIR)
await page.screenshot({ path: `${process.env.ANNOTATION_EVIDENCE_DIR}/task01-focused.png` });
// Park another slice's unfinished description and verify both buffers survive.
await workbench.focus();
await page.keyboard.press("Control+ArrowRight");
await page.getByRole("button", { name: "新增动作描述", exact: true }).click();
await workbench.focus();
await page.keyboard.press("ArrowRight");
await page.getByRole("button", { name: "确认结束点", exact: true }).click();
await description.fill("Second slice parked draft");
await page.getByRole("button", { name: "切回原布局", exact: true }).click();
await workbench.focus();
await page.keyboard.press("Control+ArrowLeft");
assert.equal(await description.inputValue(), savedText);
await workbench.focus();
await page.keyboard.press("Control+ArrowRight");
assert.equal(await description.inputValue(), "Second slice parked draft");
await workbench.focus();
await page.keyboard.press("Control+ArrowLeft");
await page.getByRole("button", { name: "进入专注视图", exact: true }).click();
assert.equal(await description.inputValue(), savedText);
await page.getByRole("link", { name: "返回任务池", exact: true }).click();
await page.getByRole("dialog", { name: "离开未保存修改确认" }).waitFor();
await page.getByRole("button", { name: "继续编辑", exact: true }).click();
assert.equal(await description.inputValue(), savedText);
console.log("PASS media/frame identity, repeated toggle, per-slice drafts, shortcuts, dirty leave guard");
const itemURL = `${baseURL}/api/human-items/${task.replace("annotation-task-", "human-item-")}`;
const readItem = async () => {
const response = await context.request.get(itemURL);
assert.ok(response.ok(), "authoritative API readback succeeds");
return (await response.json()).item;
};
const beforeSave = await readItem();
let releaseResponse;
const responseHeld = new Promise((resolve) => {
releaseResponse = resolve;
});
let serverSaved;
const serverDone = new Promise((resolve) => {
serverSaved = resolve;
});
const confirmationURL = `**/tasks/${task}/annotation-confirmations`;
await page.route(confirmationURL, async (route) => {
const response = await route.fetch();
assert.ok(response.ok(), "real save reaches server successfully");
serverSaved();
await responseHeld;
await route.fulfill({ response });
});
await description.press("Control+Enter");
await serverDone;
await page.getByRole("button", { name: "切回原布局", exact: true }).click();
assert.ok(
await page.getByRole("button", { name: "确认保存描述", exact: true }).isDisabled(),
"pending save remains locked after layout switch",
);
assert.equal(await description.inputValue(), savedText);
assert.equal(writes.length, 1, "exactly one save while response held");
releaseResponse();
await page.waitForFunction(() => !document.querySelector('[aria-label="动作描述"]'));
await page.unroute(confirmationURL);
const afterSave = await readItem();
assert.equal(afterSave.version, beforeSave.version + 1);
assert.ok(
afterSave.subject.payload.annotationWorkspace.segments.some((segment) => segment.description === savedText),
);
await page.getByRole("button", { name: "进入专注视图", exact: true }).click();
await workbench.focus();
const undone = page.waitForResponse(
(response) => response.url().endsWith("annotation-confirmations") && response.request().method() === "POST",
);
await page.keyboard.press("Control+z");
assert.ok((await undone).ok());
assert.ok(
(await readItem()).subject.payload.annotationWorkspace.segments.some(
(segment) => segment.description === originalText,
),
"undo restores original persisted description after toggling",
);
await page.getByRole("button", { name: "切回原布局", exact: true }).click();
await page.waitForTimeout(1100); // Existing history contract throttles undo/redo for one second.
await workbench.focus();
const redone = page.waitForResponse(
(response) => response.url().endsWith("annotation-confirmations") && response.request().method() === "POST",
);
await page.keyboard.press("Control+Shift+z");
assert.ok((await redone).ok());
assert.ok(
(await readItem()).subject.payload.annotationWorkspace.segments.some(
(segment) => segment.description === savedText,
),
"redo restores the saved edit in original layout",
);
assert.equal(writes.length, 3, "save, undo and redo are the only writes; no claim or release");
if (process.env.ANNOTATION_EVIDENCE_DIR)
await page.screenshot({ path: `${process.env.ANNOTATION_EVIDENCE_DIR}/task01-original.png` });
console.log(
"PASS delayed real save across toggle, pending restrictions, public API readback and persisted undo/redo",
);
// A fresh route entry preserves the original slice editor and its history.
page.on("dialog", (dialog) => dialog.accept());
await page.goto(baseURL + work.replace("annotate-primary", "slice-primary"), { waitUntil: "domcontentloaded" });
await page.getByRole("button", { name: "继续工作", exact: true }).click();
await workbench.waitFor();
await page.waitForFunction(() => [...document.querySelectorAll("video")].every((video) => video.readyState >= 2));
const boundaries = page.getByRole("button", { name: "删除切片", exact: true });
const countBefore = await boundaries.count();
await workbench.focus();
for (let frame = 0; frame < 6; frame++) await page.keyboard.press("ArrowRight");
await page.keyboard.press("c");
assert.equal(await boundaries.count(), countBefore + 1, "C splits in the original editor");
await page.getByRole("button", { name: "进入专注视图", exact: true }).click();
assert.equal(await boundaries.count(), countBefore + 1);
await workbench.focus();
await page.keyboard.press("Control+z");
assert.equal(await boundaries.count(), countBefore);
await page.getByRole("button", { name: "切回原布局", exact: true }).click();
await page.waitForTimeout(1100);
await workbench.focus();
await page.keyboard.press("Control+Shift+z");
assert.equal(await boundaries.count(), countBefore + 1);
assert.equal(writes.length, 3, "slice edits and toggles do not submit, release or claim");
console.log("PASS original slicing shortcut and in-memory undo/redo across layouts");
if (process.env.ANNOTATION_SECOND_STORAGE_STATE) {
// Replace only authenticated cookies, retaining this exact origin's preference
// storage. A new empty browser context would not prove account isolation.
await context.addCookies(JSON.parse(readFileSync(process.env.ANNOTATION_SECOND_STORAGE_STATE, "utf8")).cookies);
await page.goto(baseURL + work, { waitUntil: "domcontentloaded" });
await page.getByRole("button", { name: "切回原布局", exact: true }).waitFor();
assert.equal(
await chrome.isVisible(),
false,
"another actual account defaults focused despite first account's original preference",
);
await page.getByRole("button", { name: "切回原布局", exact: true }).click();
await context.addCookies(JSON.parse(readFileSync(process.env.ANNOTATION_STORAGE_STATE, "utf8")).cookies);
await page.reload({ waitUntil: "domcontentloaded" });
await page.getByRole("button", { name: "进入专注视图", exact: true }).waitFor();
await page.getByRole("button", { name: "进入专注视图", exact: true }).click();
await context.addCookies(JSON.parse(readFileSync(process.env.ANNOTATION_SECOND_STORAGE_STATE, "utf8")).cookies);
await page.reload({ waitUntil: "domcontentloaded" });
await page.getByRole("button", { name: "进入专注视图", exact: true }).waitFor();
assert.ok(
await chrome.isVisible(),
"second account original preference is independent of first account focused choice",
);
assert.equal(writes.length, 3, "account preference checks perform no task writes");
console.log("PASS actual account isolation in the same browser origin storage");
}
} finally {
await context.close();
await browser.close();
}