feat: 模板适配层、易班能力与全局状态

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/api/client.ts

@@ -3,19 +3,10 @@
  * 可以根据项目需求使用 axios、fetch 或其他 HTTP 客户端
  */
 
+import type { ApiError, ApiResponse } from "./client.types";
+
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || "/api";
 
-export interface ApiResponse<T> {
-	data: T;
-	message?: string;
-	code?: number;
-}
-
-export interface ApiError {
-	message: string;
-	code?: number;
-}
-
 /**
  * 基础请求函数
  */

src/api/client.types.ts

@@ -0,0 +1,10 @@
+export interface ApiResponse<T> {
+	data: T;
+	message?: string;
+	code?: number;
+}
+
+export interface ApiError {
+	message: string;
+	code?: number;
+}

src/api/index.ts

@@ -1,9 +1,2 @@
-export {
-	type ApiError,
-	type ApiResponse,
-	del,
-	get,
-	post,
-	put,
-	request,
-} from "./client.ts";
+export { del, get, post, put, request } from "./client.ts";
+export type { ApiError, ApiResponse } from "./client.types";

src/components/common/Button/Button.module.css

@@ -1,36 +0,0 @@
-@reference "tailwindcss";
-
-.button {
-	@apply inline-flex items-center justify-center rounded-md font-medium transition-colors;
-	@apply focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2;
-	@apply disabled:pointer-events-none disabled:opacity-50;
-}
-
-.primary {
-	@apply bg-blue-600 text-white hover:bg-blue-700;
-}
-
-.secondary {
-	@apply bg-gray-200 text-gray-900 hover:bg-gray-300;
-}
-
-.outline {
-	@apply border border-gray-300 bg-transparent hover:bg-gray-100;
-}
-
-.ghost {
-	@apply bg-transparent hover:bg-gray-100;
-}
-
-.sm {
-	@apply h-8 px-3 text-sm;
-}
-
-.md {
-	@apply h-10 px-4 text-base;
-}
-
-.lg {
-	@apply h-12 px-6 text-lg;
-}
-

src/components/common/Button/Button.tsx

@@ -1,22 +0,0 @@
-import { type ButtonHTMLAttributes, forwardRef } from "react";
-import { cn } from "@/utils";
-import styles from "./Button.module.css";
-
-export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-	variant?: "primary" | "secondary" | "outline" | "ghost";
-	size?: "sm" | "md" | "lg";
-}
-
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
-	({ className, variant = "primary", size = "md", ...props }, ref) => {
-		return (
-			<button
-				ref={ref}
-				className={cn(styles.button, styles[variant], styles[size], className)}
-				{...props}
-			/>
-		);
-	},
-);
-
-Button.displayName = "Button";

src/components/common/Button/index.ts

@@ -1,2 +0,0 @@
-export type { ButtonProps } from "./Button.tsx";
-export { Button } from "./Button.tsx";

src/components/common/GuideDialog/GuideDialog.helpers.ts

@@ -0,0 +1,44 @@
+import { appConfig } from "@/app.config";
+import { useDialogStore } from "@/stores";
+import type {
+	GuideDialogStep,
+	StartDialogOptions,
+} from "@/stores/types/dialog.types";
+
+export interface DefineDialogOptions {
+	id: string;
+	steps: GuideDialogStep[];
+	showOnce?: boolean;
+	initialStep?: number;
+}
+
+export interface GuideDialogController {
+	id: string;
+	steps: GuideDialogStep[];
+	start: (options?: Pick<StartDialogOptions, "initialStep">) => void;
+	reset: () => void;
+}
+
+export function defineDialog({
+	id,
+	steps,
+	showOnce = true,
+	initialStep = 0,
+}: DefineDialogOptions): GuideDialogController {
+	return {
+		id,
+		steps,
+		start: (options) => {
+			useDialogStore.getState().startDialog({
+				courseId: appConfig.course.id,
+				dialogId: id,
+				showOnce,
+				steps,
+				initialStep: options?.initialStep ?? initialStep,
+			});
+		},
+		reset: () => {
+			useDialogStore.getState().resetDialog(appConfig.course.id, id);
+		},
+	};
+}

src/components/common/GuideDialog/GuideDialog.tsx

@@ -0,0 +1,62 @@
+import { useCallback } from "react";
+import {
+	type GuideDialogProps,
+	GuideDialog as RegistryGuideDialog,
+} from "@/components/course-interactions/guide-dialog";
+import { useCourseCanvas } from "@/course-runtime/canvas";
+import { useDialogStore } from "@/stores";
+import { getAppPortalRoot } from "../canvasPortal";
+
+export function GuideDialog({
+	children,
+	onFinish,
+	onSkip,
+	...props
+}: Omit<GuideDialogProps, "actions" | "state" | "viewport"> & {
+	onFinish?: () => void;
+	onSkip?: () => void;
+}) {
+	const {
+		open,
+		steps,
+		current,
+		nextStep,
+		prevStep,
+		selectOption,
+		finishDialog,
+		skipDialog,
+	} = useDialogStore();
+	const { viewport } = useCourseCanvas();
+
+	const finish = useCallback(() => {
+		finishDialog();
+		onFinish?.();
+	}, [finishDialog, onFinish]);
+
+	const skip = useCallback(() => {
+		skipDialog();
+		onSkip?.();
+	}, [onSkip, skipDialog]);
+
+	return (
+		<RegistryGuideDialog
+			state={{
+				open,
+				steps,
+				current,
+			}}
+			actions={{
+				next: nextStep,
+				prev: prevStep,
+				skip,
+				finish,
+				selectOption,
+			}}
+			container={getAppPortalRoot}
+			viewport={viewport}
+			{...props}
+		>
+			{children}
+		</RegistryGuideDialog>
+	);
+}

src/components/common/GuideDialog/GuideDialog.types.ts

@@ -0,0 +1,5 @@
+export type {
+	GuideDialogProps,
+	GuideDialogRenderState,
+	GuideDialogTheme,
+} from "@/components/course-interactions/guide-dialog";

src/components/common/GuideDialog/index.ts

@@ -0,0 +1,11 @@
+export { GuideDialog } from "./GuideDialog";
+export type {
+	DefineDialogOptions,
+	GuideDialogController,
+} from "./GuideDialog.helpers";
+export { defineDialog } from "./GuideDialog.helpers";
+export type {
+	GuideDialogProps,
+	GuideDialogRenderState,
+	GuideDialogTheme,
+} from "./GuideDialog.types";

src/components/common/GuideSpotlight/GuideSpotlight.helpers.ts

