@usethink/cf-admin-fe 0.1.1 → 0.2.8

package/recipes/list-page.snippet.ts

@@ -0,0 +1,141 @@
+/**
+ * 管理端列表页标准骨架（recipe / 文档，非运行时模块）。
+ *
+ * 组合：
+ * - useAdminListLoader — loading / loadError / 竞态安全序号
+ * - useTablePagination — page / limit / total / offset（分页 state 的 offset 是 number）
+ * - useTableSelection — 多选（可选）
+ * - buildAdminOffsetParams / applyAdminOffsetParams — **仅 string** limit+offset（URLSearchParams）
+ * - toErrorMessage — catch / onError 统一文案
+ * - copyWithToast — 复制选中行 / ID / 链接（可选）
+ * - checkAdminBatchLimit + buildBatchToast / resolveBatchToastType — 批量（可选）
+ *
+ * 不要把领域列定义、筛选表单、业务 API 放进套件。
+ *
+ * ── 分页查询：两种契约，勿混用 ──
+ *
+ * A) Query string / URLSearchParams（本 snippet 主示例）
+ *    buildAdminOffsetParams(page, limit) → { limit: string, offset: string }
+ *    参考：cf-lottery 平台审计 / 租户 / webhook / 兑换码
+ *
+ * B) 类型化 filter / JSON body：limit、offset 为 number
+ *    手写即可，例如：
+ *      { limit: limit.value, offset: (page.value - 1) * limit.value }
+ *    参考：cf-shop AdminBalance / Recharges / Vouchers
+ *    禁止把 B 强行改成 A 只为「用上 helper」。number helper 观察期：≥2 产品同形再提案。
+ *
+ * 真实 API 签名（务必与 src/utils/admin-query.ts 一致）：
+ *   buildAdminOffsetParams(page: number, limit: number, options?)
+ *   applyAdminOffsetParams(params: URLSearchParams, page: number, limit: number, options?)
+ *
+ * 批量上限：DEFAULT_ADMIN_BATCH_LIMIT = 20（auth 风格）。
+ * 后端若为 max(200)，必须 checkAdminBatchLimit(ids, { limit: 200, unit: '…' })。
+ * 详见 docs/002 §5.8（cf-shop 接线对照）。
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { ref, watch } from 'vue'
+import {
+  useAdminListLoader,
+  useTablePagination,
+  useTableSelection,
+  copyWithToast,
+} from '@usethink/cf-admin-fe/composables'
+import {
+  toErrorMessage,
+  buildAdminOffsetParams,
+  applyAdminOffsetParams,
+  checkAdminBatchLimit,
+  buildBatchToast,
+} from '@usethink/cf-admin-fe/utils'
+
+// —— 伪代码：复制到产品 views/admin/XxxView.vue 后接领域 API ——
+
+type Row = { id: string /* … */ }
+
+const items = ref<Row[]>([])
+const { page, limit, total, offset, setTotal } = useTablePagination()
+const {
+  selectedIds,
+  clearSelection,
+  selectedCount,
+} = useTableSelection(items, (row) => row.id)
+const { loading, loadError, runLoad } = useAdminListLoader()
+
+// 示例：产品侧 admin 请求（Bearer 或 cookie 由 useAdminRequest recipe 决定）
+declare function listDomainItems(params: Record<string, string>): Promise<{ items: Row[]; total: number }>
+declare function batchDisable(ids: string[]): Promise<{ success: number; failed: number }>
+declare function showToast(message: string, type?: 'success' | 'error' | 'info'): void
+declare function t(key: string, params?: Record<string, unknown>): string
+
+async function loadData() {
+  await runLoad(
+    async (ctx) => {
+      // ── 形态 A：string query（本示例）──
+      // 位置参数：page（1-based）、limit（每页条数）→ 字符串 limit/offset
+      const params = buildAdminOffsetParams(page.value, limit.value)
+      // 若已有 URLSearchParams（含业务筛选），再写入 limit/offset：
+      // const qs = new URLSearchParams({ status: filter.status })
+      // applyAdminOffsetParams(qs, page.value, limit.value)
+      const res = await listDomainItems(params)
+
+      // ── 形态 B：number body / 类型化 filter（勿用 buildAdminOffsetParams）──
+      // const res = await listDomainItems({
+      //   status: filter.status,
+      //   limit: limit.value,
+      //   offset: (page.value - 1) * limit.value,
+      // })
+
+      if (ctx.isStale()) return
+      items.value = res.items
+      setTotal(res.total)
+    },
+    {
+      onError: (err) => toErrorMessage(err, t('adminXxx.loadFailed')),
+    },
+  )
+}
+
+watch([page, limit], () => {
+  void loadData()
+})
+
+/** 复制选中 ID / 业务字段：成功与失败文案走产品 i18n */
+async function copySelected() {
+  if (selectedCount.value === 0) return
+  const idSet = new Set(selectedIds.value)
+  const rows = items.value.filter((r) => idSet.has(r.id))
+  await copyWithToast(rows.map((r) => r.id).join('\n'), {
+    successMessage: t('adminXxx.copySelectedSuccess', { count: rows.length }),
+    errorMessage: t('adminXxx.copySelectedFailed'),
+  })
+}
+
+async function runBatchDisable() {
+  const ids = [...selectedIds.value]
+  // 默认 limit=20（auth）。shop 类后端 max(200) 时改为：
+  // checkAdminBatchLimit(ids, { limit: 200, unit: t('adminXxx.unit') })
+  const limitCheck = checkAdminBatchLimit(ids, { unit: t('adminXxx.unit') })
+  if (!limitCheck.ok) {
+    showToast(limitCheck.message, 'error')
+    return
+  }
+  try {
+    const res = await batchDisable(ids)
+    const toast = buildBatchToast(res, {
+      mixed: t('adminXxx.batchMixed'), // 模板可含 {success}/{failed}/{count}
+      success: t('adminXxx.batchSuccess'),
+    })
+    showToast(toast.message, toast.type)
+    clearSelection()
+    await loadData()
+  } catch (e) {
+    showToast(toErrorMessage(e), 'error')
+  }
+}
+
+void offset
+void applyAdminOffsetParams
+void total
+void loadError
+void loading

