@usethink/cf-admin-fe 0.1.1 → 0.2.8

package/src/composables/createAdminRequest.ts

@@ -0,0 +1,322 @@
+/**
+ * 产品管理端 HTTP 客户端工厂。
+ *
+ * CF 各产品差异点：
+ * - 认证：Bearer JWT（shop/lottery）vs cookie 会话（cf-auth）
+ * - 成功判定：仅 `res.ok` vs `res.ok && data.ok`
+ * - 错误字段：`error` vs `message`
+ * - 401 副作用：清 token / 整会话清空 / 跳转登录
+ * - Token 来源：闭包 `getToken` vs 每次调用传 `token`（shop 的 api/admin.ts）
+ *
+ * 业务 API 方法仍在产品侧；此处只统一 fetch、请求头与 401 处理。
+ */
+
+export type AdminRequestResultMode = 'http-ok' | 'ok-envelope'
+
+/** 结构化错误，便于产品映射到 AdminApiError，无需再解析 message 字符串。 */
+export class AdminRequestError extends Error {
+  readonly status: number
+  readonly code?: string
+  readonly data: Record<string, unknown>
+  readonly response?: Response
+
+  constructor(
+    message: string,
+    status: number,
+    options?: {
+      code?: string
+      data?: Record<string, unknown>
+      response?: Response
+    },
+  ) {
+    super(message)
+    this.name = 'AdminRequestError'
+    this.status = status
+    this.code = options?.code
+    this.data = options?.data ?? {}
+    this.response = options?.response
+  }
+}
+
+export type CreateAdminRequestOptions = {
+  /** 可选 API 前缀（如 `''` 或 origin）。path 仍可为绝对地址。 */
+  baseUrl?: string
+  /** 返回当前 Bearer token；省略/空 → 不带 Authorization */
+  getToken?: () => string | null | undefined
+  /** fetch credentials；cookie 管理端用 `include` */
+  credentials?: RequestCredentials
+  /**
+   * - `http-ok`：`res.ok` 即成功（cf-shop admin.ts 风格；body 可无 `ok`）
+   * - `ok-envelope`：`res.ok && data.ok`（lottery / 多数列表接口）
+   */
+  resultMode?: AdminRequestResultMode
+  /** 构造 Error 时优先取 `error`（shop）或 `message`（lottery） */
+  errorField?: 'error' | 'message' | 'auto'
+  /** HTTP 401 且抛错前调用；产品负责清会话并跳转登录 */
+  onUnauthorized?: (ctx: {
+    path: string
+    data: Record<string, unknown>
+    response: Response
+  }) => void
+  /**
+   * 成功响应被接受后调用（http-ok / ok-envelope）。
+   * Cookie 管理端用来「治愈」缺失的本地守卫 flag，无需每个调用点包一层（cf-auth 模式）。
+   * Bearer 产品通常省略。
+   */
+  onSuccess?: (ctx: {
+    path: string
+    data: Record<string, unknown>
+    response: Response
+  }) => void
+  /**
+   * 为 false 时：401 仍抛错，但跳过 onUnauthorized
+   * （登录探测 token 时不得清掉已有会话）。
+   */
+  redirectOnUnauthorized?: boolean
+  /** 默认请求头，会被单次调用的 headers 覆盖合并 */
+  defaultHeaders?: HeadersInit
+  /**
+   * 跳过跳转时（token 探测）401 文案覆盖。
+   * Shop 使用固定「管理令牌无效」与 code INVALID_ADMIN_TOKEN。
+   */
+  unauthorizedProbeMessage?: string
+  unauthorizedProbeCode?: string
+}
+
+export type AdminRequestCallOptions = RequestInit & {
+  /** 查询参数；undefined / '' 会跳过 */
+  params?: Record<string, string | number | boolean | Array<string | number> | undefined | null>
+  /** 覆盖工厂对本调用的 redirectOnUnauthorized 默认 */
+  redirectOnUnauthorized?: boolean
+  /**
+   * 单次调用的 Bearer token（shop 每个域 API 方法都会传入）。
+   * 已设置时（含空字符串）覆盖工厂 `getToken`。
+   */
+  token?: string | null
+}
+
+export type AdminRequestFn = <T = unknown>(
+  path: string,
+  options?: AdminRequestCallOptions,
+) => Promise<T>
+
+/**
+ * 非 JSON 管理端请求（blob 模板 / 导出下载）。
+ * 不解析成功 body；只检查 `res.ok` 并处理 401。
+ */
+export type AdminRequestRawFn = (
+  path: string,
+  options?: AdminRequestCallOptions,
+) => Promise<Response>
+
+function joinUrl(baseUrl: string, path: string): string {
+  if (!baseUrl) return path
+  if (/^https?:\/\//i.test(path)) return path
+  const base = baseUrl.replace(/\/+$/, '')
+  const rel = path.startsWith('/') ? path : `/${path}`
+  return `${base}${rel}`
+}
+
+function appendParams(
+  url: string,
+  params?: AdminRequestCallOptions['params'],
+): string {
+  if (!params) return url
+  const query = new URLSearchParams()
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') continue
+    query.set(key, Array.isArray(value) ? value.join(',') : String(value))
+  }
+  const qs = query.toString()
+  if (!qs) return url
+  return url.includes('?') ? `${url}&${qs}` : `${url}?${qs}`
+}
+
+function pickErrorMessage(
+  data: Record<string, unknown>,
+  status: number,
+  errorField: CreateAdminRequestOptions['errorField'],
+): string {
+  const err = typeof data.error === 'string' ? data.error : ''
+  const msg = typeof data.message === 'string' ? data.message : ''
+  if (errorField === 'error') return err || msg || `请求失败（${status}）`
+  if (errorField === 'message') return msg || err || `请求失败（${status}）`
+  return msg || err || `请求失败（${status}）`
+}
+
+function pickCode(data: Record<string, unknown>): string | undefined {
+  return typeof data.code === 'string' ? data.code : undefined
+}
+
+function isSuccess(
+  res: Response,
+  data: Record<string, unknown>,
+  mode: AdminRequestResultMode,
+): boolean {
+  if (!res.ok) return false
+  if (mode === 'http-ok') return true
+  // ok-envelope（lottery / 多数 CF 管理端 API）：要求显式 ok:true
+  return data.ok === true
+}
+
+/**
+ * 构建可复用的 `adminRequest(path, init)`。
+ */
+export function createAdminRequest(factory: CreateAdminRequestOptions = {}): AdminRequestFn {
+  const baseUrl = factory.baseUrl ?? ''
+  const resultMode: AdminRequestResultMode = factory.resultMode ?? 'ok-envelope'
+  const errorField = factory.errorField ?? 'auto'
+  const defaultRedirect = factory.redirectOnUnauthorized !== false
+
+  return async function adminRequest<T = unknown>(
+    path: string,
+    options: AdminRequestCallOptions = {},
+  ): Promise<T> {
+    const {
+      params,
+      redirectOnUnauthorized = defaultRedirect,
+      headers: callHeaders,
+      token: callToken,
+      ...fetchOptions
+    } = options
+
+    const url = appendParams(joinUrl(baseUrl, path), params)
+    const headers = new Headers(factory.defaultHeaders)
+    if (callHeaders) {
+      const extra = new Headers(callHeaders)
+      extra.forEach((value, key) => headers.set(key, value))
+    }
+
+    const token =
+      callToken !== undefined ? callToken : factory.getToken?.()
+    if (token) headers.set('Authorization', `Bearer ${token}`)
+
+    // 默认 JSON；FormData 须保留浏览器 multipart boundary。
+    if (!(fetchOptions.body instanceof FormData) && !headers.has('Content-Type')) {
+      headers.set('Content-Type', 'application/json')
+    }
+
+    const res = await fetch(url, {
+      ...fetchOptions,
+      headers,
+      credentials: factory.credentials ?? fetchOptions.credentials,
+    })
+
+    const data = (await res.json().catch(() => ({}))) as Record<string, unknown>
+
+    if (res.status === 401) {
+      if (redirectOnUnauthorized && factory.onUnauthorized) {
+        factory.onUnauthorized({ path, data, response: res })
+      }
+      const probe = !redirectOnUnauthorized
+      const message = probe
+        ? factory.unauthorizedProbeMessage ||
+          pickErrorMessage(data, 401, errorField) ||
+          '登录已过期，请重新登录'
+        : pickErrorMessage(data, 401, errorField) || '登录已过期，请重新登录'
+      const code = probe
+        ? factory.unauthorizedProbeCode || pickCode(data) || 'UNAUTHORIZED'
+        : pickCode(data) || 'UNAUTHORIZED'
+      throw new AdminRequestError(message, 401, { code, data, response: res })
+    }
+
+    if (!isSuccess(res, data, resultMode)) {
+      throw new AdminRequestError(pickErrorMessage(data, res.status, errorField), res.status, {
+        code: pickCode(data) || 'ADMIN_ERROR',
+        data,
+        response: res,
+      })
+    }
+
+    try {
+      factory.onSuccess?.({ path, data, response: res })
+    } catch {
+      /* 产品侧 heal 不得打断已成功的载荷 */
+    }
+
+    return data as T
+  }
+}
+
+/**
+ * 构建 raw `adminRequestRaw(path, init)`，用于二进制 / 非 JSON 响应。
+ * 与 {@link createAdminRequest} 共享 token、params、headers 与 401 行为。
+ */
+export function createAdminRequestRaw(
+  factory: CreateAdminRequestOptions = {},
+): AdminRequestRawFn {
+  const baseUrl = factory.baseUrl ?? ''
+  const errorField = factory.errorField ?? 'auto'
+  const defaultRedirect = factory.redirectOnUnauthorized !== false
+
+  return async function adminRequestRaw(
+    path: string,
+    options: AdminRequestCallOptions = {},
+  ): Promise<Response> {
+    const {
+      params,
+      redirectOnUnauthorized = defaultRedirect,
+      headers: callHeaders,
+      token: callToken,
+      ...fetchOptions
+    } = options
+
+    const url = appendParams(joinUrl(baseUrl, path), params)
+    const headers = new Headers(factory.defaultHeaders)
+    if (callHeaders) {
+      const extra = new Headers(callHeaders)
+      extra.forEach((value, key) => headers.set(key, value))
+    }
+
+    const token = callToken !== undefined ? callToken : factory.getToken?.()
+    if (token) headers.set('Authorization', `Bearer ${token}`)
+
+    // raw 下载不强加 JSON Content-Type。
+    const res = await fetch(url, {
+      ...fetchOptions,
+      headers,
+      credentials: factory.credentials ?? fetchOptions.credentials,
+    })
+
+    if (res.ok) {
+      // 与 createAdminRequest 对齐：raw 下载也可触发 cookie flag 治愈 / 产品钩子。
+      try {
+        factory.onSuccess?.({ path, data: {}, response: res })
+      } catch {
+        /* 产品侧 heal 不得打断已成功的下载 */
+      }
+      return res
+    }
+
+    const data = (await res
+      .clone()
+      .json()
+      .catch(() => ({}))) as Record<string, unknown>
+
+    if (res.status === 401) {
+      if (redirectOnUnauthorized && factory.onUnauthorized) {
+        factory.onUnauthorized({ path, data, response: res })
+      }
+      const probe = !redirectOnUnauthorized
+      const message = probe
+        ? factory.unauthorizedProbeMessage ||
+          pickErrorMessage(data, 401, errorField) ||
+          '登录已过期，请重新登录'
+        : pickErrorMessage(data, 401, errorField) || '登录已过期，请重新登录'
+      const code = probe
+        ? factory.unauthorizedProbeCode || pickCode(data) || 'UNAUTHORIZED'
+        : pickCode(data) || 'UNAUTHORIZED'
+      throw new AdminRequestError(message, 401, { code, data, response: res })
+    }
+
+    throw new AdminRequestError(
+      pickErrorMessage(data, res.status, errorField) || `管理端请求失败：${res.status}`,
+      res.status,
+      {
+        code: pickCode(data) || 'ADMIN_ERROR',
+        data,
+        response: res,
+      },
+    )
+  }
+}