@@ -0,0 +1,57 @@
+import { appConfig } from "@/app.config";
+import { useSpotlightStore } from "@/stores";
+import type {
+	SpotlightStep,
+	StartSpotlightOptions,
+} from "@/stores/types/spotlight.types";
+
+type DefineSpotlightStep = Omit<SpotlightStep, "target"> & {
+	target?: SpotlightStep["target"];
+};
+
+export interface DefineSpotlightOptions {
+	id: string;
+	steps: DefineSpotlightStep[];
+	showOnce?: boolean;
+	initialStep?: number;
+}
+
+export interface SpotlightController {
+	id: string;
+	steps: SpotlightStep[];
+	start: (options?: Pick<StartSpotlightOptions, "initialStep">) => void;
+	reset: () => void;
+}
+
+function normalizeSteps(steps: DefineSpotlightStep[]): SpotlightStep[] {
+	return steps.map((step) => ({
+		...step,
+		target: step.target ?? { dataGuide: step.id },
+	}));
+}
+
+export function defineSpotlight({
+	id,
+	steps,
+	showOnce = true,
+	initialStep = 0,
+}: DefineSpotlightOptions): SpotlightController {
+	const normalizedSteps = normalizeSteps(steps);
+
+	return {
+		id,
+		steps: normalizedSteps,
+		start: (options) => {
+			useSpotlightStore.getState().startSpotlight({
+				courseId: appConfig.course.id,
+				spotlightId: id,
+				showOnce,
+				steps: normalizedSteps,
+				initialStep: options?.initialStep ?? initialStep,
+			});
+		},
+		reset: () => {
+			useSpotlightStore.getState().resetSpotlight(appConfig.course.id, id);
+		},
+	};
+}

src/components/common/GuideSpotlight/GuideSpotlight.tsx

@@ -0,0 +1,62 @@
+import { useCallback } from "react";
+import {
+	type GuideSpotlightProps,
+	GuideSpotlight as RegistryGuideSpotlight,
+} from "@/components/course-interactions/guide-spotlight";
+import { useCourseCanvas } from "@/course-runtime/canvas";
+import { useSpotlightStore } from "@/stores";
+import { getAppPortalRoot } from "../canvasPortal";
+
+export function GuideSpotlight({
+	children,
+	onFinish,
+	onSkip,
+	container = getAppPortalRoot,
+	viewport,
+	...props
+}: Omit<GuideSpotlightProps, "actions" | "state"> & {
+	onFinish?: () => void;
+	onSkip?: () => void;
+}) {
+	const {
+		open,
+		steps,
+		current,
+		nextStep,
+		prevStep,
+		finishSpotlight,
+		skipSpotlight,
+	} = useSpotlightStore();
+	const { viewport: canvasViewport } = useCourseCanvas();
+
+	const finish = useCallback(() => {
+		finishSpotlight();
+		onFinish?.();
+	}, [finishSpotlight, onFinish]);
+
+	const skip = useCallback(() => {
+		skipSpotlight();
+		onSkip?.();
+	}, [onSkip, skipSpotlight]);
+
+	return (
+		<RegistryGuideSpotlight
+			state={{
+				open,
+				steps,
+				current,
+			}}
+			actions={{
+				next: nextStep,
+				prev: prevStep,
+				skip,
+				finish,
+			}}
+			container={container}
+			viewport={viewport ?? canvasViewport}
+			{...props}
+		>
+			{children}
+		</RegistryGuideSpotlight>
+	);
+}

src/components/common/GuideSpotlight/GuideSpotlight.types.ts

@@ -0,0 +1,7 @@
+export type {
+	GuideSpotlightProps,
+	GuideSpotlightRenderState,
+	GuideSpotlightTheme,
+	Rect,
+	SpotlightLayout,
+} from "@/components/course-interactions/guide-spotlight";

src/components/common/GuideSpotlight/index.ts

@@ -0,0 +1,11 @@
+export { GuideSpotlight } from "./GuideSpotlight";
+export type {
+	DefineSpotlightOptions,
+	SpotlightController,
+} from "./GuideSpotlight.helpers";
+export { defineSpotlight } from "./GuideSpotlight.helpers";
+export type {
+	GuideSpotlightProps,
+	GuideSpotlightRenderState,
+	GuideSpotlightTheme,
+} from "./GuideSpotlight.types";

src/components/common/LandscapePrompt/LandscapePrompt.tsx

@@ -0,0 +1,25 @@
+export function LandscapePrompt() {
+	return (
+		<div className="fixed inset-0 z-2000 flex items-center justify-center bg-gray-950/80 px-8 text-white">
+			<div className="text-center">
+				<div className="mx-auto mb-2 flex h-16 w-16 items-center justify-center">
+					<svg
+						aria-hidden="true"
+						className="h-full w-full text-white"
+						fill="none"
+						viewBox="0 0 24 24"
+						stroke="currentColor"
+						strokeWidth={1.5}
+					>
+						<rect x="2" y="5" width="20" height="14" rx="2" />
+						<circle cx="12" cy="12" r="1" fill="currentColor" />
+					</svg>
+				</div>
+				<h1 className="text-2xl font-semibold">请旋转屏幕</h1>
+				<p className="mt-3 text-base text-gray-400">
+					为获得最佳体验,请横屏浏览
+				</p>
+			</div>
+		</div>
+	);
+}

src/components/common/LandscapePrompt/index.ts

@@ -0,0 +1 @@
+export { LandscapePrompt } from "./LandscapePrompt";

src/components/common/RouteFallback/RouteError.tsx

@@ -0,0 +1,39 @@
+import { isRouteErrorResponse, Link, useRouteError } from "react-router-dom";
+
+export function RouteError() {
+	const error = useRouteError();
+	const message = isRouteErrorResponse(error)
+		? `${error.status} ${error.statusText}`
+		: error instanceof Error
+			? error.message
+			: "页面加载失败";
+
+	return (
+		<div className="flex min-h-full items-center justify-center p-8">
+			<div className="w-full max-w-xl rounded-3xl border border-rose-200 bg-white p-8 text-center shadow-xl">
+				<p className="text-sm font-semibold text-rose-600">页面运行异常</p>
+				<h1 className="mt-3 text-2xl font-bold text-gray-950">
+					当前示例无法加载
+				</h1>
+				<p className="mt-3 break-words text-sm leading-6 text-gray-600">
+					{message}
+				</p>
+				<div className="mt-6 flex justify-center gap-3">
+					<Link
+						to="/"
+						className="rounded-lg bg-blue-600 px-4 py-2 text-sm font-medium text-white"
+					>
+						返回首页
+					</Link>
+					<button
+						type="button"
+						className="rounded-lg border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700"
+						onClick={() => window.location.reload()}
+					>
+						重新加载
+					</button>
+				</div>
+			</div>
+		</div>
+	);
+}

