Files
ttstd-infinite-canvas/web/src/lib/canvas/director/director-onboarding.ts
T

246 lines
12 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { localForageStorageForScope } from "@/lib/localforage-storage";
import type { DirectorMode } from "@/lib/canvas/director/director-modes";
/**
* 导演台首次上手引导。
*
* 为什么存在:导演台把模板、四个一级模式、对象操作、保存/导出堆在同一个工作台里,
* 第一次进来的人没有任何线索该先做什么。引导给出一条确定的最短路径。
*
* 硬约束:
* - 纯状态机 + 持久化,绝不触碰 DirectorScene,也不写 undo/redo 历史:
* 引导是「用户看到什么提示」,不是场景内容。
* - 进度按用户隔离。所有导出 API 必须显式收到非空 scope,禁止内部兜底成 guest ——
* 默认 scope 会让 A 账号的引导状态泄漏给 B 账号。
* - 只用 localforage(走 localForageStorageForScope),不用 localStorage:
* 与项目里其他用户态持久化保持同一条通道。
* - 缺失、损坏、版本不符的持久数据一律回落到初始进度;只有存储层本身失败才向上抛。
*/
export type DirectorOnboardingStepId = "actor" | "move" | "pose" | "path" | "camera" | "apply";
/** active 才展示。dismissed(用户跳过)与 completed(走完)都不再展示,且不可被 next/back 唤醒。 */
export type DirectorOnboardingStatus = "active" | "dismissed" | "completed";
/**
* 进度 schema 版本。
* 步骤集合发生语义变化(增删步骤、改变顺序)时必须 +1:
* 旧进度里的 stepId 在新步骤表里可能不存在,继续沿用会把用户卡在不存在的步骤上。
*/
export const DIRECTOR_ONBOARDING_VERSION = 2;
/** localforage 键名。真实键由 localForageStorageForScope 追加 `:user:<scope>`。 */
export const DIRECTOR_ONBOARDING_KEY = "director-onboarding-v2";
export type DirectorOnboardingStep = {
id: DirectorOnboardingStepId;
title: string;
/** 一句话说清「在哪儿点什么」,不解释概念。 */
detail: string;
/**
* 该步骤应该在哪个一级模式里完成。
* 模式巡览步骤本身没有单一归属,故为 undefined —— 由 UI 决定是否代为切换模式。
*/
mode?: DirectorMode;
};
/** 引导步骤按首次使用的最短操作路径排列:添加演员 → 移动 → 调姿 → 轨迹 → CAM → 应用。 */
export const DIRECTOR_ONBOARDING_STEPS: DirectorOnboardingStep[] = [
{ id: "actor", title: "添加并选中演员", detail: "在左侧「快速添加」点演员;模板已有演员时,直接在场景树或视口选中它。", mode: "layout" },
{ id: "move", title: "把演员移动到表演位置", detail: "保持摆场模式,在底部 dock 选移动工具(W),拖动轴手柄;右栏可输入精确坐标。", mode: "layout" },
{ id: "pose", title: "调整演员姿态", detail: "切到姿态模式,在右侧选择姿势预设;模型有骨骼时还可选择手臂、腿和躯干微调。", mode: "pose" },
{ id: "path", title: "记录一段走位", detail: "切到动画模式,在起点和终点分别移动播放头、摆放演员并记录 Transform 关键帧,再播放预览。", mode: "animate" },
{ id: "camera", title: "用 CAM 检查构图", detail: "切到摄影机模式,再点视口工具栏 CAM;调整焦距、焦点和机位,确认安全框内的画面。", mode: "camera" },
{ id: "apply", title: "应用到镜头", detail: "确认场景、姿态、走位和 CAM 构图后,点顶栏「应用到镜头」生成静帧并回写画布。", mode: "camera" },
];
export type DirectorOnboardingProgress = {
version: number;
status: DirectorOnboardingStatus;
stepId: DirectorOnboardingStepId;
};
export const directorOnboardingInitial: DirectorOnboardingProgress = {
version: DIRECTOR_ONBOARDING_VERSION,
status: "active",
stepId: DIRECTOR_ONBOARDING_STEPS[0].id,
};
export type DirectorOnboardingAction = "next" | "back" | "dismiss" | "complete" | "reset";
/**
* 引导状态机。
*
* 关键不变量:
* - 只有 reset 能让已 dismissed/completed 的引导重新活过来。next/back/dismiss/complete
* 在非 active 状态下是恒等变换,否则「跳过引导」会被后续任何一次误触重新拉起来。
* - 在最后一步 next 等于完成:完成必须是终态,而不是停在最后一步继续可 next。
* - 首步 back 保持不动,不越界,也不隐式关闭引导。
* - 当前 stepId 不在步骤表里(旧数据、被外部改写)时回到初始进度,而不是把 -1 当下标继续算。
*/
export function reduceDirectorOnboarding(progress: DirectorOnboardingProgress, action: DirectorOnboardingAction): DirectorOnboardingProgress {
if (action === "reset") return directorOnboardingInitial;
if (progress.status !== "active") return progress;
if (action === "dismiss") return { ...progress, status: "dismissed" };
if (action === "complete") return { ...progress, status: "completed" };
const index = DIRECTOR_ONBOARDING_STEPS.findIndex((step) => step.id === progress.stepId);
if (index < 0) return directorOnboardingInitial;
if (action === "back") {
if (index === 0) return progress;
return { ...progress, stepId: DIRECTOR_ONBOARDING_STEPS[index - 1].id };
}
const next = DIRECTOR_ONBOARDING_STEPS[index + 1];
if (!next) return { ...progress, status: "completed" };
return { ...progress, stepId: next.id };
}
export type DirectorOnboardingView = {
step: DirectorOnboardingStep;
/** 1 起数,直接用于「第 N 步 / 共 M 步」。 */
position: number;
total: number;
isFirst: boolean;
isLast: boolean;
};
/**
* 展示态。返回 null 表示不该显示引导 —— 组件层只看这一个判据,
* 不自己再拼 status 与步骤下标,避免出现第二套可见性规则。
*/
export function resolveDirectorOnboardingView(progress: DirectorOnboardingProgress): DirectorOnboardingView | null {
if (progress.status !== "active") return null;
const index = DIRECTOR_ONBOARDING_STEPS.findIndex((step) => step.id === progress.stepId);
if (index < 0) return null;
return {
step: DIRECTOR_ONBOARDING_STEPS[index],
position: index + 1,
total: DIRECTOR_ONBOARDING_STEPS.length,
isFirst: index === 0,
isLast: index === DIRECTOR_ONBOARDING_STEPS.length - 1,
};
}
function isStepId(value: unknown): value is DirectorOnboardingStepId {
return typeof value === "string" && DIRECTOR_ONBOARDING_STEPS.some((step) => step.id === value);
}
function isStatus(value: unknown): value is DirectorOnboardingStatus {
return value === "active" || value === "dismissed" || value === "completed";
}
/**
* 解析持久进度。
*
* 引导是提示,不是内容:任何无法确信的持久值都当成「没有进度」,宁可再引导一次,
* 也不要把用户卡在一个无法解释的状态里。覆盖:非 JSON、非对象、数组、版本不符、
* status/stepId 不在枚举内。
*/
export function parseDirectorOnboardingProgress(raw: string | null | undefined): DirectorOnboardingProgress {
if (!raw) return directorOnboardingInitial;
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return directorOnboardingInitial;
}
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return directorOnboardingInitial;
const candidate = parsed as Partial<DirectorOnboardingProgress>;
if (candidate.version !== DIRECTOR_ONBOARDING_VERSION) return directorOnboardingInitial;
if (!isStatus(candidate.status) || !isStepId(candidate.stepId)) return directorOnboardingInitial;
return { version: DIRECTOR_ONBOARDING_VERSION, status: candidate.status, stepId: candidate.stepId };
}
/** 只要求读写能力:既是测试注入内存实现的接缝,也避免依赖 zustand StateStorage 的全量接口。 */
export type DirectorOnboardingStorage = {
getItem: (name: string) => string | null | Promise<string | null>;
setItem: (name: string, value: string) => void | Promise<void>;
};
/**
* scope 归一化 + 守卫。前后空白裁掉后再校验/使用,这样 " user-a " 与 "user-a"
* 落到同一把生产键上,不会分裂成两份互不可见的进度。
*
* 必须在每个导出的持久化函数入口无条件调用 —— 包括调用方已经注入自定义 storage 的分支。
* 之前的实现写成 `storage ?? localForageStorageForScope(requireScope(scope))`,
* `??` 短路导致「传了 storage」时 requireScope 根本不会执行,空 scope 就此绕过校验。
*/
function requireScope(scope: string) {
const normalized = scope.trim();
if (!normalized) throw new Error("缺少导演台引导的用户 scope");
return normalized;
}
/**
* 读取进度。
* 数据脏 -> 初始进度;存储层(IndexedDB)失败 -> 向上抛,由调用方决定是否隐藏引导,
* 不在这里 catch 成默认值假装读到了。
*/
export async function loadDirectorOnboardingProgress(scope: string, storage?: DirectorOnboardingStorage): Promise<DirectorOnboardingProgress> {
const normalizedScope = requireScope(scope);
const target = storage ?? localForageStorageForScope(normalizedScope);
return parseDirectorOnboardingProgress(await target.getItem(DIRECTOR_ONBOARDING_KEY));
}
export async function saveDirectorOnboardingProgress(scope: string, progress: DirectorOnboardingProgress, storage?: DirectorOnboardingStorage): Promise<void> {
const normalizedScope = requireScope(scope);
const target = storage ?? localForageStorageForScope(normalizedScope);
await target.setItem(DIRECTOR_ONBOARDING_KEY, JSON.stringify({ version: DIRECTOR_ONBOARDING_VERSION, status: progress.status, stepId: progress.stepId }));
}
/**
* 推进并持久化。返回新进度;写失败向上抛,调用方拿到的进度与已落盘的进度保持一致,
* 不存在「界面前进了但磁盘没动」这种静默分叉。
*
* scope 校验必须在「无变化动作提前返回」之前完成:否则对已 dismissed/completed 账号
* 调用 next 之类的恒等动作会在校验之前就 return progress,空 scope 也能悄悄跑过去。
* 无变化的动作仍然不写盘。
*/
export async function advanceDirectorOnboarding(scope: string, progress: DirectorOnboardingProgress, action: DirectorOnboardingAction, storage?: DirectorOnboardingStorage): Promise<DirectorOnboardingProgress> {
const normalizedScope = requireScope(scope);
const next = reduceDirectorOnboarding(progress, action);
if (next === progress) return progress;
await saveDirectorOnboardingProgress(normalizedScope, next, storage);
return next;
}
/**
* 独立的重启 API。不依赖调用方持有当前内存进度;设置页的「重新开始引导」
* 按钮可以直接落盘初始状态,对已 dismissed/completed 的账号同样生效。
*/
export async function resetDirectorOnboardingProgress(scope: string, storage?: DirectorOnboardingStorage): Promise<DirectorOnboardingProgress> {
const normalizedScope = requireScope(scope);
await saveDirectorOnboardingProgress(normalizedScope, directorOnboardingInitial, storage);
return directorOnboardingInitial;
}
export type DirectorOnboardingGate = {
/** 尝试进入互斥区;已有一次未完成的调用时返回 false,调用方必须放弃本次动作。 */
tryEnter: () => boolean;
/** 释放互斥区。scope/enabled 变化(换账号)时也要调用,否则旧账号的占用会永久卡死新账号。 */
release: () => void;
};
/**
* 创建一次性写锁:保证同一 tick 内的重复调用(双击、程序化连点)只有一个能真正发起写入。
*
* 用同步闭包变量而不是 React state 做门禁:state 更新要等到下一次渲染才对外可见,
* 两次点击完全可能发生在同一次渲染之间,仅靠 busy state 挡不住这种同步重入。
* release 是幂等的:未锁定时调用不抛错,方便在 effect 里无条件清理。
*/
export function createDirectorOnboardingGate(): DirectorOnboardingGate {
let locked = false;
return {
tryEnter: () => {
if (locked) return false;
locked = true;
return true;
},
release: () => {
locked = false;
},
};
}