docs record live viewer sync rollout

client/src/lib/changelog.ts

@@ -8,6 +8,23 @@ export type ChangeLogEntry = {
 };
 
 export const CHANGE_LOG_ENTRIES: ChangeLogEntry[] = [
+  {
+    version: "2026.03.16-live-analysis-viewer-full-sync",
+    releaseDate: "2026-03-16",
+    repoVersion: "922a9fb",
+    summary: "多端同步观看改为按持有端快照完整渲染，另一设备可同步看到视频状态、模式、画质、虚拟形象和保存阶段信息。",
+    features: [
+      "viewer 端现在同步显示持有端的会话标题、训练模式、设备端、拍摄视角、画质模式、虚拟形象状态和最近同步时间",
+      "同步观看时的分析阶段、保存阶段、已完成状态也会跟随主端刷新，不再只显示本地默认状态",
+      "viewer 页面会自动关闭拍摄校准弹窗，避免同步观看时被“启用摄像头”流程遮挡",
+      "新增 viewer 同步信息卡，明确允许 1 秒级延迟，并持续显示最近心跳时间",
+    ],
+    tests: [
+      "pnpm exec playwright test tests/e2e/app.spec.ts --grep \"live camera switches into viewer mode|viewer stream|recorder blocks\"",
+      "pnpm build",
+      "部署后线上 smoke: `https://te.hao.work/` 已提供 `assets/index-HRdM3fxq.js` 与 `assets/index-tNGuStgv.css`；同账号 H1 双端登录后，移动端 owner 可开始实时分析，桌面端 `/live-camera` 自动进入同步观看并显示主端信息、同步视频流，owner 点击结束分析后 viewer 会同步进入保存阶段",
+    ],
+  },
   {
     version: "2026.03.16-live-analysis-lock-hardening",
     releaseDate: "2026-03-16",

client/src/pages/LiveCamera.tsx

@@ -121,6 +121,15 @@ type RuntimeSnapshot = {
   phase?: "idle" | "analyzing" | "saving" | "safe" | "failed";
   startedAt?: number;
   durationMs?: number;
+  title?: string;
+  sessionMode?: SessionMode;
+  qualityPreset?: CameraQualityPreset;
+  facingMode?: CameraFacing;
+  deviceKind?: "mobile" | "desktop";
+  avatarEnabled?: boolean;
+  avatarKey?: AvatarKey;
+  avatarLabel?: string;
+  updatedAt?: number;
   currentAction?: ActionType;
   rawAction?: ActionType;
   feedback?: string[];
@@ -534,6 +543,20 @@ function getSessionBand(input: { overallScore: number; knownRatio: number; effec
   return { label: "待加强", tone: "bg-amber-500/10 text-amber-700" };
 }
 
+function getRuntimeSyncDelayMs(lastHeartbeatAt?: string | null) {
+  if (!lastHeartbeatAt) return null;
+  const heartbeatMs = new Date(lastHeartbeatAt).getTime();
+  if (Number.isNaN(heartbeatMs)) return null;
+  return Math.max(0, Date.now() - heartbeatMs);
+}
+
+function formatRuntimeSyncDelay(delayMs: number | null) {
+  if (delayMs == null) return "等待同步";
+  if (delayMs < 1500) return "同步中";
+  if (delayMs < 10_000) return `${(delayMs / 1000).toFixed(1)}s 延迟`;
+  return "同步较慢";
+}
+
 export default function LiveCamera() {
   const { user } = useAuth();
   const utils = trpc.useUtils();
@@ -675,6 +698,13 @@ export default function LiveCamera() {
     leaveStatusRef.current = leaveStatus;
   }, [leaveStatus]);
 
+  useEffect(() => {
+    if (runtimeRole === "viewer") {
+      setShowSetupGuide(false);
+      setSetupStep(0);
+    }
+  }, [runtimeRole]);
+
   useEffect(() => {
     sessionModeRef.current = sessionMode;
   }, [sessionMode]);
@@ -859,6 +889,15 @@ export default function LiveCamera() {
     phase: phase ?? leaveStatusRef.current,
     startedAt: sessionStartedAtRef.current || undefined,
     durationMs: durationMsRef.current,
+    title: runtimeSession?.title ?? `实时分析 ${ACTION_META[currentActionRef.current].label}`,
+    sessionMode: sessionModeRef.current,
+    qualityPreset,
+    facingMode: facing,
+    deviceKind: mobile ? "mobile" : "desktop",
+    avatarEnabled: avatarRenderRef.current.enabled,
+    avatarKey: avatarRenderRef.current.avatarKey,
+    avatarLabel: getAvatarPreset(avatarRenderRef.current.avatarKey)?.label || "猩猩",
+    updatedAt: Date.now(),
     currentAction: currentActionRef.current,
     rawAction: rawActionRef.current,
     feedback: feedbackRef.current,
@@ -868,7 +907,7 @@ export default function LiveCamera() {
     unknownSegments: segmentsRef.current.filter((segment) => segment.isUnknown).length,
     archivedVideoCount: archivedVideosRef.current.length,
     recentSegments: segmentsRef.current.slice(-5),
-  }), []);
+  }), [facing, mobile, qualityPreset, runtimeSession?.title]);
 
   const closeBroadcastPeer = useCallback(() => {
     broadcastSessionIdRef.current = null;
@@ -1644,6 +1683,7 @@ export default function LiveCamera() {
     await startCamera(facing, zoomTargetRef.current, qualityPreset);
   }, [facing, qualityPreset, startCamera]);
 
+  const displayLeaveStatus = runtimeRole === "viewer" ? (runtimeSnapshot?.phase ?? "idle") : leaveStatus;
   const displayAction = runtimeRole === "viewer" ? (runtimeSnapshot?.currentAction ?? "unknown") : currentAction;
   const displayRawAction = runtimeRole === "viewer" ? (runtimeSnapshot?.rawAction ?? "unknown") : rawAction;
   const displayScore = runtimeRole === "viewer" ? (runtimeSnapshot?.liveScore ?? null) : liveScore;
@@ -1655,6 +1695,33 @@ export default function LiveCamera() {
         ...runtimeSnapshot?.stabilityMeta,
       }
     : stabilityMeta;
+  const displaySessionMode = runtimeRole === "viewer"
+    ? (runtimeSnapshot?.sessionMode ?? runtimeSession?.sessionMode ?? sessionMode)
+    : sessionMode;
+  const displayQualityPreset = runtimeRole === "viewer"
+    ? (runtimeSnapshot?.qualityPreset ?? qualityPreset)
+    : qualityPreset;
+  const displayFacing = runtimeRole === "viewer"
+    ? (runtimeSnapshot?.facingMode ?? facing)
+    : facing;
+  const displayDeviceKind = runtimeRole === "viewer"
+    ? (runtimeSnapshot?.deviceKind ?? (mobile ? "mobile" : "desktop"))
+    : (mobile ? "mobile" : "desktop");
+  const displayAvatarEnabled = runtimeRole === "viewer"
+    ? Boolean(runtimeSnapshot?.avatarEnabled)
+    : avatarEnabled;
+  const displayAvatarKey = runtimeRole === "viewer"
+    ? ((runtimeSnapshot?.avatarKey as AvatarKey | undefined) ?? resolvedAvatarKey)
+    : resolvedAvatarKey;
+  const displayAvatarPreset = getAvatarPreset(displayAvatarKey);
+  const displayAvatarLabel = runtimeRole === "viewer"
+    ? (runtimeSnapshot?.avatarLabel ?? displayAvatarPreset?.label ?? "猩猩")
+    : (displayAvatarPreset?.label || "猩猩");
+  const runtimeSyncDelayMs = runtimeRole === "viewer" ? getRuntimeSyncDelayMs(runtimeSession?.lastHeartbeatAt) : null;
+  const runtimeSyncLabel = runtimeRole === "viewer" ? formatRuntimeSyncDelay(runtimeSyncDelayMs) : "";
+  const displayRuntimeTitle = runtimeRole === "viewer"
+    ? (runtimeSnapshot?.title ?? runtimeSession?.title ?? "其他设备实时分析")
+    : (runtimeSession?.title ?? `实时分析 ${ACTION_META[currentAction].label}`);
   const hasVideoFeed = cameraActive || viewerConnected;
   const heroAction = ACTION_META[displayAction];
   const rawActionMeta = ACTION_META[displayRawAction];
@@ -1665,7 +1732,7 @@ export default function LiveCamera() {
   const fullBodyAvatarPresets = AVATAR_PRESETS.filter((preset) => preset.category === "full-body-3d");
   const previewTitle = runtimeRole === "viewer"
     ? viewerConnected
-      ? "同步观看中"
+      ? `${runtimeSyncLabel} · 同步观看中`
       : "正在连接同步画面"
     : analyzing
       ? displayStabilityMeta.pending && pendingActionMeta
@@ -1906,42 +1973,50 @@ export default function LiveCamera() {
         </DialogContent>
       </Dialog>
 
-      {leaveStatus === "analyzing" ? (
+      {displayLeaveStatus === "analyzing" ? (
         <Alert>
           <Activity className="h-4 w-4" />
           <AlertTitle>分析进行中</AlertTitle>
           <AlertDescription>
-            当前仍在采集和识别动作数据，请先不要关闭浏览器或切走页面。
+            {runtimeRole === "viewer"
+              ? "持有端仍在采集和识别动作数据，本页会按会话心跳持续同步视频与动作信息。"
+              : "当前仍在采集和识别动作数据，请先不要关闭浏览器或切走页面。"}
           </AlertDescription>
         </Alert>
       ) : null}
 
-      {leaveStatus === "saving" ? (
+      {displayLeaveStatus === "saving" ? (
         <Alert>
           <Activity className="h-4 w-4" />
           <AlertTitle>正在保存分析结果</AlertTitle>
           <AlertDescription>
-            实时分析录像、动作区间和训练记录正在提交，请暂时停留当前页面；保存完成后会提示你可以离开。
+            {runtimeRole === "viewer"
+              ? "持有端正在提交录像、动作区间和训练记录；本页会同步保存状态，可以稍后再刷新查看。"
+              : "实时分析录像、动作区间和训练记录正在提交，请暂时停留当前页面；保存完成后会提示你可以离开。"}
           </AlertDescription>
         </Alert>
       ) : null}
 
-      {leaveStatus === "safe" ? (
+      {displayLeaveStatus === "safe" ? (
         <Alert>
           <CheckCircle2 className="h-4 w-4" />
           <AlertTitle>分析结果已保存</AlertTitle>
           <AlertDescription>
-            当前分析数据已经提交完成。现在可以关闭浏览器、返回上一页，或切换到其他页面，不会影响已保存的数据。
+            {runtimeRole === "viewer"
+              ? "持有端分析数据已经提交完成；本页显示的是同步结果，你现在可以离开，不会影响已保存的数据。"
+              : "当前分析数据已经提交完成。现在可以关闭浏览器、返回上一页，或切换到其他页面，不会影响已保存的数据。"}
           </AlertDescription>
         </Alert>
       ) : null}
 
-      {leaveStatus === "failed" ? (
+      {displayLeaveStatus === "failed" ? (
         <Alert>
           <Activity className="h-4 w-4" />
           <AlertTitle>分析保存失败</AlertTitle>
           <AlertDescription>
-            当前会话还没有完整写入，请先留在本页并重新尝试结束分析或检查网络状态。
+            {runtimeRole === "viewer"
+              ? "持有端当前会话还没有完整写入，本页会继续显示最后一次同步状态。"
+              : "当前会话还没有完整写入，请先留在本页并重新尝试结束分析或检查网络状态。"}
           </AlertDescription>
         </Alert>
       ) : null}
@@ -1951,7 +2026,7 @@ export default function LiveCamera() {
           <Monitor className="h-4 w-4" />
           <AlertTitle>同步观看模式</AlertTitle>
           <AlertDescription>
-            {viewerModeLabel}。当前设备不会占用本地摄像头，也不能再次开启分析；如需查看同步画面，可直接点击“同步观看”。
+            {viewerModeLabel}。当前设备不会占用本地摄像头，也不能再次开启分析；视频、动作、评分与会话信息会按心跳自动同步，允许 1 秒级延迟。
           </AlertDescription>
         </Alert>
       ) : null}
@@ -1982,21 +2057,29 @@ export default function LiveCamera() {
               </Badge>
               <Badge className="gap-1.5 border-white/10 bg-white/10 text-white hover:bg-white/10">
                 <Camera className="h-3.5 w-3.5" />
-                {avatarEnabled ? `虚拟形象 ${resolvedAvatarLabel}` : "骨架叠加"}
+                {displayAvatarEnabled ? `虚拟形象 ${displayAvatarLabel}` : "骨架叠加"}
               </Badge>
               <Badge className="gap-1.5 border-white/10 bg-white/10 text-white hover:bg-white/10">
                 <PlayCircle className="h-3.5 w-3.5" />
-                {(runtimeRole === "viewer" ? runtimeSession?.sessionMode : sessionMode) === "practice" ? "练习会话" : "训练 PK"}
+                {displaySessionMode === "practice" ? "练习会话" : "训练 PK"}
               </Badge>
               <Badge className="gap-1.5 border-white/10 bg-white/10 text-white hover:bg-white/10">
                 <Video className="h-3.5 w-3.5" />
-                默认 {CAMERA_QUALITY_PRESETS[qualityPreset].label}
+                默认 {CAMERA_QUALITY_PRESETS[displayQualityPreset].label}
               </Badge>
+              {runtimeRole === "viewer" ? (
+                <Badge className="gap-1.5 border-white/10 bg-white/10 text-white hover:bg-white/10" data-testid="live-camera-viewer-delay-badge">
+                  <Monitor className="h-3.5 w-3.5" />
+                  {runtimeSyncLabel}
+                </Badge>
+              ) : null}
             </div>
             <div>
-              <h1 className="text-3xl font-semibold tracking-tight">实时分析中枢</h1>
+              <h1 className="text-3xl font-semibold tracking-tight">{displayRuntimeTitle}</h1>
               <p className="mt-2 max-w-2xl text-sm leading-6 text-white/70">
-                摄像头启动后会持续识别正手、反手、发球、截击、高压、切削、挑高球与未知动作。系统会用 24 帧时间窗口统一动作，再把稳定动作写入片段、训练记录与评分；分析过程中会自动录制“视频画面 + 骨架/关键点叠层”的合成回放，并按 60 秒分段归档进视频库。开启虚拟形象后，画面中的人体可切换为 10 个轻量动物替身，或 4 个免费的全身 3D Avatar 示例覆盖显示。
+                {runtimeRole === "viewer"
+                  ? `当前正在同步 ${displayDeviceKind === "mobile" ? "移动端" : "桌面端"} ${displayFacing === "environment" ? "后置/主摄视角" : "前置视角"} 画面。视频、动作、评分、最近区间、虚拟形象和会话状态会自动跟随持有端刷新，允许少量网络延迟。`
+                  : "摄像头启动后会持续识别正手、反手、发球、截击、高压、切削、挑高球与未知动作。系统会用 24 帧时间窗口统一动作，再把稳定动作写入片段、训练记录与评分；分析过程中会自动录制“视频画面 + 骨架/关键点叠层”的合成回放，并按 60 秒分段归档进视频库。开启虚拟形象后，画面中的人体可切换为 10 个轻量动物替身，或 4 个免费的全身 3D Avatar 示例覆盖显示。"}
               </p>
             </div>
           </div>
@@ -2082,10 +2165,10 @@ export default function LiveCamera() {
                     <Target className="h-3.5 w-3.5" />
                     非未知片段 {displayVisibleSegments.length}
                   </Badge>
-                  {avatarEnabled ? (
+                  {displayAvatarEnabled ? (
                     <Badge className="gap-1.5 bg-black/60 text-white shadow-sm">
                       <Sparkles className="h-3.5 w-3.5" />
-                      虚拟形象 {resolvedAvatarLabel}
+                      虚拟形象 {displayAvatarLabel}
                     </Badge>
                   ) : null}
                 </div>
@@ -2133,7 +2216,7 @@ export default function LiveCamera() {
               <div className="border-t border-border/60 bg-card/80 p-4">
               <div className="grid gap-3 md:grid-cols-[180px_minmax(0,1fr)]">
                   <Select
-                    value={runtimeRole === "viewer" ? (runtimeSession?.sessionMode ?? sessionMode) : sessionMode}
+                    value={displaySessionMode}
                     onValueChange={(value) => setSessionMode(value as SessionMode)}
                     disabled={analyzing || saving || runtimeRole === "viewer"}
                   >
@@ -2150,6 +2233,29 @@ export default function LiveCamera() {
                   </div>
                 </div>
                 <div className="mt-4 grid gap-3 rounded-[24px] border border-border/60 bg-muted/15 p-4 md:grid-cols-3">
+                  {runtimeRole === "viewer" ? (
+                    <div className="rounded-2xl border border-border/60 bg-background/90 p-4 md:col-span-3" data-testid="live-camera-viewer-sync-card">
+                      <div className="flex flex-wrap items-start justify-between gap-3">
+                        <div>
+                          <div className="text-[11px] uppercase tracking-[0.16em] text-muted-foreground">同步中的主端信息</div>
+                          <div className="mt-2 text-lg font-semibold">{displayRuntimeTitle}</div>
+                          <div className="mt-2 grid gap-2 text-xs text-muted-foreground sm:grid-cols-2">
+                            <div>设备端：{displayDeviceKind === "mobile" ? "移动端" : "桌面端"}</div>
+                            <div>拍摄视角：{displayFacing === "environment" ? "后置 / 主摄" : "前置"}</div>
+                            <div>画质模式：{CAMERA_QUALITY_PRESETS[displayQualityPreset].label}</div>
+                            <div>虚拟形象：{displayAvatarEnabled ? displayAvatarLabel : "未开启"}</div>
+                          </div>
+                        </div>
+                        <div className="min-w-[150px] rounded-2xl border border-border/60 bg-muted/20 px-4 py-3 text-sm">
+                          <div className="text-[11px] uppercase tracking-[0.16em] text-muted-foreground">最近同步</div>
+                          <div className="mt-2 font-semibold">{runtimeSyncLabel}</div>
+                          <div className="mt-1 text-xs text-muted-foreground">
+                            {runtimeSession?.lastHeartbeatAt ? formatDateTimeShanghai(runtimeSession.lastHeartbeatAt) : "等待首个心跳"}
+                          </div>
+                        </div>
+                      </div>
+                    </div>
+                  ) : null}
                   <div className="rounded-2xl border border-border/60 bg-background/90 p-4">
                     <div className="text-[11px] uppercase tracking-[0.16em] text-muted-foreground">自动分析录像</div>
                     <div className="mt-2 text-lg font-semibold">每 60 秒自动切段</div>
@@ -2482,11 +2588,11 @@ export default function LiveCamera() {
                 <div className="flex items-center justify-between text-sm">
                   <span>未知动作占比</span>
                   <span className="font-medium">
-                    {segments.length > 0 ? `${Math.round((unknownSegments.length / segments.length) * 100)}%` : "0%"}
+                    {totalDisplaySegments > 0 ? `${Math.round(((runtimeRole === "viewer" ? (runtimeSnapshot?.unknownSegments ?? 0) : unknownSegments.length) / totalDisplaySegments) * 100)}%` : "0%"}
                   </span>
                 </div>
                 <Progress
-                  value={segments.length > 0 ? (unknownSegments.length / segments.length) * 100 : 0}
+                  value={totalDisplaySegments > 0 ? (((runtimeRole === "viewer" ? (runtimeSnapshot?.unknownSegments ?? 0) : unknownSegments.length) / totalDisplaySegments) * 100) : 0}
                   className="mt-3 h-2"
                 />
               </div>
@@ -2564,10 +2670,10 @@ export default function LiveCamera() {
                   <Sparkles className="h-3.5 w-3.5" />
                   {heroAction.label}
                 </Badge>
-                {avatarEnabled ? (
+                {displayAvatarEnabled ? (
                   <Badge className="gap-1.5 bg-black/60 text-white shadow-sm">
                     <Camera className="h-3.5 w-3.5" />
-                    {resolvedAvatarLabel}
+                    {displayAvatarLabel}
                   </Badge>
                 ) : null}
                 <Badge className="gap-1.5 bg-black/60 text-white shadow-sm">

docs/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Tennis Training Hub - 变更日志
 
+## 2026.03.16-live-analysis-viewer-full-sync (2026-03-16)
+
+### 功能更新
+
+- 同账号多端同步观看时，viewer 端现在会按持有端 runtime snapshot 完整渲染，不再混用本地默认状态
+- `/live-camera` viewer 端新增主端同步信息卡，可看到当前会话标题、训练模式、设备端、拍摄视角、画质模式、虚拟形象状态和最近同步时间
+- viewer 端现在会同步显示主端当前处于“分析中 / 保存中 / 已保存 / 保存失败”的阶段状态
+- viewer 页面在同步观看模式下会自动关闭拍摄校准弹窗，避免被“启用摄像头”引导遮挡画面和状态信息
+
+### 测试
+
+- `pnpm exec playwright test tests/e2e/app.spec.ts --grep "live camera switches into viewer mode|viewer stream|recorder blocks"`
+- `pnpm build`
+- `playwright-skill` 线上 smoke：同账号 `H1` 双端登录后，移动端 owner 开始实时分析，桌面端 `/live-camera` 进入同步观看并显示主端信息、同步视频流，owner 点击结束分析后 viewer 同步进入保存阶段
+
+### 线上 smoke
+
+- `https://te.hao.work/` 已切换到本次新构建
+- 当前公开站点前端资源 revision：`assets/index-HRdM3fxq.js` 与 `assets/index-tNGuStgv.css`
+- 真实双端验证已通过：同账号 `H1` 在移动端开启实时分析后，桌面端 `/live-camera` 会自动进入同步观看模式，显示主端设备信息、最近同步时间和远端视频流；owner 点击结束分析后，viewer 会同步进入“保存中”阶段
+
+### 仓库版本
+
+- `922a9fb`
+
 ## 2026.03.16-live-analysis-lock-hardening (2026-03-16)
 
 ### 功能更新

tests/e2e/app.spec.ts

@@ -75,6 +75,10 @@ test("live camera switches into viewer mode when another device already owns ana
   await expect(page.getByText("同步观看模式")).toBeVisible();
   await expect(page.getByText(/同步观看|重新同步/).first()).toBeVisible();
   await expect(page.getByText("当前设备已锁定为观看模式")).toBeVisible();
+  await expect(page.getByTestId("live-camera-viewer-sync-card")).toContainText("其他设备实时分析");
+  await expect(page.getByTestId("live-camera-viewer-sync-card")).toContainText("移动端");
+  await expect(page.getByTestId("live-camera-viewer-sync-card")).toContainText("均衡模式");
+  await expect(page.getByTestId("live-camera-viewer-sync-card")).toContainText("猩猩");
   await expect(page.getByTestId("live-camera-score-overall")).toBeVisible();
 });
 

tests/e2e/helpers/mockApp.ts

@@ -776,6 +776,15 @@ export async function installAppMocks(
             lastHeartbeatAt: nowIso(),
             snapshot: {
               phase: "analyzing",
+              title: "其他设备实时分析",
+              sessionMode: "practice",
+              qualityPreset: "balanced",
+              facingMode: "environment",
+              deviceKind: "mobile",
+              avatarEnabled: true,
+              avatarKey: "gorilla",
+              avatarLabel: "猩猩",
+              updatedAt: Date.parse(nowIso()),
               currentAction: "forehand",
               rawAction: "forehand",
               durationMs: 3200,