chore(deps): add unstorage and migrate ChatStorage to use SpAsyncUtil

src/data/repositories/auth_repository.ts

@@ -12,7 +12,7 @@
  *
  * 原始 Dart: lib/data/repositories/auth_repository_impl.dart
  */
-import { AuthApi, authApi } from "@/data/api";
+import { AuthApi, authApi } from "@/data/services/api";
 import { AppleLoginRequest } from "@/data/dto/auth/apple_login_request";
 import { FacebookLoginRequest } from "@/data/dto/auth/facebook_login_request";
 import { FbIdLoginRequest } from "@/data/dto/auth/fb_id_login_request";

src/data/services/api/interceptor/auth_refresh_interceptor.ts

@@ -7,8 +7,9 @@
 import type { FetchHook } from "ofetch";
 import { ApiPath } from "../api_path";
 import { ApiError, ErrorCode } from "../api_result";
-import { authStorage } from "../../storage/auth_storage";
+import { AuthStorage } from "@/data/storage/auth/auth_storage";
 import { deviceIdentifier } from "@/utils/device_identifier";
+import { Result } from "@/utils/result";
 
 /**
  * 不需要 auth token 刷新的路径
@@ -32,6 +33,22 @@ let isRefreshing = false;
  */
 let refreshPromise: Promise<void> | null = null;
 
+/**
+ * 获取当前可用的 auth token（登录 token 优先，其次游客 token）
+ */
+async function getAuthTokenAsync(): Promise<string | null> {
+  const storage = AuthStorage.getInstance();
+  const loginResult = await storage.getLoginToken();
+  if (Result.isOk(loginResult) && loginResult.data && loginResult.data.length > 0) {
+    return loginResult.data;
+  }
+  const guestResult = await storage.getGuestToken();
+  if (Result.isOk(guestResult) && guestResult.data && guestResult.data.length > 0) {
+    return guestResult.data;
+  }
+  return null;
+}
+
 /**
  * 实际刷新 token（被拦截器调用）
  */