package/recipes/main-styles.snippet.ts

@@ -0,0 +1,13 @@
+/**
+ * RECIPE — 样式入口。
+ *
+ * 方案 A（完整工具包 token + 基础样式）：
+ *   import '@usethink/cf-admin-fe/styles'
+ *
+ * 方案 B（产品已有与商城共享的 base.css token）：
+ *   // assets/admin.css
+ *   @import '@usethink/cf-admin-fe/styles/admin-primitives.css';
+ *
+ * 在应用根节点挂载一次：
+ *   <ToastContainer />
+ */

package/recipes/reexports/components.ts

@@ -0,0 +1,19 @@
+/**
+ * 轻量组件重新导出 — 产品中每个组件一个文件：
+ *
+ *   src/components/AdminPagination.ts
+ *   export { default } from '@usethink/cf-admin-fe/components/AdminPagination.vue'
+ *
+ * 使用深 `.vue` 路径可避免把整个包根目录拉进 Vitest。
+ */
+
+export { default as AdminPagination } from '@usethink/cf-admin-fe/components/AdminPagination.vue'
+export { default as AdminModal } from '@usethink/cf-admin-fe/components/AdminModal.vue'
+export { default as ConfirmDialog } from '@usethink/cf-admin-fe/components/ConfirmDialog.vue'
+export { default as ToastContainer } from '@usethink/cf-admin-fe/components/ToastContainer.vue'
+export { default as ConfigField } from '@usethink/cf-admin-fe/components/ConfigField.vue'
+export { default as AdminShell } from '@usethink/cf-admin-fe/components/AdminShell.vue'
+export { default as AdminLoginShell } from '@usethink/cf-admin-fe/components/AdminLoginShell.vue'
+export { default as AdminMetadataDetail } from '@usethink/cf-admin-fe/components/AdminMetadataDetail.vue'
+export type { AdminShellMenuItem } from '@usethink/cf-admin-fe/components'
+export type { AdminLogEntry } from '@usethink/cf-admin-fe/components'

package/recipes/reexports/composables.ts

@@ -0,0 +1,29 @@
+/**
+ * 将每个导出复制到各自的产品轻量文件中，使现有的
+ * `@/composables/useX` 导入无需大规模改写视图即可继续工作。
+ *
+ * 示例：`src/composables/useTablePagination.ts`
+ *   export { useTablePagination, type UseTablePaginationOptions, type UseTablePaginationReturn } from '@usethink/cf-admin-fe/composables'
+ */
+
+export {
+  useTablePagination,
+  type UseTablePaginationOptions,
+  type UseTablePaginationReturn,
+  useTableSelection,
+  type UseTableSelectionOptions,
+  useConfirmDialog,
+  type ConfirmOptionDef,
+  type ConfirmAskOptions,
+  type ConfirmResult,
+  useToast,
+  MAX_TOASTS,
+  type ToastType,
+  type ToastItem,
+  useAdminBatchOperation,
+  type AdminBatchOperationResult,
+  writeClipboardText,
+  copyText,
+  copyWithToast,
+  type CopyWithToastOptions,
+} from '@usethink/cf-admin-fe/composables'

