@usethink/cf-admin-fe 0.1.0 → 0.2.6

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@usethink/cf-admin-fe",
-  "version": "0.1.0",
-  "description": "Vue 3 frontend admin kit for CF product family \u2014 composables, shell components, design tokens (FE only; not cf-core)",
+  "version": "0.2.6",
+  "description": "Vue 3 frontend admin kit for CF product family — composables, shell, ConfigField, list loader, login chrome, request/token/raw factories, error/batch helpers, system-config engine, nav helpers, i18n seeds, recipes (FE only; not cf-core)",
   "type": "module",
   "private": false,
   "files": [
     "src",
     "dist",
-    "README.md"
+    "recipes",
+    "docs",
+    "README.md",
+    "LICENSE"
   ],
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -26,14 +29,32 @@
       "types": "./src/components/index.ts",
       "import": "./src/components/index.ts"
     },
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "import": "./src/utils/index.ts"
+    },
+    "./types": {
+      "types": "./src/types/index.ts",
+      "import": "./src/types/index.ts"
+    },
+    "./i18n": {
+      "types": "./src/i18n/index.ts",
+      "import": "./src/i18n/index.ts"
+    },
     "./styles": "./src/styles/index.css",
     "./styles/tokens.css": "./src/styles/tokens.css",
     "./styles/admin-primitives.css": "./src/styles/admin-primitives.css",
+    "./styles/login-primitives.css": "./src/styles/login-primitives.css",
     "./package.json": "./package.json",
     "./components/AdminPagination.vue": "./src/components/AdminPagination.vue",
     "./components/AdminModal.vue": "./src/components/AdminModal.vue",
     "./components/ConfirmDialog.vue": "./src/components/ConfirmDialog.vue",
-    "./components/ToastContainer.vue": "./src/components/ToastContainer.vue"
+    "./components/ToastContainer.vue": "./src/components/ToastContainer.vue",
+    "./components/ConfigField.vue": "./src/components/ConfigField.vue",
+    "./components/AdminShell.vue": "./src/components/AdminShell.vue",
+    "./components/AdminLoginShell.vue": "./src/components/AdminLoginShell.vue",
+    "./recipes/*": "./recipes/*",
+    "./components/AdminMetadataDetail.vue": "./src/components/AdminMetadataDetail.vue"
   },
   "sideEffects": [
     "**/*.css"
@@ -47,6 +68,7 @@
     }
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "@vitejs/plugin-vue": "^5.2.1",
     "typescript": "^5.7.2",
     "vite": "^6.0.0",