package/src/composables/createAdminTokenSession.ts

@@ -0,0 +1,149 @@
+/**
+ * 通用管理端 Bearer token 会话（localStorage + TTL）。
+ *
+ * 产品在其上叠加产品专属 key / 伪装 / 平台角色。
+ * Cookie 会话产品改用 {@link createAdminFlagSession}（无 Bearer）。
+ */
+import { computed, ref, type ComputedRef, type Ref } from 'vue'
+
+export type StoredAdminToken = { token: string; expiry: number }
+
+export const DEFAULT_ADMIN_TOKEN_TTL_MS = 8 * 60 * 60 * 1000
+
+export type CreateAdminTokenSessionOptions = {
+  /** localStorage 键名（如 `admin_token`） */
+  storageKey: string
+  /** 会话有效期；默认 8 小时，对齐常见 verify-jwt 会话 JWT */
+  ttlMs?: number
+  /** 覆盖存储实现（测试用）；默认在可用时用 `localStorage` */
+  storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null
+}
+
+function resolveStorage(
+  explicit?: CreateAdminTokenSessionOptions['storage'],
+): Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null {
+  if (explicit !== undefined) return explicit
+  try {
+    if (typeof localStorage === 'undefined') return null
+    return localStorage
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 解析已存储的 token 记录。
+ * - 含 token+expiry 的对象：遵守 TTL；过期则清除键
+ * - 旧版裸字符串：保留一次迁移（不自动清除）
+ */
+export function parseStoredAdminToken(
+  raw: string | null,
+  options?: { storageKey?: string; storage?: CreateAdminTokenSessionOptions['storage'] },
+): string {
+  if (!raw) return ''
+  const storage = resolveStorage(options?.storage)
+  try {
+    const parsed = JSON.parse(raw) as StoredAdminToken
+    if (typeof parsed.token === 'string' && typeof parsed.expiry === 'number') {
+      if (Date.now() < parsed.expiry) return parsed.token
+      if (options?.storageKey && storage) {
+        try {
+          storage.removeItem(options.storageKey)
+        } catch {
+          /* 忽略清除失败 */
+        }
+      }
+      return ''
+    }
+    return ''
+  } catch {
+    return raw
+  }
+}
+
+export function readAdminTokenFromStorage(
+  storageKey: string,
+  storage?: CreateAdminTokenSessionOptions['storage'],
+): string {
+  const store = resolveStorage(storage)
+  if (!store) return ''
+  try {
+    return parseStoredAdminToken(store.getItem(storageKey), { storageKey, storage: store })
+  } catch {
+    return ''
+  }
+}
+
+export type AdminTokenSession = {
+  token: Ref<string>
+  isLoggedIn: ComputedRef<boolean>
+  setToken: (value: string) => void
+  clearToken: () => void
+  readToken: () => string
+  storageKey: string
+  ttlMs: number
+}
+
+/**
+ * 单个管理端 token 键的 Vue 会话句柄。
+ * 在 setup 外的路由守卫中调用 `readToken`。
+ */
+export function createAdminTokenSession(
+  options: CreateAdminTokenSessionOptions,
+): AdminTokenSession {
+  const storageKey = options.storageKey
+  const ttlMs = options.ttlMs ?? DEFAULT_ADMIN_TOKEN_TTL_MS
+  const storage = resolveStorage(options.storage)
+
+  function readToken(): string {
+    return readAdminTokenFromStorage(storageKey, storage)
+  }
+
+  const token = ref<string>(readToken())
+  const isLoggedIn = computed(() => !!token.value)
+
+  function setToken(value: string) {
+    const stored: StoredAdminToken = { token: value, expiry: Date.now() + ttlMs }
+    token.value = value
+    if (!storage) return
+    try {
+      storage.setItem(storageKey, JSON.stringify(stored))
+    } catch {
+      /* 隐私模式 */
+    }
+  }
+
+  function clearToken() {
+    token.value = ''
+    if (!storage) return
+    try {
+      storage.removeItem(storageKey)
+    } catch {
+      /* ignore */
+    }
+  }
+
+  return {
+    token,
+    isLoggedIn,
+    setToken,
+    clearToken,
+    readToken,
+    storageKey,
+    ttlMs,
+  }
+}
+
+/**
+ * 便捷组合式：默认键 `admin_token`、8 小时 TTL（cf-shop 形态）。
+ * 多租户 / 伪装登录产品应直接调用 {@link createAdminTokenSession}。
+ */
+export function useAdminTokenSession(
+  options?: Partial<CreateAdminTokenSessionOptions>,
+): AdminTokenSession {
+  return createAdminTokenSession({
+    storageKey: options?.storageKey ?? 'admin_token',
+    ttlMs: options?.ttlMs,
+    storage: options?.storage,
+  })
+}

package/src/composables/index.ts

@@ -31,4 +31,55 @@ export {
 export {
   writeClipboardText,
   copyText,
+  copyWithToast,
+  type CopyWithToastOptions,
 } from './useClipboard'
+
+export {
+  createAdminTokenSession,
+  useAdminTokenSession,
+  parseStoredAdminToken,
+  readAdminTokenFromStorage,
+  DEFAULT_ADMIN_TOKEN_TTL_MS,
+  type StoredAdminToken,
+  type CreateAdminTokenSessionOptions,
+  type AdminTokenSession,
+} from './createAdminTokenSession'
+
+export {
+  createAdminFlagSession,
+  readAdminFlagFromStorage,
+  writeAdminFlagToStorage,
+  DEFAULT_ADMIN_FLAG_TRUTHY,
+  type CreateAdminFlagSessionOptions,
+  type AdminFlagSession,
+} from './createAdminFlagSession'
+
+export {
+  createAdminRequest,
+  createAdminRequestRaw,
+  AdminRequestError,
+  type CreateAdminRequestOptions,
+  type AdminRequestCallOptions,
+  type AdminRequestFn,
+  type AdminRequestRawFn,
+  type AdminRequestResultMode,
+} from './createAdminRequest'
+
+export {
+  useAdminSidebar,
+  type UseAdminSidebarOptions,
+  type UseAdminSidebarReturn,
+} from './useAdminSidebar'
+
+export {
+  useAdminListLoader,
+  type UseAdminListLoaderOptions,
+  type UseAdminListLoaderReturn,
+  type AdminListLoadContext,
+  type AdminListRunLoadOptions,
+} from './useAdminListLoader'
+
+export {
+  useNow,
+} from './useNow'

package/src/composables/useAdminBatchOperation.ts

@@ -1,3 +1,7 @@
+/**
+ * 管理端逐条串行批处理：进度 ref + 成功/失败汇总。
+ * 服务端一次返回 `{ success, failed }` 的接口请改用 `buildBatchToast` / `resolveBatchToastType`。
+ */
 import { ref } from 'vue'
 
 export interface AdminBatchOperationResult<T> {

package/src/composables/useAdminListLoader.ts

@@ -0,0 +1,124 @@
+/**
+ * 后台列表通用的加载生命周期：loading / loadError / 竞态安全的序号。
+ * 业务请求、列定义、筛选逻辑保留在产品页面中。
+ */
+import { ref, type Ref } from 'vue'
+
+export type UseAdminListLoaderOptions = {
+  /** 初始加载状态（默认 false）。 */
+  initialLoading?: boolean
+}
+
+export type AdminListLoadContext = {
+  /** 本次尝试的单调递增序号。 */
+  sequence: number
+  /** 若有更新的加载已开始（或调用了 invalidate），返回 true。 */
+  isStale: () => boolean
+}
+
+export type AdminListRunLoadOptions = {
+  /**
+   * 将抛出的错误映射为面向用户的 loadError 字符串。
+   * 默认：Error.message 或 String(err)。
+   */
+  onError?: (err: unknown) => string
+}
+
+export type UseAdminListLoaderReturn = {
+  loading: Ref<boolean>
+  loadError: Ref<string>
+  /** 递增序号、置 loading 为 true、清空 loadError；返回本次尝试的序号。 */
+  beginLoad: () => number
+  isStale: (sequence: number) => boolean
+  /** 仅当序号仍为最新时清除 loading。 */
+  finishLoad: (sequence: number) => void
+  /**
+   * 若序号仍为最新则记录错误信息。
+   * @returns 错误是否已生效（未被判定为过期）
+   */
+  failLoad: (sequence: number, message: string) => boolean
+  /**
+   * 完整且竞态安全的加载流程：begin → work → catch → finish。
+   * work 内部在 await 之后应通过 `ctx.isStale()` 提前返回。
+   * @returns 若尝试未抛错且 try 结束时未过期，返回 true
+   */
+  runLoad: (
+    work: (ctx: AdminListLoadContext) => void | Promise<void>,
+    options?: AdminListRunLoadOptions,
+  ) => Promise<boolean>
+  /** 使进行中的加载失效（例如组件卸载时）。 */
+  invalidate: () => void
+}
+
+function defaultErrorMessage(err: unknown): string {
+  if (err instanceof Error && err.message) return err.message
+  if (typeof err === 'string' && err) return err
+  return '加载失败'
+}
+
+export function useAdminListLoader(
+  options: UseAdminListLoaderOptions = {},
+): UseAdminListLoaderReturn {
+  const loading = ref(options.initialLoading ?? false)
+  const loadError = ref('')
+  let loadSequence = 0
+
+  function beginLoad(): number {
+    const sequence = ++loadSequence
+    loading.value = true
+    loadError.value = ''
+    return sequence
+  }
+
+  function isStale(sequence: number): boolean {
+    return sequence !== loadSequence
+  }
+
+  function finishLoad(sequence: number): void {
+    if (sequence === loadSequence) loading.value = false
+  }
+
+  function failLoad(sequence: number, message: string): boolean {
+    if (sequence !== loadSequence) return false
+    loadError.value = message
+    return true
+  }
+
+  async function runLoad(
+    work: (ctx: AdminListLoadContext) => void | Promise<void>,
+    runOptions: AdminListRunLoadOptions = {},
+  ): Promise<boolean> {
+    const sequence = beginLoad()
+    const ctx: AdminListLoadContext = {
+      sequence,
+      isStale: () => isStale(sequence),
+    }
+    try {
+      await work(ctx)
+      if (isStale(sequence)) return false
+      return true
+    } catch (err) {
+      if (isStale(sequence)) return false
+      loadError.value = runOptions.onError?.(err) ?? defaultErrorMessage(err)
+      return false
+    } finally {
+      finishLoad(sequence)
+    }
+  }
+
+  function invalidate(): void {
+    loadSequence += 1
+    loading.value = false
+  }
+
+  return {
+    loading,
+    loadError,
+    beginLoad,
+    isStale,
+    finishLoad,
+    failLoad,
+    runLoad,
+    invalidate,
+  }
+}