package/recipes/reexports/utils.ts

@@ -0,0 +1,31 @@
+/**
+ * 产品侧再导出示例：`src/lib/csv-export.ts`、`body-scroll-lock.ts`、
+ * `composables/useFormat.ts`（日期 + 错误/批量助手等）。
+ */
+
+export {
+  formatDate,
+  toDateTimeLocalValue,
+  dateTimeLocalToIso,
+  isoToDateTimeLocal,
+  formatIpFingerprint,
+  downloadCsv,
+  safeCsvCell,
+  lockBodyScroll,
+  unlockBodyScroll,
+  isBodyScrollLocked,
+  normalizeCents,
+  formatCents,
+  parseYuanToCents,
+  createAdminUnauthorizedHandler,
+  decideAdminRouteAccess,
+  resolveAdminLoginRedirect,
+  toErrorMessage,
+  resolveBatchToastType,
+  buildBatchToast,
+  checkAdminBatchLimit,
+  DEFAULT_ADMIN_BATCH_LIMIT,
+  formatMetadata,
+  buildAdminOffsetParams,
+  applyAdminOffsetParams,
+} from '@usethink/cf-admin-fe/utils'

package/recipes/router-guard.snippet.ts

@@ -0,0 +1,32 @@
+/**
+ * RECIPE — 将 `beforeEach` 主体粘贴到产品 `src/router/index.ts`。
+ * 抽奖产品：先运行工具包门禁，再运行产品 onboarding / 平台 / 仿冒登录。
+ */
+import type { Router } from 'vue-router'
+import { decideAdminRouteAccess } from '@usethink/cf-admin-fe/utils'
+// import { readAdminToken } from '@/composables/useAdminAuth'
+
+export function installAdminRouteGuard(
+  router: Router,
+  readAdminToken: () => string,
+): void {
+  router.beforeEach((to) => {
+    const adminToken = readAdminToken()
+    const decision = decideAdminRouteAccess({
+      hasToken: !!adminToken,
+      requiresAuth: to.meta.requiresAuth as boolean | undefined,
+      requiresGuest: to.meta.requiresGuest as boolean | undefined,
+      fullPath: to.fullPath,
+    })
+
+    if (decision.type === 'login') {
+      return { name: 'AdminLogin', query: { redirect: decision.redirect }, replace: true }
+    }
+    if (decision.type === 'home') {
+      return { name: 'AdminDashboard', replace: true }
+    }
+
+    // 产品专属钩子写在这里（抽奖 onboarding、平台角色等）
+    return true
+  })
+}

package/recipes/useAdminAuth.cookie.ts

@@ -0,0 +1,29 @@
+/**
+ * RECIPE — cookie 管理员本地标志会话（cf-auth 风格）。
+ *
+ * 不是 Bearer token。HTTP 会话是 cookie；这里只是给路由守卫用的
+ * localStorage 标记。在模块作用域创建一次。
+ *
+ * PRODUCT：健康探测 /api/admin/health、登录、登出、允许列表 — 永远留在产品侧。
+ */
+import { createAdminFlagSession } from '@usethink/cf-admin-fe/composables'
+
+export const adminFlagSession = createAdminFlagSession({
+  storageKey: 'cf_auth_admin_ok', // PRODUCT：产品方自定义 key
+})
+
+export const readAdminFlag = () => adminFlagSession.readFlag()
+export const writeAdminFlag = (ok: boolean) => adminFlagSession.writeFlag(ok)
+
+export function useAdminAuth() {
+  return {
+    isLoggedIn: adminFlagSession.isLoggedIn,
+    loggedIn: adminFlagSession.loggedIn,
+    markLoggedIn: adminFlagSession.markLoggedIn,
+    /** 为仍使用 clearToken 命名的产品 API 保留的别名 */
+    clearToken: adminFlagSession.clearSession,
+    clearSession: adminFlagSession.clearSession,
+    writeFlag: adminFlagSession.writeFlag,
+    readFlag: adminFlagSession.readFlag,
+  }
+}