src/components/common/RouteFallback/RouteFallback.tsx

@@ -0,0 +1,7 @@
+export function RouteFallback() {
+	return (
+		<div className="flex min-h-[200px] items-center justify-center text-gray-500">
+			加载中...
+		</div>
+	);
+}

src/components/common/RouteFallback/index.ts

@@ -0,0 +1,2 @@
+export { RouteError } from "./RouteError";
+export { RouteFallback } from "./RouteFallback";

src/components/common/canvasPortal.ts

@@ -0,0 +1,16 @@
+import type { RefObject } from "react";
+
+let portalRoot: RefObject<HTMLDivElement | null> | null = null;
+
+export function registerAppPortalRoot(
+	container: RefObject<HTMLDivElement | null>,
+): () => void {
+	portalRoot = container;
+	return () => {
+		if (portalRoot === container) portalRoot = null;
+	};
+}
+
+export function getAppPortalRoot(): HTMLDivElement | null {
+	return portalRoot?.current ?? null;
+}

src/components/common/index.ts

@@ -1,2 +1,35 @@
-export type { ButtonProps } from "./Button";
-export { Button } from "./Button";
+export type { ButtonProps } from "@/components/ui/button";
+export { Button } from "@/components/ui/button";
+export type { OverlayProps } from "@/components/ui/overlay";
+export { Overlay } from "@/components/ui/overlay";
+export type { PortalContainer, PortalProps } from "@/components/ui/portal";
+export { Portal } from "@/components/ui/portal";
+export type {
+	ToastContextValue,
+	ToastItem as ToastItemData,
+	ToastOptions,
+	ToastProviderProps,
+	ToastRenderApi,
+	ToastType,
+	ToastViewportClassNames,
+	ToastViewportProps,
+} from "@/components/ui/toast";
+export { ToastProvider, ToastViewport, useToast } from "@/components/ui/toast";
+export type {
+	DefineDialogOptions,
+	GuideDialogController,
+	GuideDialogProps,
+	GuideDialogRenderState,
+	GuideDialogTheme,
+} from "./GuideDialog";
+export { defineDialog, GuideDialog } from "./GuideDialog";
+export type {
+	DefineSpotlightOptions,
+	GuideSpotlightProps,
+	GuideSpotlightRenderState,
+	GuideSpotlightTheme,
+	SpotlightController,
+} from "./GuideSpotlight";
+export { defineSpotlight, GuideSpotlight } from "./GuideSpotlight";
+export { LandscapePrompt } from "./LandscapePrompt";
+export { RouteError, RouteFallback } from "./RouteFallback";

src/hooks/index.ts

@@ -1 +0,0 @@
-export { useLocalStorage } from "./useLocalStorage.ts";

src/hooks/useLocalStorage.ts

@@ -1,52 +0,0 @@
-import { useEffect, useState } from "react";
-
-/**
- * 自定义 Hook：使用 localStorage 存储状态
- * @param key - localStorage 的 key
- * @param initialValue - 初始值
- * @returns [storedValue, setValue] - 存储的值和更新函数
- */
-export function useLocalStorage<T>(
-	key: string,
-	initialValue: T,
-): [T, (value: T | ((val: T) => T)) => void] {
-	const [storedValue, setStoredValue] = useState<T>(() => {
-		try {
-			const item = window.localStorage.getItem(key);
-			return item ? (JSON.parse(item) as T) : initialValue;
-		} catch (error) {
-			console.error(`Error reading localStorage key "${key}":`, error);
-			return initialValue;
-		}
-	});
-
-	const setValue = (value: T | ((val: T) => T)) => {
-		try {
-			const valueToStore =
-				value instanceof Function ? value(storedValue) : value;
-			setStoredValue(valueToStore);
-			window.localStorage.setItem(key, JSON.stringify(valueToStore));
-		} catch (error) {
-			console.error(`Error setting localStorage key "${key}":`, error);
-		}
-	};
-
-	useEffect(() => {
-		const handleStorageChange = (e: StorageEvent) => {
-			if (e.key === key && e.newValue) {
-				try {
-					setStoredValue(JSON.parse(e.newValue) as T);
-				} catch (error) {
-					console.error(`Error parsing storage event for key "${key}":`, error);
-				}
-			}
-		};
-
-		window.addEventListener("storage", handleStorageChange);
-		return () => {
-			window.removeEventListener("storage", handleStorageChange);
-		};
-	}, [key]);
-
-	return [storedValue, setValue];
-}

src/stores/index.ts

@@ -0,0 +1,17 @@
+export * from "./modules";
+export type {
+	AppState,
+	GuideDialogCharacter,
+	GuideDialogOption,
+	GuideDialogPlacement,
+	GuideDialogState,
+	GuideDialogStep,
+	SpotlightPlacement,
+	SpotlightState,
+	SpotlightStep,
+	SpotlightTarget,
+	StartDialogOptions,
+	StartSpotlightOptions,
+	UserState,
+	YibanConnectionStatus,
+} from "./types";

src/stores/modules/app.ts

@@ -0,0 +1,8 @@
+import { create } from "zustand";
+import type { AppState } from "../types/app.types";
+
+export const useAppStore = create<AppState>((set) => ({
+	count: 0,
+	increment: () => set((state) => ({ count: state.count + 1 })),
+	reset: () => set({ count: 0 }),
+}));

src/stores/modules/dialog.ts