@@ -55,10 +77,12 @@
     "vue-tsc": "^2.1.10"
   },
   "scripts": {
-    "type-check": "tsc --noEmit && vue-tsc --noEmit -p tsconfig.json",
+    "type-check": "tsc --noEmit -p tsconfig.build.json && vue-tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "build": "tsc -p tsconfig.build.json"
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "clean": "node scripts/clean-dist.mjs"
   },
   "keywords": [
     "admin",

package/recipes/AdminLayout.vue

@@ -0,0 +1,73 @@
+<template>
+  <!--
+    RECIPE — 产品 AdminLayout 外壳。
+    将 menuItems + brand 替换为产品的 i18n / 配置。
+    可选插槽：#nav-extra（平台链接）、#banner（仿冒登录）、#header-actions（语言，在顶栏用户信息左侧）。
+    用户头像/名称/退出默认在顶栏右上；侧栏底默认不占位（菜单多时省高）。
+    若需自定义侧栏底：#sidebar-footer（有内容才渲染）。
+  -->
+  <AdminShell
+    :brand="brand"
+    :menu-items="shellMenuItems"
+    :current-name="currentName ?? null"
+    :page-title="pageTitle"
+    :user-name="t('adminLayout.admin')"
+    @logout="handleLogout"
+    @navigate="onNavClick"
+  >
+    <template #header-actions>
+      <!-- 产品：语言选择、环境徽标等（出现在用户信息与退出左侧） -->
+      <slot name="header-actions" />
+    </template>
+
+    <RouterView v-slot="{ Component }">
+      <transition name="admin-fade" mode="out-in">
+        <component :is="Component" />
+      </transition>
+    </RouterView>
+  </AdminShell>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { useI18n } from 'vue-i18n'
+import { AdminShell, type AdminShellMenuItem } from '@usethink/cf-admin-fe/components'
+import { useAdminAuth } from '@/composables/useAdminAuth'
+import { useToast } from '@/composables/useToast'
+
+const route = useRoute()
+const router = useRouter()
+const { t } = useI18n()
+const { clearToken } = useAdminAuth()
+const { showToast } = useToast()
+
+/** PRODUCT: 品牌标题 */
+const brand = computed(() => t('adminLayout.title'))
+
+/** PRODUCT: 替换为真实菜单 */
+const menuItems = computed(() => [
+  { name: 'AdminDashboard', to: '/admin', label: t('adminLayout.title'), icon: '📊' },
+  // { name: 'AdminOrders', to: '/admin/orders', label: '…', icon: '📋' },
+])
+
+const shellMenuItems = computed<AdminShellMenuItem[]>(() => menuItems.value)
+
+const currentName = computed(() => route.name as string | undefined)
+
+const pageTitle = computed(() => {
+  const item = menuItems.value.find((m) => m.name === currentName.value)
+  return item?.label || t('adminLayout.title')
+})
+
+function onNavClick(to: string) {
+  if (route.fullPath === to) return
+  router.push(to)
+}
+
+function handleLogout() {
+  clearToken()
+  showToast(t('adminLayout.loggedOut'), 'success')
+  router.replace('/admin/login')
+}
+</script>

package/recipes/README.md

@@ -0,0 +1,130 @@
+# Recipes — 复制到新的 CF 管理后台前端
+
+这些文件是**起点模板**，不是运行时导入。将它们复制（或重新导出）到你的产品 `src/` 目录下，然后补齐产品专属部分（菜单、领域 API 方法、登录 UI）。
+
+**完整用法、注意事项、能力榨干清单：** 见 [`docs/002_cf-admin-fe使用说明书与注意事项.md`](../docs/002_cf-admin-fe使用说明书与注意事项.md)。
+
+## 推荐复制顺序
+
+| 步骤 | Recipe | 产品路径（示例） |
+|---|---|---|
+| 1 | `reexports/` | `src/composables/*`、`src/components/*`、`src/lib/*` |
+| 2a | **Bearer：** `useAdminAuth.shop.ts` | `src/composables/useAdminAuth.ts` |
+| 2b | **Cookie：** `useAdminAuth.cookie.ts` | 同上 — 使用 `createAdminFlagSession` |
+| 3a | **Bearer：** `useAdminRequest.ts` | `src/composables/useAdminRequest.ts`（或 `api/admin.ts`） |
+| 3b | **Cookie：** `useAdminRequest.cookie.ts` | `credentials: 'include'` + `onSuccess` 标志修复 |
+| 4 | `AdminLayout.vue` | `src/views/AdminLayout.vue` |
+| 5 | `router-guard.snippet.ts` | 粘贴到 `src/router/index.ts`（Bearer 用 `hasToken`；cookie 产品可在**产品内**添加健康探测） |
+| 6 | `i18n-merge.snippet.ts` | 粘贴到 `src/i18n/index.ts` |
+| 7 | 样式 | `import '@usethink/cf-admin-fe/styles'` **或** `@import` 基础样式（+ 登录 CSS） |
+| 8 | 应用外壳 | 在应用根节点挂载一次 `ToastContainer` |
+| 9 | 登录 | 用 `AdminLoginShell` 包裹**产品**表单；用 `resolveAdminLoginRedirect` 处理 `?redirect=` |
+| 10 | 列表页 | 见 `list-page.snippet.ts`：`useAdminListLoader` + 分页/多选 + `toErrorMessage` / `copyWithToast`；**先确认**后端是 string query 还是 number body offset |
+
+### 两种一等会话模型
+
+| 模型 | 工具包工厂 | 请求 | 实际参考 |
+|---|---|---|---|
+| Bearer JWT | `createAdminTokenSession` | `getToken` + 可选 Bearer | **cf-shop**、**cf-lottery** |
+| Cookie + 本地标志 | `createAdminFlagSession` | `credentials: 'include'`，可选 `onSuccess` 修复 | **cf-auth** |
+
+Cookie 产品**不应**被强制套用 token TTL / 密码表单。它们的特性（OAuth、健康探测、登出 cookie）留在产品侧；工具包只提供标志存储 + 请求工厂 + 外壳 UI。
+
+## 不要放入工具包 / 不要按领域复制
+
+- 领域页面（`views/admin/*` 业务 CRUD）
+- 领域 API 方法目录
+- 抽奖仿冒登录 / 平台角色（产品 L3）
+- Better Auth / OAuth / PKCE **流程**和允许列表策略（产品）
+- 多币种 / 订单状态映射
+- 通用组件（日期选择器、级联选择、树、富文本）— 产品自选轻量库
+- 一次性产品辅助函数“以防将来共享”
+
+## 导入风格
+
+产品重新导出时优先使用**子路径**导入，这样 Vitest/node 不会解析根 SFC barrel 文件：
+
+```ts
+from '@usethink/cf-admin-fe/composables'
+from '@usethink/cf-admin-fe/utils'
+from '@usethink/cf-admin-fe/components/ConfigField.vue'
+from '@usethink/cf-admin-fe/i18n'
+```
+
+## 错误 / 批量纯辅助函数（0.2.6+）
+
+```ts
+import {
+  toErrorMessage,
+  buildBatchToast,
+  resolveBatchToastType,
+  checkAdminBatchLimit,
+} from '@usethink/cf-admin-fe/utils'
+
+// catch
+showToast(toErrorMessage(e), 'error')
+// 列表 loader
+onError: (err) => toErrorMessage(err, t('…loadFailed'))
+
+// 服务端批量响应 { success, failed }
+const toast = buildBatchToast(res, {
+  mixed: '完成：成功 {success}，失败 {failed}',
+  success: '已处理 {count} 条',
+})
+showToast(toast.message, toast.type)
+
+// 或保留 vue-i18n 文案，只复用成功/失败色调：
+showToast(t('…', counts), resolveBatchToastType(counts))
+
+// POST 前多选上限
+// 默认 20 = auth / docs 风格；后端若 z.array.max(200) 必须传 limit: 200
+const limitCheck = checkAdminBatchLimit(ids, { unit: '人' })
+// shop 示例：checkAdminBatchLimit(ids, { limit: 200, unit: '单' })
+if (!limitCheck.ok) {
+  showToast(limitCheck.message, 'error')
+  return
+}
+```
+
+不要把业务成功文案或硬删除策略用语放进套件——只放纯形状。  
+**`limit` 必须与后端单次批量 max 一致**，默认 20 不是「所有 CF 产品的真理」。
+
+## 列表 limit / offset（string vs number）
+
+| 形态 | 工具 | 参考产品 |
+|---|---|---|
+| `URLSearchParams` / query：`limit`、`offset` 为 **字符串** | `buildAdminOffsetParams(page, limit)` 或 `applyAdminOffsetParams` | cf-lottery 平台审计、租户、webhook、兑换码 |
+| 类型化 filter / body：`limit`、`offset` 为 **数字** | **手写** `(page - 1) * limit`；**不要**套 string helper | cf-shop 余额 / 充值 / 代金券等 |
+| Cursor | 产品自管 | shop 部分订单/日志 |
+
+`buildAdminOffsetParams` 的返回值是 `{ limit: string; offset: string }`，塞进需要 `number` 的 TypeScript filter 会类型错误或静默把数字变成字符串——属于误用，不是「再抽一个兼容层就能糊弄过去」。
+
+完整对照与升级清单：`docs/002` **§5.8**。
+
+## 复制 + toast（0.2.6+）
+
+```ts
+import { copyWithToast } from '@usethink/cf-admin-fe/composables'
+// 或产品 reexport：@/composables/useClipboard
+
+const ok = await copyWithToast(text, {
+  successMessage: t('…copySuccess'),
+  errorMessage: t('…copyFailed'),
+})
+if (ok) {
+  // 可选：关弹层、清选中
+}
+```
+
+- **`copyWithToast`**：剪贴板 + 全局 toast（管理端列表/详情主路径）
+- **`copyText(text, event)`**：按钮内 ✅/❌（前台交付明细等，不抢 toast）
+- **`writeClipboardText`**：仅写入，由调用方自管反馈（例如创建成功后静默复制链接）
+
+## 列表页骨架
+
+见 [`list-page.snippet.ts`](./list-page.snippet.ts)（含形态 A/B 注释与 batch `limit` 提示）。
+
+## 审计元数据
+
+- 纯函数：`formatMetadata`（旧页、自研详情 markup 足够时只用这个）
+- 组件：`AdminMetadataDetail` — **新审计详情页优先**；已有产品详情 DOM 的旧页 **不必** 为对齐而全量迁移（见 docs/001 R4 尾巴、docs/002 步骤 11）

package/recipes/i18n-merge.snippet.ts

@@ -0,0 +1,29 @@
+/**
+ * RECIPE — 合并工具包消息种子，使 ConfigField / Pagination / Confirm 在新产品
+ * 上不会显示原始 key。冲突时产品宿主 key 始终优先。
+ *
+ * 示例（vue-i18n）：
+ *
+ *   import { mergeAdminKitMessages } from '@usethink/cf-admin-fe/i18n'
+ *   import zhHost from './zh-CN'
+ *   import enHost from './en'
+ *
+ *   const i18n = createI18n({
+ *     locale: 'zh-CN',
+ *     messages: {
+ *       'zh-CN': mergeAdminKitMessages(zhHost, 'zh-CN'),
+ *       en: mergeAdminKitMessages(enHost, 'en'),
+ *     },
+ *   })
+ */
+import { mergeAdminKitMessages } from '@usethink/cf-admin-fe/i18n'
+
+export function withAdminKitI18n<T extends Record<string, unknown>>(
+  zhHost: T,
+  enHost: T,
+): { 'zh-CN': T; en: T } {
+  return {
+    'zh-CN': mergeAdminKitMessages(zhHost, 'zh-CN'),
+    en: mergeAdminKitMessages(enHost, 'en'),
+  }
+}

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,
+  }
+}