feat: add progression logic for puzzle residences

- Implemented functions to manage puzzle progress including checking if residences are started, complete, and unlocked.
- Added utility functions to retrieve piece IDs based on residence and route.
- Introduced a new TypeScript file for progression management.
- Integrated puzzle data configuration and residence data for seamless progression tracking.

src/lib/utils/api-common.ts

@@ -9,6 +9,11 @@ declare function getFutureDa(days: number): string
 declare function getCurrentDa(str: string): void
 declare function formatDateFromMilliseconds(date: Date): string
 
+// 本地或非易班环境下，外部全局变量可能未注入；统一用安全访问
+const isYibanRuntime = (): boolean => {
+  return typeof iscallyb !== 'undefined' && iscallyb === true
+}
+
 interface UserDefineParam {
   lessonId: string
   key?: string | number
@@ -72,8 +77,8 @@ $.extend({
 
 const LESSON_PREFIX = 'hsgrl'
 
-const videoajax: VideoAjax = videoAjax()
-videoajax.setHost('/')
+const videoajax: VideoAjax | null = typeof videoAjax !== 'undefined' ? videoAjax() : null
+videoajax?.setHost('/')
 
 function normalizeLessonId(lessonId: string | number): string {
   const raw = String(lessonId)
@@ -82,7 +87,7 @@ function normalizeLessonId(lessonId: string | number): string {
 
 // 设置我的自定义数据(所有的自定义数据都设置在第一个课时ID上，以key来区分不同的类型)
 function setLtDefine(key: string | number, value: string): void {
-  if (iscallyb) {
+  if (isYibanRuntime()) {
     setUserDefine(1, key, value)
   } else {
     sessionStorage.setItem(`${LESSON_PREFIX}_${key}`, value)
@@ -93,7 +98,7 @@ let mycstr9 = ''
 
 // 获取定义数据（由于底层是异步接口，这里返回 Promise）
 async function getLtDefine(key: string | number): Promise<string> {
-  if (iscallyb) {
+  if (isYibanRuntime()) {
     if (mycstr9 === '') {
       const all = await getUsersDefine(1, emykey)
       if (all === undefined || all === null || all === 'null' || all === '') {
@@ -137,6 +142,11 @@ export function setUserDefine(
   key: string | number,
   value: string
 ): void {
+  if (!isYibanRuntime() || !videoajax) {
+    sessionStorage.setItem(`${normalizeLessonId(lessonId)}_${key}`, value)
+    return
+  }
+
   const param: UserDefineParam = {
     lessonId: normalizeLessonId(lessonId),
     key,
@@ -150,14 +160,20 @@ function getUserDefineAsyncInternal(
   lessonId: string | number,
   key: string | number
 ): Promise<string> {
+  if (!isYibanRuntime() || !videoajax) {
+    const value = sessionStorage.getItem(`${normalizeLessonId(lessonId)}_${key}`)
+    return Promise.resolve(value === null || value === 'null' ? '' : value)
+  }
+
   const param: UserDefineParam = {
     lessonId: normalizeLessonId(lessonId),
     order: key,
   }
 
+  const ajax = videoajax
   return new Promise((resolve) => {
     let content = ''
-    videoajax.getUserDefineInfoByUser(param, (res) => {
+    ajax.getUserDefineInfoByUser(param, (res) => {
       // 保留原有 console 行为
       console.log(res)
       if (res && res.code === 200) {
@@ -185,14 +201,19 @@ function getUsersDefineAsyncInternal(
   lessonId: string | number,
   key: string | number
 ): Promise<string | VideoAjaxResponseItem[]> {
+  if (!isYibanRuntime() || !videoajax) {
+    return Promise.resolve('')
+  }
+
   const param: UserDefineParam = {
     lessonId: normalizeLessonId(lessonId),
     order: key,
   }
 
+  const ajax = videoajax
   return new Promise((resolve) => {
     let content: string | VideoAjaxResponseItem[] = ''
-    videoajax.getUserDefineInfo(param, (data) => {
+    ajax.getUserDefineInfo(param, (data) => {
       if (data && data.code === 200) {
         const json = (data.data.value || []) as VideoAjaxResponseItem[]
         if (json.length > 1) {
@@ -232,7 +253,13 @@ export async function setCourseTimeProgress(order: number): Promise<void> {
   // var courseid = getCookie(lesson+"_course_id");//获取url链接的课程ID
   // const courseid = await getLtDefine('10000')
   console.info(`courseid:${courseid} order:${order}`)
-  if (iscallyb && courseid !== undefined && courseid !== null && courseid !== '') {
+  if (
+    isYibanRuntime() &&
+    videoajax &&
+    courseid !== undefined &&
+    courseid !== null &&
+    courseid !== ''
+  ) {
     if (order > 0) {
       const param2 = { order, co: courseid, process: 100 }
       videoajax.finishCourse(param2)