@@ -0,0 +1,136 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { appConfig } from "@/app.config";
+import type { GuideDialogState } from "../types/dialog.types";
+
+const getDialogKey = (courseId: string, dialogId: string) =>
+	`${courseId}:${dialogId}`;
+
+const getInitialState = () => ({
+	open: false,
+	courseId: null,
+	dialogId: null,
+	steps: [],
+	current: 0,
+	showOnce: true,
+});
+
+export const useDialogStore = create<GuideDialogState>()(
+	persist(
+		(set, get) => ({
+			...getInitialState(),
+			completedDialogMap: {},
+
+			startDialog: ({
+				courseId,
+				dialogId,
+				steps,
+				showOnce = true,
+				initialStep = 0,
+			}) => {
+				if (steps.length === 0) return;
+
+				const key = getDialogKey(courseId, dialogId);
+				if (showOnce && get().completedDialogMap[key]) {
+					return;
+				}
+
+				set({
+					open: true,
+					courseId,
+					dialogId,
+					steps,
+					current: Math.min(Math.max(initialStep, 0), steps.length - 1),
+					showOnce,
+				});
+			},
+
+			closeDialog: () => {
+				set(getInitialState());
+			},
+
+			nextStep: () => {
+				const { current, steps, finishDialog } = get();
+				if (current >= steps.length - 1) {
+					finishDialog();
+					return;
+				}
+				set({ current: current + 1 });
+			},
+
+			prevStep: () => {
+				const { current } = get();
+				set({ current: Math.max(current - 1, 0) });
+			},
+
+			setStep: (index) => {
+				const { steps } = get();
+				if (steps.length === 0) return;
+				set({ current: Math.min(Math.max(index, 0), steps.length - 1) });
+			},
+
+			selectOption: (optionId) => {
+				const { current, steps, setStep, finishDialog, nextStep } = get();
+				const step = steps[current];
+				const option = step?.options?.find((item) => item.id === optionId);
+				if (!option) return;
+
+				if (option.finish) {
+					finishDialog();
+					return;
+				}
+
+				if (option.nextId) {
+					const nextIndex = steps.findIndex(
+						(item) => item.id === option.nextId,
+					);
+					if (nextIndex >= 0) {
+						setStep(nextIndex);
+						return;
+					}
+				}
+
+				nextStep();
+			},
+
+			finishDialog: () => {
+				const { courseId, dialogId, completedDialogMap } = get();
+				if (!courseId || !dialogId) {
+					set(getInitialState());
+					return;
+				}
+
+				const key = getDialogKey(courseId, dialogId);
+				set({
+					...getInitialState(),
+					completedDialogMap: {
+						...completedDialogMap,
+						[key]: true,
+					},
+				});
+			},
+
+			skipDialog: () => {
+				get().finishDialog();
+			},
+
+			resetDialog: (courseId, dialogId) => {
+				const key = getDialogKey(courseId, dialogId);
+				const { [key]: _removed, ...rest } = get().completedDialogMap;
+				const isCurrentDialog =
+					get().courseId === courseId && get().dialogId === dialogId;
+
+				set({
+					...(isCurrentDialog ? getInitialState() : {}),
+					completedDialogMap: rest,
+				});
+			},
+		}),
+		{
+			name: `${appConfig.storage.prefix}-dialog-storage`,
+			partialize: (state) => ({
+				completedDialogMap: state.completedDialogMap,
+			}),
+		},
+	),
+);

src/stores/modules/index.ts

@@ -0,0 +1,4 @@
+export * from "./app";
+export * from "./dialog";
+export * from "./spotlight";
+export * from "./user";

src/stores/modules/spotlight.ts

@@ -0,0 +1,112 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { appConfig } from "@/app.config";
+import type { SpotlightState } from "../types/spotlight.types";
+
+const getSpotlightKey = (courseId: string, spotlightId: string) =>
+	`${courseId}:${spotlightId}`;
+
+const getInitialState = () => ({
+	open: false,
+	courseId: null,
+	spotlightId: null,
+	steps: [],
+	current: 0,
+	showOnce: true,
+});
+
+export const useSpotlightStore = create<SpotlightState>()(
+	persist(
+		(set, get) => ({
+			...getInitialState(),
+			completedSpotlightMap: {},
+
+			startSpotlight: ({
+				courseId,
+				spotlightId,
+				steps,
+				showOnce = true,
+				initialStep = 0,
+			}) => {
+				if (steps.length === 0) return;
+
+				const key = getSpotlightKey(courseId, spotlightId);
+				if (showOnce && get().completedSpotlightMap[key]) {
+					return;
+				}
+
+				set({
+					open: true,
+					courseId,
+					spotlightId,
+					steps,
+					current: Math.min(Math.max(initialStep, 0), steps.length - 1),
+					showOnce,
+				});
+			},
+
+			closeSpotlight: () => {
+				set(getInitialState());
+			},
+
+			nextStep: () => {
+				const { current, steps, finishSpotlight } = get();
+				if (current >= steps.length - 1) {
+					finishSpotlight();
+					return;
+				}
+				set({ current: current + 1 });
+			},
+
+			prevStep: () => {
+				const { current } = get();
+				set({ current: Math.max(current - 1, 0) });
+			},
+
+			setStep: (index) => {
+				const { steps } = get();
+				if (steps.length === 0) return;
+				set({ current: Math.min(Math.max(index, 0), steps.length - 1) });
+			},
+
+			finishSpotlight: () => {
+				const { courseId, spotlightId, completedSpotlightMap } = get();
+				if (!courseId || !spotlightId) {
+					set(getInitialState());
+					return;
+				}
+
+				const key = getSpotlightKey(courseId, spotlightId);
+				set({
+					...getInitialState(),
+					completedSpotlightMap: {
+						...completedSpotlightMap,
+						[key]: true,
+					},
+				});
+			},
+
+			skipSpotlight: () => {
+				get().finishSpotlight();
+			},
+
+			resetSpotlight: (courseId, spotlightId) => {
+				const key = getSpotlightKey(courseId, spotlightId);
+				const { [key]: _removed, ...rest } = get().completedSpotlightMap;
+				const isCurrentSpotlight =
+					get().courseId === courseId && get().spotlightId === spotlightId;
+
+				set({
+					...(isCurrentSpotlight ? getInitialState() : {}),
+					completedSpotlightMap: rest,
+				});
+			},
+		}),
+		{
+			name: `${appConfig.storage.prefix}-spotlight-storage`,
+			partialize: (state) => ({
+				completedSpotlightMap: state.completedSpotlightMap,
+			}),
+		},
+	),
+);

src/stores/modules/user.ts

@@ -0,0 +1,29 @@
+import { create } from "zustand";
+import type { UserState } from "../types/user.types";
+
+export const useUserStore = create<UserState>((set) => ({
+	yibanConnectionStatus: "unknown",
+	setYibanConnectionStatus: (status) => set({ yibanConnectionStatus: status }),
+
+	courseId: null,
+	setCourseId: (courseId) => set({ courseId }),
+
+	userId: null,
+	userName: null,
+	userAvatar: null,
+	setUserInfo: (info) =>
+		set({
+			userId: info.userId,
+			userName: info.userName ?? null,
+			userAvatar: info.userAvatar ?? null,
+		}),
+
+	clearUser: () =>
+		set({
+			userId: null,
+			userName: null,
+			userAvatar: null,
+			yibanConnectionStatus: "unknown",
+			courseId: null,
+		}),
+}));

src/stores/types/app.types.ts