@@ -50,15 +67,16 @@ async function refreshToken(
  * 刷新登录 token
  */
 async function refreshLoginToken(baseUrl: string): Promise<void> {
-  const refreshToken = authStorage.getRefreshToken();
-  if (!refreshToken) {
+  const storage = AuthStorage.getInstance();
+  const refreshResult = await storage.getRefreshToken();
+  if (!Result.isOk(refreshResult) || !refreshResult.data) {
     throw new Error("No refresh token available");
   }
 
   const response = await fetch(`${baseUrl}${ApiPath.refresh}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ refreshToken }),
+    body: JSON.stringify({ refreshToken: refreshResult.data }),
   });
 
   if (!response.ok) {
@@ -71,9 +89,8 @@ async function refreshLoginToken(baseUrl: string): Promise<void> {
   };
 
   if (json.success && json.data) {
-    if (json.data.token) authStorage.setLoginToken(json.data.token);
-    if (json.data.refreshToken)
-      authStorage.setRefreshToken(json.data.refreshToken);
+    if (json.data.token) await storage.setLoginToken(json.data.token);
+    if (json.data.refreshToken) await storage.setRefreshToken(json.data.refreshToken);
   } else {
     throw new Error("Refresh response invalid");
   }
@@ -83,6 +100,7 @@ async function refreshLoginToken(baseUrl: string): Promise<void> {
  * 刷新游客 token
  */
 async function refreshGuestToken(baseUrl: string): Promise<void> {
+  const storage = AuthStorage.getInstance();
   const deviceId = await deviceIdentifier.getDeviceId();
 
   const response = await fetch(`${baseUrl}${ApiPath.guestLogin}`, {
@@ -101,8 +119,8 @@ async function refreshGuestToken(baseUrl: string): Promise<void> {
   };
 
   if (json.success && json.data) {
-    if (json.data.token) authStorage.setGuestToken(json.data.token);
-    if (json.data.deviceId) authStorage.setDeviceId(json.data.deviceId);
+    if (json.data.token) await storage.setGuestToken(json.data.token);
+    if (json.data.deviceId) await storage.setDeviceId(json.data.deviceId);
   } else {
     throw new Error("Guest refresh response invalid");
   }
@@ -124,7 +142,7 @@ export const onResponseErrorAuthRefresh: FetchHook = async (ctx) => {
   if (NO_AUTH_REFRESH_PATHS.some((p) => path.includes(p))) return;
 
   // 已登录则刷新登录 token，否则刷新游客 token
-  const isGuestMode = !authStorage.hasLoginToken();
+  const isGuestMode = !AuthStorage.getInstance().hasLoginToken();
 
   // 并发刷新：等待或启动
   if (isRefreshing && refreshPromise) {
@@ -144,9 +162,9 @@ export const onResponseErrorAuthRefresh: FetchHook = async (ctx) => {
   }
 
   // 刷新失败 → 清除数据并抛出
-  const newToken = authStorage.getAuthToken();
+  const newToken = await getAuthTokenAsync();
   if (!newToken) {
-    authStorage.clearAuthData();
+    AuthStorage.getInstance().clearAuthData();
     throw new ApiError(
       ErrorCode.unknownError,
       "Token refresh failed",

src/data/storage/app/app_storage.ts

@@ -1,14 +1,14 @@
 "use client";
 
 /**
- * AppStorage 完整实现（静态类风格 / localStorage）
+ * AppStorage 完整实现（基于 unstorage 抽象）
  *
  * 对齐 Dart 端 `AppStorage`（lib/data/services/storage/app_storage.dart）：
  *   - PWA 对话框每日展示 / PWA 事件每日上报 / app-info 每日上报
  *   - 内部用 `yyyy-MM-dd` 字符串比对实现"每日一次"语义
  *
  * 注意：Dart 端是 `static class` 没有接口，本 TS 版本同样保持静态方法风格。
- * 通过 `LocalStorage` 单例 + 懒加载的私有 getter 访问底层存储。
+ * 通过 SpAsyncUtil 静态类访问底层存储（浏览器 localStorage / SSR memory 自动切换）。
  *
  * 语义：
  *   - `canXxx(today)` 返回 `true` 当且仅当"自上次记录以来日期变了"
@@ -17,23 +17,10 @@
  */
 
 import { Result, type Result as ResultT } from "@/utils/result";
+import { SpAsyncUtil } from "@/utils/storage";
 import { StorageKeys } from "../storage_keys";
-import { LocalStorage } from "@/utils/local-storage";
 
 export class AppStorage {
-  private static _ls: LocalStorage | null = null;
-
-  /** 懒加载 LocalStorage 单例，避免模块加载期触发 SSR 副作用。 */
-  private static get ls(): LocalStorage {
-    if (!AppStorage._ls) AppStorage._ls = LocalStorage.getInstance();
-    return AppStorage._ls;
-  }
-
-  /** @internal */
-  static _resetForTests(): void {
-    AppStorage._ls = null;
-  }
-
   // ---- PWA install dialog ----
 
   static async canShowPwaDialog(todayString: string): Promise<ResultT<boolean>> {
@@ -41,7 +28,7 @@ export class AppStorage {
   }
 
   static recordPwaDialogShown(todayString: string): Promise<ResultT<void>> {
-    return AppStorage.ls.setString(StorageKeys.lastPwaDialogShown, todayString);
+    return SpAsyncUtil.setString(StorageKeys.lastPwaDialogShown, todayString);
   }
 
   // ---- PWA event reporting ----
@@ -51,7 +38,7 @@ export class AppStorage {
   }
 
   static recordPwaEventReported(todayString: string): Promise<ResultT<void>> {
-    return AppStorage.ls.setString(StorageKeys.lastPwaEventReported, todayString);
+    return SpAsyncUtil.setString(StorageKeys.lastPwaEventReported, todayString);
   }
 
   // ---- app info reporting ----
@@ -61,7 +48,7 @@ export class AppStorage {
   }
 
   static recordAppInfoReported(todayString: string): Promise<ResultT<void>> {
-    return AppStorage.ls.setString(StorageKeys.lastAppInfoReported, todayString);
+    return SpAsyncUtil.setString(StorageKeys.lastAppInfoReported, todayString);
   }
 
   // ---- internal helpers ----
@@ -77,7 +64,7 @@ export class AppStorage {
     key: string,
     todayString: string,
   ): Promise<ResultT<boolean>> {
-    const r = await AppStorage.ls.getString(key);
+    const r = await SpAsyncUtil.getString(key);
     if (!r.success) return r;
     return Result.ok(r.data === null || r.data !== todayString);
   }

src/data/storage/auth/auth_storage.ts

@@ -1,32 +1,29 @@
 "use client";
 
 /**
- * AuthStorage 完整实现（示范 1：KV / localStorage）
+ * AuthStorage 完整实现（基于 unstorage 抽象）
+ *
+ * 原始 Dart: lib/data/services/storage/auth_storage.dart
  *
  * SECURITY: 当前与 Dart 端行为一致，refresh_token 以明文存于 localStorage。
  * 后续轮次将升级到 HttpOnly Cookie 方案，参见 `clearAuthData` 处的 TODO 标记。
  *
  * 设计说明：
- *   - 组合而非继承 `LocalStorage`（避免多重继承层级）
+ *   - 内部使用 `SpAsyncUtil` 静态类（@/utils/storage）
+ *   - 浏览器 → `localStorage` driver；SSR → memory driver（unstorage 自动）
  *   - 单例挂在 class 静态字段，规避 HMR 复用污染
- *   - 构造函数接受可选 `LocalStorage` 注入，便于测试时使用 jsdom 的 storage
  *   - `hasXxx` = `token != null && token.length > 0`，对齐 Dart 端 `isNotEmpty` 语义
  *   - `clearAuthData` 顺序清理：loginToken → guestToken → refreshToken，任一失败立即返回
  */
 
 import { Result, type Result as ResultT } from "@/utils/result";
+import { SpAsyncUtil } from "@/utils/storage";
 import { StorageKeys } from "../storage_keys";
 import type { IAuthStorage } from "./iauth_storage";
-import { LocalStorage } from "@/utils/local-storage";
 
 export class AuthStorage implements IAuthStorage {
-  private readonly ls: LocalStorage;
   private static _instance: AuthStorage | null = null;
 
-  constructor(localStorage?: LocalStorage) {
-    this.ls = localStorage ?? LocalStorage.getInstance();
-  }
-
   static getInstance(): AuthStorage {
     if (!AuthStorage._instance) AuthStorage._instance = new AuthStorage();
     return AuthStorage._instance;
@@ -40,10 +37,10 @@ export class AuthStorage implements IAuthStorage {
   // ---- login token ----
 
   getLoginToken(): Promise<ResultT<string | null>> {
-    return this.ls.getString(StorageKeys.loginToken);
+    return SpAsyncUtil.getString(StorageKeys.loginToken);
   }
   setLoginToken(token: string): Promise<ResultT<void>> {
-    return this.ls.setString(StorageKeys.loginToken, token);
+    return SpAsyncUtil.setString(StorageKeys.loginToken, token);
   }
   async hasLoginToken(): Promise<ResultT<boolean>> {
     const r = await this.getLoginToken();
@@ -51,16 +48,16 @@ export class AuthStorage implements IAuthStorage {
     return Result.ok(r.data !== null && r.data.length > 0);
   }
   clearLoginToken(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.loginToken);
+    return SpAsyncUtil.remove(StorageKeys.loginToken);
   }
 
   // ---- guest token ----
 
   getGuestToken(): Promise<ResultT<string | null>> {
-    return this.ls.getString(StorageKeys.guestToken);
+    return SpAsyncUtil.getString(StorageKeys.guestToken);
   }
   setGuestToken(token: string): Promise<ResultT<void>> {
-    return this.ls.setString(StorageKeys.guestToken, token);
+    return SpAsyncUtil.setString(StorageKeys.guestToken, token);
   }
   async hasGuestToken(): Promise<ResultT<boolean>> {
     const r = await this.getGuestToken();
@@ -68,16 +65,16 @@ export class AuthStorage implements IAuthStorage {
     return Result.ok(r.data !== null && r.data.length > 0);
   }
   clearGuestToken(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.guestToken);
+    return SpAsyncUtil.remove(StorageKeys.guestToken);
   }
 
   // ---- device id ----
 
   getDeviceId(): Promise<ResultT<string | null>> {
-    return this.ls.getString(StorageKeys.deviceId);
+    return SpAsyncUtil.getString(StorageKeys.deviceId);
   }
   setDeviceId(deviceId: string): Promise<ResultT<void>> {
-    return this.ls.setString(StorageKeys.deviceId, deviceId);
+    return SpAsyncUtil.setString(StorageKeys.deviceId, deviceId);
   }
 
   // ---- refresh token ----
@@ -85,22 +82,22 @@ export class AuthStorage implements IAuthStorage {
   // SECURITY: 明文存储，仅供本轮与 Dart 行为对齐
 
   getRefreshToken(): Promise<ResultT<string | null>> {
-    return this.ls.getString(StorageKeys.refreshToken);
+    return SpAsyncUtil.getString(StorageKeys.refreshToken);
   }
   setRefreshToken(token: string): Promise<ResultT<void>> {
-    return this.ls.setString(StorageKeys.refreshToken, token);
+    return SpAsyncUtil.setString(StorageKeys.refreshToken, token);
   }
   clearRefreshToken(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.refreshToken);
+    return SpAsyncUtil.remove(StorageKeys.refreshToken);
   }
 
   // ---- facebook id ----
 
   getFacebookId(): Promise<ResultT<string | null>> {
-    return this.ls.getString(StorageKeys.facebookId);
+    return SpAsyncUtil.getString(StorageKeys.facebookId);
   }
   setFacebookId(id: string): Promise<ResultT<void>> {
-    return this.ls.setString(StorageKeys.facebookId, id);
+    return SpAsyncUtil.setString(StorageKeys.facebookId, id);
   }
 
   // ---- bulk clear ----

src/data/storage/chat/chat_storage.ts

@@ -1,7 +1,7 @@
 "use client";
 
 /**
- * ChatStorage 完整实现（KV / localStorage）
+ * ChatStorage 完整实现（基于 unstorage 抽象）
  *
  * 对齐 Dart 端 `ChatStorage`（lib/data/services/storage/chat/chat_storage.dart）：
  *   - 游客每日聊天配额（GuestChatQuota：{ remaining, date }）
@@ -11,8 +11,7 @@
  *   - ChatStorage = 游客配额等元数据（KV）
  *   - LocalChatStorage = 聊天记录本身（IndexedDB）
  *
- * 设计沿用 AuthStorage 模式：组合 `LocalStorage` + 单例 + Zod 校验。
- * 跨天重置判断（`needsReset`）保留在 `GuestChatQuota` 类上，存储层只做读写。
+ * 设计：内部使用 SpAsyncUtil 静态类 + Zod 校验；保持对外 API 完全兼容。
  */
 
 import {
@@ -22,18 +21,13 @@ import {
 import { z } from "zod";
 
 import { type Result as ResultT } from "@/utils/result";
+import { SpAsyncUtil } from "@/utils/storage";
 import { StorageKeys } from "../storage_keys";
 import type { IChatStorage } from "./ichat_storage";
-import { LocalStorage } from "@/utils/local-storage";
 
 export class ChatStorage implements IChatStorage {
-  private readonly ls: LocalStorage;
   private static _instance: ChatStorage | null = null;
 
-  constructor(localStorage?: LocalStorage) {
-    this.ls = localStorage ?? LocalStorage.getInstance();
-  }
-
   static getInstance(): ChatStorage {
     if (!ChatStorage._instance) ChatStorage._instance = new ChatStorage();
     return ChatStorage._instance;
@@ -47,29 +41,29 @@ export class ChatStorage implements IChatStorage {
   // ---- guest daily chat quota ----
 
   getGuestDailyChatQuota(): Promise<ResultT<GuestChatQuotaData | null>> {
-    return this.ls.getJson(StorageKeys.guestChatQuota, GuestChatQuotaSchema);
+    return SpAsyncUtil.getJson(StorageKeys.guestChatQuota, GuestChatQuotaSchema);
   }
 
   setGuestDailyChatQuota(remaining: number, date: string): Promise<ResultT<void>> {
     const value: GuestChatQuotaData = { remaining, date };
-    return this.ls.setJson(StorageKeys.guestChatQuota, value, GuestChatQuotaSchema);
+    return SpAsyncUtil.setJson(StorageKeys.guestChatQuota, value, GuestChatQuotaSchema);
   }
 
   clearGuestDailyChatQuota(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.guestChatQuota);
+    return SpAsyncUtil.remove(StorageKeys.guestChatQuota);
   }
 
   // ---- guest total quota ----
 
   getGuestTotalQuota(): Promise<ResultT<number | null>> {
-    return this.ls.getJson(StorageKeys.guestTotalQuotaRemaining, z.number());
+    return SpAsyncUtil.getJson(StorageKeys.guestTotalQuotaRemaining, z.number());
   }
 
   setGuestTotalQuota(remaining: number): Promise<ResultT<void>> {
-    return this.ls.setJson(StorageKeys.guestTotalQuotaRemaining, remaining, z.number());
+    return SpAsyncUtil.setJson(StorageKeys.guestTotalQuotaRemaining, remaining, z.number());
   }
 
   clearGuestTotalQuota(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.guestTotalQuotaRemaining);
+    return SpAsyncUtil.remove(StorageKeys.guestTotalQuotaRemaining);
   }
 }

src/data/storage/index.ts

@@ -1,8 +1,10 @@
 /**
- * @file Automatically generated by barrelsby.
+ * @file Storage 公共导出
+ *
+ * unstorage 重构后：
+ *   - 删除 `./local_storage`（原自定义 LocalStorage class 已被 unstorage 取代）
+ *   - 业务层（AuthStorage / ChatStorage / UserStorage / AppStorage）继续走原接口
  */
-
-export * from "./local_storage";
 export * from "@/utils/result";
 export * from "./storage_keys";
 export * from "./app/app_storage";

src/data/storage/user/user_storage.ts

@@ -1,13 +1,13 @@
 "use client";
 
 /**
- * UserStorage 完整实现（KV / localStorage）
+ * UserStorage 完整实现（基于 unstorage 抽象）
  *
  * 对齐 Dart 端 `UserStorage`（lib/data/services/storage/user_storage.dart）：
  *   - 三个独立字段：User 对象 / userId / avatarUrl
  *   - `clearUserData()` 批量清空
  *
- * 设计沿用 AuthStorage 模式：组合 `LocalStorage`（非继承）+ 单例 + Zod 校验。
+ * 设计：内部使用 SpAsyncUtil 静态类 + Zod 校验；保持对外 API 完全兼容。
  *
  * 边界：
  *   - `getUser` 走 `UserSchema` 解析：缺字段时 Zod `.default()` 自动兜底
@@ -17,18 +17,13 @@
 
 import { UserSchema, type UserData } from "@/data/schemas/user/user";
 import { type Result as ResultT } from "@/utils/result";
+import { SpAsyncUtil } from "@/utils/storage";
 import { StorageKeys } from "../storage_keys";
 import type { IUserStorage } from "./iuser_storage";
-import { LocalStorage } from "@/utils/local-storage";
 
 export class UserStorage implements IUserStorage {
-  private readonly ls: LocalStorage;
   private static _instance: UserStorage | null = null;
 
-  constructor(localStorage?: LocalStorage) {
-    this.ls = localStorage ?? LocalStorage.getInstance();
-  }
-
   static getInstance(): UserStorage {
     if (!UserStorage._instance) UserStorage._instance = new UserStorage();
     return UserStorage._instance;
@@ -42,43 +37,43 @@ export class UserStorage implements IUserStorage {
   // ---- user object ----
 
   getUser(): Promise<ResultT<UserData | null>> {
-    return this.ls.getJson(StorageKeys.user, UserSchema);
+    return SpAsyncUtil.getJson(StorageKeys.user, UserSchema);
   }
 
   setUser(user: UserData): Promise<ResultT<void>> {
-    return this.ls.setJson(StorageKeys.user, user, UserSchema);
+    return SpAsyncUtil.setJson(StorageKeys.user, user, UserSchema);
   }
 
   clearUser(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.user);
+    return SpAsyncUtil.remove(StorageKeys.user);
   }
 
   // ---- userId ----
 
   getUserId(): Promise<ResultT<string | null>> {
-    return this.ls.getString(StorageKeys.userId);
+    return SpAsyncUtil.getString(StorageKeys.userId);
   }
 
   setUserId(id: string): Promise<ResultT<void>> {
-    return this.ls.setString(StorageKeys.userId, id);
+    return SpAsyncUtil.setString(StorageKeys.userId, id);
   }
 
   clearUserId(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.userId);
+    return SpAsyncUtil.remove(StorageKeys.userId);
   }
 
   // ---- avatarUrl ----
 
   getAvatarUrl(): Promise<ResultT<string | null>> {
-    return this.ls.getString(StorageKeys.userAvatar);
+    return SpAsyncUtil.getString(StorageKeys.userAvatar);
   }
 
   setAvatarUrl(url: string): Promise<ResultT<void>> {
-    return this.ls.setString(StorageKeys.userAvatar, url);
+    return SpAsyncUtil.setString(StorageKeys.userAvatar, url);
   }
 
   clearAvatarUrl(): Promise<ResultT<void>> {
-    return this.ls.remove(StorageKeys.userAvatar);
+    return SpAsyncUtil.remove(StorageKeys.userAvatar);
   }
 
   // ---- bulk clear ----