package/recipes/useAdminAuth.shop.ts

@@ -0,0 +1,29 @@
+/**
+ * RECIPE — shop 简易 Bearer 会话（单个 localStorage key + 8 小时 TTL）。
+ * 复制到 `src/composables/useAdminAuth.ts`，必要时调整 TOKEN_KEY。
+ *
+ * 抽奖多租户 / 仿冒登录：保留产品胶水代码；仅复用工具包中的
+ * `parseStoredAdminToken` + `DEFAULT_ADMIN_TOKEN_TTL_MS`。
+ */
+import { createAdminTokenSession } from '@usethink/cf-admin-fe/composables'
+
+const TOKEN_KEY = 'admin_token'
+
+const session = createAdminTokenSession({
+  storageKey: TOKEN_KEY,
+  ttlMs: 8 * 60 * 60 * 1000,
+})
+
+/** 供 setup 之外的 Router 守卫使用 */
+export function readAdminToken(): string {
+  return session.readToken()
+}
+
+export function useAdminAuth() {
+  return {
+    token: session.token,
+    isLoggedIn: session.isLoggedIn,
+    setToken: session.setToken,
+    clearToken: session.clearToken,
+  }
+}

package/recipes/useAdminRequest.cookie.ts

@@ -0,0 +1,36 @@
+/**
+ * RECIPE — cookie 会话 adminRequest（cf-auth / Better Auth 风格）。
+ *
+ * 工具包一等路径（与 Bearer 对称）：
+ * - createAdminFlagSession — 本地守卫标志（不是 HTTP cookie）
+ * - createAdminRequest({ credentials: 'include', onSuccess 修复, onUnauthorized 清除 })
+ *
+ * PRODUCT 仍负责：健康探测、登录/登出、OAuth、ADMIN_* 允许列表、领域路径。
+ */
+import {
+  createAdminFlagSession,
+  createAdminRequest,
+} from '@usethink/cf-admin-fe/composables'
+import { createAdminUnauthorizedHandler } from '@usethink/cf-admin-fe/utils'
+
+// PRODUCT: 本地管理员守卫标志的存储 key
+export const adminFlagSession = createAdminFlagSession({
+  storageKey: 'cf_auth_admin_ok',
+})
+
+const handleUnauthorized = createAdminUnauthorizedHandler({
+  clearSession: () => adminFlagSession.clearSession(),
+  loginPath: '/admin/login',
+  defaultRedirectPath: '/admin',
+})
+
+export const adminRequest = createAdminRequest({
+  credentials: 'include',
+  resultMode: 'ok-envelope',
+  errorField: 'message',
+  onUnauthorized: handleUnauthorized,
+  // 任何管理员调用成功后修复缺失的标志（会话 cookie 已有效）
+  onSuccess: () => {
+    if (!adminFlagSession.readFlag()) adminFlagSession.markLoggedIn()
+  },
+})

package/recipes/useAdminRequest.ts

@@ -0,0 +1,37 @@
+/**
+ * RECIPE — 可注入的管理员 fetch（抽奖风格 ok-envelope）。
+ *
+ * Shop 风格：使用 `resultMode: 'http-ok'`、`errorField: 'error'`，并在领域
+ * API 方法中逐次调用传入 `token`（参见 cf-shop `api/admin.ts`）。
+ *
+ * 复制到 `src/composables/useAdminRequest.ts`。
+ */
+import {
+  createAdminRequest,
+  type AdminRequestFn,
+} from '@usethink/cf-admin-fe/composables'
+import { createAdminUnauthorizedHandler } from '@usethink/cf-admin-fe/utils'
+import { readAdminToken, useAdminAuth } from './useAdminAuth'
+
+// 接入产品会话清理 — shop 通常只删除 admin_token；
+// 抽奖产品可能调用完整业务会话清空。
+function clearProductSession() {
+  try {
+    useAdminAuth().clearToken()
+  } catch {
+    /* 忽略 */
+  }
+}
+
+const handleUnauthorized = createAdminUnauthorizedHandler({
+  clearSession: clearProductSession,
+  loginPath: '/admin/login',
+  defaultRedirectPath: '/admin',
+})
+
+export const adminRequest: AdminRequestFn = createAdminRequest({
+  getToken: () => readAdminToken(),
+  resultMode: 'ok-envelope',
+  errorField: 'message',
+  onUnauthorized: handleUnauthorized,
+})