@@ -0,0 +1,5 @@
+export interface AppState {
+	count: number;
+	increment: () => void;
+	reset: () => void;
+}

src/stores/types/dialog.types.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+
+export type GuideDialogPlacement = "top" | "center" | "bottom";
+
+export interface GuideDialogCharacter {
+	name?: ReactNode;
+	avatar?: ReactNode;
+	mood?: string;
+}
+
+export interface GuideDialogOption {
+	id: string;
+	label: ReactNode;
+	nextId?: string;
+	finish?: boolean;
+	data?: unknown;
+}
+
+export interface GuideDialogStep {
+	id: string;
+	character?: GuideDialogCharacter;
+	title?: ReactNode;
+	description?: ReactNode;
+	placement?: GuideDialogPlacement;
+	nextLabel?: string;
+	prevLabel?: string;
+	skipLabel?: string;
+	doneLabel?: string;
+	options?: GuideDialogOption[];
+	data?: unknown;
+}
+
+export interface StartDialogOptions {
+	courseId: string;
+	dialogId: string;
+	steps: GuideDialogStep[];
+	showOnce?: boolean;
+	initialStep?: number;
+}
+
+export interface GuideDialogState {
+	open: boolean;
+	courseId: string | null;
+	dialogId: string | null;
+	steps: GuideDialogStep[];
+	current: number;
+	showOnce: boolean;
+	completedDialogMap: Record<string, boolean>;
+	startDialog: (options: StartDialogOptions) => void;
+	closeDialog: () => void;
+	nextStep: () => void;
+	prevStep: () => void;
+	setStep: (index: number) => void;
+	selectOption: (optionId: string) => void;
+	finishDialog: () => void;
+	skipDialog: () => void;
+	resetDialog: (courseId: string, dialogId: string) => void;
+}

src/stores/types/index.ts

@@ -0,0 +1,17 @@
+export type { AppState } from "./app.types";
+export type {
+	GuideDialogCharacter,
+	GuideDialogOption,
+	GuideDialogPlacement,
+	GuideDialogState,
+	GuideDialogStep,
+	StartDialogOptions,
+} from "./dialog.types";
+export type {
+	SpotlightPlacement,
+	SpotlightState,
+	SpotlightStep,
+	SpotlightTarget,
+	StartSpotlightOptions,
+} from "./spotlight.types";
+export type { UserState, YibanConnectionStatus } from "./user.types";

src/stores/types/spotlight.types.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from "react";
+
+export type SpotlightPlacement = "top" | "bottom" | "left" | "right" | "auto";
+
+export interface SpotlightTarget {
+	selector?: string;
+	dataGuide?: string;
+}
+
+export interface SpotlightStep {
+	id: string;
+	target: string | SpotlightTarget;
+	title?: ReactNode;
+	description?: ReactNode;
+	placement?: SpotlightPlacement;
+	allowTargetClick?: boolean;
+	padding?: number;
+	radius?: number;
+	panelClassName?: string;
+	nextLabel?: string;
+	prevLabel?: string;
+	doneLabel?: string;
+	skipLabel?: string;
+	data?: unknown;
+}
+
+export interface StartSpotlightOptions {
+	courseId: string;
+	spotlightId: string;
+	steps: SpotlightStep[];
+	showOnce?: boolean;
+	initialStep?: number;
+}
+
+export interface SpotlightState {
+	open: boolean;
+	courseId: string | null;
+	spotlightId: string | null;
+	steps: SpotlightStep[];
+	current: number;
+	showOnce: boolean;
+	completedSpotlightMap: Record<string, boolean>;
+	startSpotlight: (options: StartSpotlightOptions) => void;
+	closeSpotlight: () => void;
+	nextStep: () => void;
+	prevStep: () => void;
+	setStep: (index: number) => void;
+	finishSpotlight: () => void;
+	skipSpotlight: () => void;
+	resetSpotlight: (courseId: string, spotlightId: string) => void;
+}

src/stores/types/user.types.ts

@@ -0,0 +1,24 @@
+export type YibanConnectionStatus = "connected" | "disconnected" | "unknown";
+
+export interface UserState {
+	// 易班连接状态
+	yibanConnectionStatus: YibanConnectionStatus;
+	setYibanConnectionStatus: (status: YibanConnectionStatus) => void;
+
+	// 课程ID（用于上报进度）
+	courseId: string | null;
+	setCourseId: (courseId: string) => void;
+
+	// 易班用户信息
+	userId: string | null;
+	userName: string | null;
+	userAvatar: string | null;
+	setUserInfo: (info: {
+		userId: string;
+		userName?: string;
+		userAvatar?: string;
+	}) => void;
+
+	// 清空用户信息
+	clearUser: () => void;
+}

src/types/index.ts

@@ -1,34 +0,0 @@
-/**
- * 全局类型定义
- */
-
-// 用户相关类型
-export interface User {
-	id: string;
-	name: string;
-	email: string;
-	avatar?: string;
-}
-
-// API 响应类型
-export interface PaginationParams {
-	page: number;
-	pageSize: number;
-}
-
-export interface PaginationResponse<T> {
-	list: T[];
-	total: number;
-	page: number;
-	pageSize: number;
-}
-
-// 通用类型
-export type Nullable<T> = T | null;
-export type Optional<T> = T | undefined;
-
-// 组件 Props 基础类型
-export interface BaseComponentProps {
-	className?: string;
-	children?: React.ReactNode;
-}

src/types/yiban.ts

@@ -0,0 +1,137 @@
+/**
+ * 易班 videoajax.js 相关类型定义
+ */
+
+// 声明外部依赖（由 vite.config.ts 注入的 videoajax.js 提供，运行时可能加载失败）
+declare global {
+	var videoAjax: (() => VideoAjax) | undefined;
+}
+
+/**
+ * VideoAjax 实例接口
+ */
+export interface VideoAjax {
+	setHost(host: string): void;
+	addUserDefine(
+		param: UserDefineParam,
+		callback?: (data: unknown) => void,
+	): void;
+	getUserDefineInfoByUser(
+		param: UserDefineParam,
+		callback: (data: VideoAjaxResponse | undefined) => void,
+	): void;
+	getUserDefineInfo(
+		param: UserDefineParam,
+		callback: (data: VideoAjaxResponse | undefined) => void,
+	): void;
+	finishCourse(
+		param: { order: number; co: string; process: number },
+		callback?: (status: boolean, data: unknown) => void,
+	): void;
+	getfinishCourse(
+		param: { order: number; co: string },
+		callback: (data: unknown) => void,
+	): void;
+	quitBreakPoint(
+		param: {
+			user_id: string;
+			course_id: string;
+			lesson_id: string;
+			break_point: number;
+		},
+		callback?: (status: boolean, data: unknown) => void,
+	): void;
+	getBreakPoint(
+		param: { user_id: string; course_id: string; lesson_id: string },
+		callback: (status: boolean, data: unknown) => void,
+	): void;
+	getUserAnswer(
+		param: {
+			user_id: string;
+			lesson_id: string;
+			course_id: string;
+			question_order: number;
+			answer: string;
+		},
+		callback?: (status: boolean, data: unknown) => void,
+	): void;
+}
+
+/**
+ * UserDefine 接口参数
+ */
+export interface UserDefineParam {
+	lessonId: string;
+	key?: string | number;
+	order?: string | number;
+	content?: string;
+}
+
+/**
+ * VideoAjax 响应项
+ */
+export interface VideoAjaxResponseItem {
+	content?: string;
+}
+
+/**
+ * VideoAjax 响应
+ */
+export interface VideoAjaxResponse {
+	code: number;
+	msg?: string;
+	data: {
+		value?: VideoAjaxResponseItem[] | string;
+		process?: string;
+	};
+}
+
+/**
+ * 用户存储获取状态
+ */
+export type UserStorageFetchStatus =
+	| "success"
+	| "empty"
+	| "unauthenticated"
+	| "error";
+
+/**
+ * 用户存储获取结果
+ */
+export interface UserStorageFetchResult {
+	status: UserStorageFetchStatus;
+	content: string;
+	code?: number;
+	message?: string;
+}
+
+/**
+ * 存储后端类型
+ */
+export type StorageBackend = "auto" | "yiban" | "session";
+
+/**
+ * 存储选项
+ */
+export interface StorageOptions {
+	backend?: StorageBackend;
+}
+
+/**
+ * 易班请求结果
+ */
+export interface YibanRequestResult<T = unknown> {
+	success: boolean;
+	data?: T;
+	error?: string;
+}
+
+/**
+ * 播放断点参数
+ */
+export interface BreakPointParams {
+	userId: string;
+	courseId: string;
+	lessonId: string;
+	breakPoint?: number;
+}

src/utils/index.ts

@@ -1,3 +1,6 @@
 export * from "./assets";
 export * from "./lazyRoute";
 export * from "./tailwind";
+export * from "./useOrientation";
+export * from "./useScale";
+export * from "./yiban";

src/utils/tailwind.ts

@@ -1,10 +1 @@
-import { twMerge } from "tailwind-merge";
-
-/**
- * 合并 Tailwind CSS 类名，自动处理冲突
- * @param classes - 要合并的类名
- * @returns 合并后的类名字符串
- */
-export function cn(...classes: (string | undefined | null | false)[]): string {
-	return twMerge(classes.filter(Boolean).join(" "));
-}
+export { cn } from "@/lib/cn";

src/utils/useOrientation.ts

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+
+function getIsPortrait() {
+	if (typeof window === "undefined") return false;
+	return window.innerHeight > window.innerWidth;
+}
+
+export function useOrientation() {
+	const [isPortrait, setIsPortrait] = useState(getIsPortrait);
+
+	useEffect(() => {
+		const updateOrientation = () => setIsPortrait(getIsPortrait());
+		window.addEventListener("resize", updateOrientation);
+		window.addEventListener("orientationchange", updateOrientation);
+		return () => {
+			window.removeEventListener("resize", updateOrientation);
+			window.removeEventListener("orientationchange", updateOrientation);
+		};
+	}, []);
+
+	return isPortrait;
+}

src/utils/useScale.ts

@@ -0,0 +1,43 @@
+import { useCallback, useEffect, useState } from "react";
+import { appConfig } from "@/app.config";
+
+export const DESIGN_WIDTH = appConfig.design.width;
+export const DESIGN_HEIGHT = appConfig.design.height;
+
+function getViewportSize() {
+	if (typeof window === "undefined") {
+		return { width: DESIGN_WIDTH, height: DESIGN_HEIGHT };
+	}
+	return {
+		width: window.visualViewport?.width ?? window.innerWidth,
+		height: window.visualViewport?.height ?? window.innerHeight,
+	};
+}
+
+export function useScale() {
+	const calculateScale = useCallback(() => {
+		const viewport = getViewportSize();
+		return Math.min(
+			viewport.width / DESIGN_WIDTH,
+			viewport.height / DESIGN_HEIGHT,
+			appConfig.scale.max,
+		);
+	}, []);
+	const [scale, setScale] = useState(calculateScale);
+
+	useEffect(() => {
+		const updateScale = () => setScale(calculateScale());
+		window.addEventListener("resize", updateScale);
+		window.addEventListener("orientationchange", updateScale);
+		window.visualViewport?.addEventListener("resize", updateScale);
+		window.visualViewport?.addEventListener("scroll", updateScale);
+		return () => {
+			window.removeEventListener("resize", updateScale);
+			window.removeEventListener("orientationchange", updateScale);
+			window.visualViewport?.removeEventListener("resize", updateScale);
+			window.visualViewport?.removeEventListener("scroll", updateScale);
+		};
+	}, [calculateScale]);
+
+	return scale;
+}

src/utils/vconsole.ts

@@ -0,0 +1,21 @@
+/**
+ * vconsole 移动端调试工具
+ * 仅在开发环境的移动端启用
+ */
+function isMobileDevice() {
+	const userAgent = navigator.userAgent.toLowerCase();
+	const isMobileUA = /android|iphone|ipad|ipod|mobile/.test(userAgent);
+	const hasTouch = "ontouchstart" in window || navigator.maxTouchPoints > 0;
+
+	return isMobileUA || hasTouch;
+}
+
+if (import.meta.env.DEV && isMobileDevice()) {
+	void import("vconsole")
+		.then(({ default: VConsole }) => {
+			new VConsole();
+		})
+		.catch((error) => {
+			console.warn("[vconsole] failed to load", error);
+		});
+}

src/utils/yiban.ts