package/src/components/AdminLoginShell.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+/**
+ * 仅提供管理端登录页的展示性外壳。
+ * 认证流程（token / 密码 / OTP / OAuth）由业务产品自行实现。
+ */
+defineProps<{
+  /** #title 插槽为空时的回退标题 */
+  title?: string
+  /** #subtitle 插槽为空时的回退副标题 */
+  subtitle?: string
+}>()
+</script>
+
+<template>
+  <div class="admin-login">
+    <div class="login-card">
+      <div v-if="$slots.title || $slots.subtitle || title || subtitle" class="login-header">
+        <slot name="title">
+          <h1 v-if="title" class="login-title">{{ title }}</h1>
+        </slot>
+        <slot name="subtitle">
+          <p v-if="subtitle" class="login-subtitle">{{ subtitle }}</p>
+        </slot>
+      </div>
+      <slot />
+      <div v-if="$slots.footer" class="login-footer">
+        <slot name="footer" />
+      </div>
+    </div>
+  </div>
+</template>

package/src/components/AdminMetadataDetail.vue

@@ -0,0 +1,121 @@
+<template>
+  <AdminModal v-model="innerVisible" :title="$t('adminLogs.metadataTitle')" max-width="640px">
+    <div v-if="log" class="detail-box">
+      <div class="detail-section">
+        <div class="detail-title">{{ $t('adminLogs.basicInfo') }}</div>
+        <div class="detail-row">
+          <span class="detail-label">{{ $t('adminLogs.labelAction') }}</span>
+          <span class="detail-value">{{ log.action }}</span>
+        </div>
+        <div class="detail-row">
+          <span class="detail-label">{{ $t('adminLogs.labelTargetType') }}</span>
+          <span class="detail-value">{{ log.targetType }}</span>
+        </div>
+        <div class="detail-row">
+          <span class="detail-label">{{ $t('adminLogs.labelTargetId') }}</span>
+          <span class="detail-value">{{ log.targetId }}</span>
+        </div>
+        <div class="detail-row">
+          <span class="detail-label">{{ $t('adminLogs.labelTime') }}</span>
+          <span class="detail-value">{{ formatDate(log.createdAt) }}</span>
+        </div>
+        <div class="detail-row">
+          <span class="detail-label">{{ $t('adminLogs.labelIpFingerprint') }}</span>
+          <span class="detail-value">{{ log.ipHash || '-' }}</span>
+        </div>
+      </div>
+      <div v-if="log.metadata && Object.keys(log.metadata).length > 0" class="detail-section">
+        <div class="detail-title">{{ $t('adminLogs.labelMetadata') }}</div>
+        <pre class="detail-json">{{ formatMetadata(log.metadata) }}</pre>
+      </div>
+    </div>
+  </AdminModal>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import AdminModal from './AdminModal.vue'
+import { formatDate } from '../utils/datetime'
+import { formatMetadata } from '../utils/format-metadata'
+
+export interface AdminLogEntry {
+  action: string
+  targetType: string
+  targetId: string
+  createdAt: string
+  ipHash?: string | null
+  metadata?: Record<string, unknown> | null
+}
+
+const props = withDefaults(defineProps<{
+  modelValue: boolean
+  log: AdminLogEntry | null
+}>(), {
+  modelValue: false,
+  log: null,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+}>()
+
+const innerVisible = ref(false)
+
+watch(() => props.modelValue, (val) => {
+  innerVisible.value = val
+}, { immediate: true })
+
+watch(innerVisible, (val, wasVisible) => {
+  if (!val && wasVisible && props.modelValue) {
+    emit('update:modelValue', false)
+  }
+})
+</script>
+
+<style scoped>
+.detail-box {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.detail-section {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.detail-title {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--tg-hint, #9aa4b2);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+.detail-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  font-size: 13px;
+  line-height: 1.55;
+}
+.detail-label {
+  flex-shrink: 0;
+  width: 100px;
+  color: var(--tg-hint, #9aa4b2);
+}
+.detail-value {
+  color: var(--tg-text, #f0f2f5);
+  word-break: break-all;
+}
+.detail-json {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: var(--r-sm, 6px);
+  background: rgba(0, 0, 0, 0.2);
+  font-size: 12px;
+  line-height: 1.55;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  word-break: break-all;
+  color: var(--tg-text, #f0f2f5);
+}
+</style>