@@ -0,0 +1,485 @@
+/**
+ * 易班 videoajax.js 封装
+ * 用于与易班平台交互：用户数据存取、课程进度上报等
+ */
+
+import { useUserStore } from "@/stores";
+import type {
+	BreakPointParams,
+	StorageBackend,
+	StorageOptions,
+	UserDefineParam,
+	UserStorageFetchResult,
+	VideoAjax,
+	VideoAjaxResponse,
+	YibanRequestResult,
+} from "@/types/yiban";
+
+// 超时时间
+const TIMEOUT_MS = 1000 * 6;
+
+// 课时前缀
+const LESSON_PREFIX = "hsgrl";
+
+// 初始化 videoajax 实例
+let videoajaxInstance: VideoAjax | null = null;
+
+/**
+ * 检测 videoajax.js 是否已加载
+ */
+export function isVideoAjaxAvailable() {
+	return typeof globalThis.videoAjax === "function";
+}
+
+/**
+ * 记录 videoajax 不可用的诊断信息
+ */
+function warnVideoAjaxUnavailable(description: string) {
+	console.warn(`[yiban] videoajax unavailable: ${description}`, {
+		hasVideoAjax: isVideoAjaxAvailable(),
+	});
+}
+
+/**
+ * 获取 VideoAjax 实例
+ */
+function getVideoAjax(): VideoAjax {
+	if (!videoajaxInstance) {
+		const createVideoAjax = globalThis.videoAjax;
+		if (typeof createVideoAjax !== "function") {
+			throw new Error(
+				"videoAjax is not available. Please ensure public/videoajax/videoajax.js is loaded.",
+			);
+		}
+		videoajaxInstance = createVideoAjax();
+		videoajaxInstance.setHost("/");
+	}
+	return videoajaxInstance;
+}
+
+/**
+ * 生成存储键
+ */
+const getStorageKey = (lessonId: string | number, key: string | number) => {
+	const { courseId, userId } = useUserStore.getState();
+	const courseScope = courseId || "dev-course";
+	const userScope = userId || "guest";
+
+	return `${LESSON_PREFIX}_${courseScope}_${userScope}_${lessonId}_${key}`;
+};
+
+/**
+ * 解析存储后端
+ */
+const resolveStorageBackend = (
+	backend: StorageBackend = "auto",
+): "yiban" | "session" => {
+	if (backend === "session") return backend;
+
+	if (backend === "yiban") {
+		if (!isVideoAjaxAvailable()) {
+			warnVideoAjaxUnavailable("force yiban storage fallback to session");
+			return "session";
+		}
+		return backend;
+	}
+
+	const { yibanConnectionStatus } = useUserStore.getState();
+	if (yibanConnectionStatus === "connected" && isVideoAjaxAvailable()) {
+		return "yiban";
+	}
+
+	if (yibanConnectionStatus === "connected") {
+		warnVideoAjaxUnavailable("auto storage fallback to session");
+	}
+
+	return "session";
+};
+
+/**
+ * 统一的易班请求封装
+ * 处理超时、错误、日志
+ */
+async function yibanRequest<T>(options: {
+	method: (callback: (res: T) => void) => void;
+	timeout?: number;
+	description?: string;
+}): Promise<YibanRequestResult<T>> {
+	const { method, timeout = TIMEOUT_MS, description = "request" } = options;
+
+	return new Promise((resolve) => {
+		let settled = false;
+
+		const timeoutId = setTimeout(() => {
+			if (!settled) {
+				settled = true;
+				console.warn(`[yiban] ${description} timeout`);
+				resolve({ success: false, error: "timeout" });
+			}
+		}, timeout);
+
+		try {
+			method((res) => {
+				if (!settled) {
+					settled = true;
+					clearTimeout(timeoutId);
+					resolve({ success: true, data: res });
+				}
+			});
+		} catch (error) {
+			if (!settled) {
+				settled = true;
+				clearTimeout(timeoutId);
+				console.error(`[yiban] ${description} failed`, error);
+				resolve({ success: false, error: String(error) });
+			}
+		}
+	});
+}
+
+async function yibanStatusRequest<T>(options: {
+	method: (callback: (status: boolean, data: T) => void) => void;
+	timeout?: number;
+	description?: string;
+}): Promise<YibanRequestResult<T>> {
+	const { method, timeout = TIMEOUT_MS, description = "request" } = options;
+
+	return new Promise((resolve) => {
+		let settled = false;
+
+		const timeoutId = setTimeout(() => {
+			if (!settled) {
+				settled = true;
+				console.warn(`[yiban] ${description} timeout`);
+				resolve({ success: false, error: "timeout" });
+			}
+		}, timeout);
+
+		try {
+			method((status, data) => {
+				if (!settled) {
+					settled = true;
+					clearTimeout(timeoutId);
+					resolve(
+						status
+							? { success: true, data }
+							: { success: false, error: `${description} returned false` },
+					);
+				}
+			});
+		} catch (error) {
+			if (!settled) {
+				settled = true;
+				clearTimeout(timeoutId);
+				console.error(`[yiban] ${description} failed`, error);
+				resolve({ success: false, error: String(error) });
+			}
+		}
+	});
+}
+
+/**
+ * 设置用户存储数据
+ * @param lessonId 课时唯一ID
+ * @param key 数据键
+ * @param value 数据值
+ * @param options 存储选项
+ */
+export async function setUserStorage(
+	lessonId: string | number,
+	key: string | number,
+	value: string,
+	options: StorageOptions = {},
+): Promise<YibanRequestResult> {
+	const backend = resolveStorageBackend(options.backend);
+
+	if (backend === "session") {
+		sessionStorage.setItem(getStorageKey(lessonId, key), value);
+		return { success: true };
+	}
+
+	const param: UserDefineParam = {
+		lessonId: `${LESSON_PREFIX}_${lessonId}`,
+		key,
+		content: value,
+	};
+
+	const result = await yibanRequest({
+		method: (callback) => getVideoAjax().addUserDefine(param, callback),
+		description: `setUserStorage(${lessonId}, ${key})`,
+	});
+
+	return result;
+}
+
+/**
+ * 获取用户存储数据
+ * @param lessonId 课时唯一ID
+ * @param key 数据键
+ * @param options 存储选项
+ * @returns Promise<UserStorageFetchResult>
+ */
+export async function getUserStorage(
+	lessonId: string | number,
+	key: string | number,
+	options: StorageOptions = {},
+): Promise<UserStorageFetchResult> {
+	const backend = resolveStorageBackend(options.backend);
+
+	if (backend === "session") {
+		const itemValue = sessionStorage.getItem(getStorageKey(lessonId, key));
+		return itemValue === undefined ||
+			itemValue === null ||
+			itemValue === "null" ||
+			itemValue === ""
+			? { status: "empty", content: "" }
+			: { status: "success", content: itemValue };
+	}
+
+	const param: UserDefineParam = {
+		lessonId: `${LESSON_PREFIX}_${lessonId}`,
+		order: key,
+	};
+
+	const result = await yibanRequest<VideoAjaxResponse | undefined>({
+		method: (callback) =>
+			getVideoAjax().getUserDefineInfoByUser(param, callback),
+		description: `getUserStorage(${lessonId}, ${key})`,
+	});
+
+	if (!result.success) {
+		return {
+			status: "error",
+			content: "",
+			message: result.error || "请求失败",
+		};
+	}
+
+	const res = result.data;
+	if (!res || res === null || res === ("null" as unknown)) {
+		return { status: "empty", content: "" };
+	}
+
+	if (res.code === 202) {
+		return {
+			status: "unauthenticated",
+			content: "",
+			code: res.code,
+			message: res.msg,
+		};
+	}
+
+	if (res.code !== 200) {
+		return {
+			status: "error",
+			content: "",
+			code: res.code,
+			message: res.msg || "学习进度获取失败",
+		};
+	}
+
+	const value = res.data?.value;
+	if (
+		value === undefined ||
+		value === null ||
+		value === "null" ||
+		value === ""
+	) {
+		return { status: "empty", content: "" };
+	}
+
+	const json = Array.isArray(value) ? value : [];
+	const content = json[0]?.content || "";
+
+	return content === "" || content === "null"
+		? { status: "empty", content: "" }
+		: { status: "success", content };
+}
+
+/**
+ * 上报课程进度到易班平台
+ * @param order 课时顺序号
+ * @returns Promise<boolean> 是否成功上报
+ */
+export async function reportCourseProgress(order: number): Promise<boolean> {
+	const { yibanConnectionStatus, courseId } = useUserStore.getState();
+
+	if (yibanConnectionStatus !== "connected") {
+		console.info(`[yiban] skip finishCourse: disconnected, order=${order}`);
+		return false;
+	}
+
+	if (courseId === undefined || courseId === null || courseId === "") {
+		console.info(`[yiban] skip finishCourse: missing courseId, order=${order}`);
+		return false;
+	}
+
+	if (!isVideoAjaxAvailable()) {
+		warnVideoAjaxUnavailable(`skip finishCourse, order=${order}`);
+		return false;
+	}
+
+	if (order <= 0) {
+		console.info(`[yiban] skip finishCourse: invalid order=${order}`);
+		return false;
+	}
+
+	const result = await yibanStatusRequest<unknown>({
+		method: (callback) =>
+			getVideoAjax().finishCourse(
+				{ order, co: courseId, process: 100 },
+				callback,
+			),
+		description: `reportCourseProgress(${order})`,
+	});
+
+	if (result.success) {
+		console.info(`[yiban] finishCourse success, order=${order}`);
+	}
+
+	return result.success;
+}
+
+/**
+ * 获取课程进度
+ * @param order 课时顺序号
+ * @returns Promise<课程进度数据 | null>
+ */
+export async function getCourseProgress(
+	order: number,
+): Promise<unknown | null> {
+	const { yibanConnectionStatus, courseId } = useUserStore.getState();
+
+	if (yibanConnectionStatus !== "connected" || !courseId) {
+		return null;
+	}
+
+	if (!isVideoAjaxAvailable()) {
+		warnVideoAjaxUnavailable(`skip getfinishCourse, order=${order}`);
+		return null;
+	}
+
+	const result = await yibanRequest<unknown>({
+		method: (callback) =>
+			getVideoAjax().getfinishCourse({ order, co: courseId }, callback),
+		description: `getCourseProgress(${order})`,
+	});
+
+	return result.success && result.data ? result.data : null;
+}
+
+/**
+ * 保存播放断点
+ * @param params 断点参数
+ * @returns Promise<boolean> 是否成功保存
+ */
+export async function saveBreakPoint(
+	params: BreakPointParams & { breakPoint: number },
+): Promise<boolean> {
+	const { yibanConnectionStatus } = useUserStore.getState();
+
+	if (yibanConnectionStatus !== "connected") {
+		return false;
+	}
+
+	if (!isVideoAjaxAvailable()) {
+		warnVideoAjaxUnavailable(
+			`skip quitBreakPoint, lessonId=${params.lessonId}`,
+		);
+		return false;
+	}
+
+	const result = await yibanStatusRequest<unknown>({
+		method: (callback) =>
+			getVideoAjax().quitBreakPoint(
+				{
+					user_id: params.userId,
+					course_id: params.courseId,
+					lesson_id: params.lessonId,
+					break_point: params.breakPoint,
+				},
+				callback,
+			),
+		description: `saveBreakPoint(${params.lessonId}, ${params.breakPoint})`,
+	});
+
+	return result.success;
+}
+
+/**
+ * 获取播放断点
+ * @param params 断点参数
+ * @returns Promise<断点数据 | null>
+ */
+export async function getBreakPoint(
+	params: BreakPointParams,
+): Promise<unknown | null> {
+	const { yibanConnectionStatus } = useUserStore.getState();
+
+	if (yibanConnectionStatus !== "connected") {
+		return null;
+	}
+
+	if (!isVideoAjaxAvailable()) {
+		warnVideoAjaxUnavailable(`skip getBreakPoint, lessonId=${params.lessonId}`);
+		return null;
+	}
+
+	const result = await yibanStatusRequest<unknown>({
+		method: (callback) =>
+			getVideoAjax().getBreakPoint(
+				{
+					user_id: params.userId,
+					course_id: params.courseId,
+					lesson_id: params.lessonId,
+				},
+				callback,
+			),
+		description: `getBreakPoint(${params.lessonId})`,
+	});
+
+	return result.success ? result.data : null;
+}
+
+/**
+ * 保存用户答题记录
+ * @param params 答题参数
+ * @returns Promise<boolean> 是否成功保存
+ */
+export async function saveUserAnswer(params: {
+	userId: string;
+	lessonId: string;
+	courseId: string;
+	questionOrder: number;
+	answer: string;
+}): Promise<boolean> {
+	const { yibanConnectionStatus } = useUserStore.getState();
+
+	if (yibanConnectionStatus !== "connected") {
+		return false;
+	}
+
+	if (!isVideoAjaxAvailable()) {
+		warnVideoAjaxUnavailable(
+			`skip saveUserAnswer, lessonId=${params.lessonId}`,
+		);
+		return false;
+	}
+
+	const result = await yibanStatusRequest<unknown>({
+		method: (callback) =>
+			getVideoAjax().getUserAnswer(
+				{
+					user_id: params.userId,
+					lesson_id: params.lessonId,
+					course_id: params.courseId,
+					question_order: params.questionOrder,
+					answer: params.answer,
+				},
+				callback,
+			),
+		description: `saveUserAnswer(${params.lessonId}, Q${params.questionOrder})`,
+	});
+
+	return result.success;
+}