@usethink/cf-admin-fe 0.1.0 → 0.2.6

package/src/composables/useAdminSidebar.ts

@@ -0,0 +1,68 @@
+/**
+ * 响应式后台侧边栏状态（1024px 以下显示汉堡菜单）。
+ * 布局骨架由产品方维护；这里只负责媒体查询与打开状态。
+ */
+import { onMounted, onUnmounted, ref, type Ref } from 'vue'
+
+export type UseAdminSidebarOptions = {
+  /** matchMedia 查询条件；默认 `(max-width: 1023px)` */
+  query?: string
+}
+
+export type UseAdminSidebarReturn = {
+  isMobile: Ref<boolean>
+  sidebarOpen: Ref<boolean>
+  toggleSidebar: () => void
+  closeSidebar: () => void
+  openSidebar: () => void
+}
+
+export function useAdminSidebar(
+  options: UseAdminSidebarOptions = {},
+): UseAdminSidebarReturn {
+  const query = options.query ?? '(max-width: 1023px)'
+  const isMobile = ref(false)
+  const sidebarOpen = ref(false)
+
+  let mql: MediaQueryList | null = null
+
+  function onMqChange(e: MediaQueryListEvent | MediaQueryList) {
+    isMobile.value = e.matches
+    if (!e.matches) {
+      // 桌面端：强制关闭遮罩模式，保证固定侧边栏的 CSS 保持干净
+      sidebarOpen.value = false
+    }
+  }
+
+  function toggleSidebar() {
+    sidebarOpen.value = !sidebarOpen.value
+  }
+
+  function closeSidebar() {
+    sidebarOpen.value = false
+  }
+
+  function openSidebar() {
+    sidebarOpen.value = true
+  }
+
+  onMounted(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return
+    mql = window.matchMedia(query)
+    onMqChange(mql)
+    mql.addEventListener('change', onMqChange)
+  })
+
+  onUnmounted(() => {
+    mql?.removeEventListener('change', onMqChange)
+    mql = null
+  })
+
+  return {
+    isMobile,
+    sidebarOpen,
+    toggleSidebar,
+    closeSidebar,
+    openSidebar,
+  }
+}

package/src/composables/useClipboard.ts

@@ -1,8 +1,10 @@
-/** 剪贴板工具：一键复制文本到剪贴板，带按钮视觉反馈 */
+/** 剪贴板工具：一键复制；按钮视觉反馈；或成功/失败 toast（管理端列表/详情常用） */
+
+import { useToast, type ToastType } from './useToast'
 
 const FEEDBACK_MS = 1500
 
-/** 复制文本，更新按钮文字反馈 */
+/** 写入剪贴板（无 UI 反馈） */
 export async function writeClipboardText(text: string): Promise<void> {
   if (navigator.clipboard?.writeText) {
     await navigator.clipboard.writeText(text)
@@ -21,6 +23,43 @@ export async function writeClipboardText(text: string): Promise<void> {
   if (!copied) throw new Error('Clipboard copy failed')
 }
 
+/**
+ * 复制到剪贴板，并用全局 toast 提示成功/失败。
+ * 与 `copyText`（按钮内 ✅/❌ 反馈）互补：管理端列表/详情更常用 toast。
+ *
+ * 文案一律由产品传入（i18n），套件不内置默认中英文案。
+ *
+ * @returns 是否复制成功（调用方可在成功后关弹层等）
+ */
+export type CopyWithToastOptions = {
+  /** 成功 toast 文案（由产品 i18n 提供） */
+  successMessage: string
+  /** 失败 toast 文案（由产品 i18n 提供） */
+  errorMessage: string
+  /**
+   * 自定义 toast 出口；默认 `useToast().showToast`。
+   * 测试或未挂 ToastContainer 的场景可注入。
+   */
+  showToast?: (message: string, type: ToastType) => void
+}
+
+export async function copyWithToast(
+  text: string,
+  options: CopyWithToastOptions,
+): Promise<boolean> {
+  const toast = options.showToast ?? useToast().showToast
+
+  try {
+    await writeClipboardText(text)
+    toast(options.successMessage, 'success')
+    return true
+  } catch {
+    toast(options.errorMessage, 'error')
+    return false
+  }
+}
+
+/** 复制文本，更新触发按钮的文字反馈（前台交付明细等） */
 export function copyText(text: string, e: Event) {
   writeClipboardText(text).then(() => {
     feedback(e, '✅')

package/src/composables/useConfirmDialog.ts

@@ -1,3 +1,7 @@
+/**
+ * 确认弹窗状态机：与 `<ConfirmDialog />` 配对使用。
+ * 支持可选勾选项与 `requirePhrase` 键入确认。
+ */
 import { ref, watch } from 'vue'
 
 export type ConfirmOptionDef = {
@@ -5,7 +9,7 @@ export type ConfirmOptionDef = {
   label: string
   /** 补充说明，显示在 label 下方 */
   hint?: string
-  /** 默认 false */
+  /** 默认是否勾选；默认 false */
   defaultChecked?: boolean
 }
 
@@ -14,6 +18,11 @@ export type ConfirmAskOptions = {
   danger?: boolean
   /** 可选勾选项，默认全部未勾选；打开弹窗时按 defaultChecked 重置 */
   options?: ConfirmOptionDef[]
+  /**
+   * 须键入的确认短语（如硬删除的 "DELETE"）。
+   * 有值时确认按钮在输入完全匹配前禁用；与服务端 confirm 字面量对齐。
+   */
+  requirePhrase?: string
 }
 
 export type ConfirmResult = {
@@ -27,6 +36,8 @@ export function useConfirmDialog() {
   const confirmMessage = ref('')
   const confirmOptionDefs = ref<ConfirmOptionDef[]>([])
   const confirmOptionValues = ref<Record<string, boolean>>({})
+  /** 非空则弹窗要求键入该短语 */
+  const confirmRequirePhrase = ref<string | null>(null)
   let confirmCallback: ((result: ConfirmResult) => void) | null = null
 
   function snapshotOptions(): Record<string, boolean> {
@@ -47,10 +58,13 @@ export function useConfirmDialog() {
 
   /**
    * 简单确认：仅返回 boolean（兼容旧调用）。
-   * 需要读取 Checkbox 时请用 askConfirmWithOptions。
+   * 需要 Checkbox / requirePhrase 时请用 askConfirmWithOptions，或把 options 作为第二参传入。
    */
-  function askConfirm(message: string): Promise<boolean> {
-    return askConfirmWithOptions(message).then((r) => r.confirmed)
+  function askConfirm(
+    message: string,
+    options: ConfirmAskOptions = {},
+  ): Promise<boolean> {
+    return askConfirmWithOptions(message, options).then((r) => r.confirmed)
   }
 
   function askConfirmWithOptions(
@@ -62,6 +76,10 @@ export function useConfirmDialog() {
     const defs = options.options ?? []
     confirmOptionDefs.value = defs
     resetOptionValues(defs)
+    confirmRequirePhrase.value =
+      typeof options.requirePhrase === 'string' && options.requirePhrase.length > 0
+        ? options.requirePhrase
+        : null
     confirmVisible.value = true
     return new Promise((resolve) => {
       confirmCallback = (result) => resolve(result)
@@ -88,6 +106,9 @@ export function useConfirmDialog() {
       confirmCallback = null
       callback({ confirmed: false, options: snapshotOptions() })
     }
+    if (!visible) {
+      confirmRequirePhrase.value = null
+    }
   })
 
   return {
@@ -95,6 +116,7 @@ export function useConfirmDialog() {
     confirmMessage,
     confirmOptionDefs,
     confirmOptionValues,
+    confirmRequirePhrase,
     askConfirm,
     askConfirmWithOptions,
     onConfirm,

package/src/composables/useNow.ts

@@ -0,0 +1,38 @@
+/**
+ * 共享的当前时间 composable
+ *
+ * 多个组件需要展示倒计时/实时时钟时，
+ * 共享同一个 60 秒定时器，避免 N 个组件创建 N 个 setInterval。
+ *
+ * 使用 ref 计数模式：仅当至少一个组件订阅时才启动定时器，
+ * 所有组件卸载后自动清理。
+ */
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const nowMs = ref(Date.now())
+let timer: number | undefined
+let subscriberCount = 0
+
+export function useNow() {
+  onMounted(() => {
+    subscriberCount++
+    if (subscriberCount === 1) {
+      timer = window.setInterval(() => {
+        nowMs.value = Date.now()
+      }, 60000)
+    }
+  })
+
+  onUnmounted(() => {
+    subscriberCount--
+    if (subscriberCount <= 0) {
+      subscriberCount = 0
+      if (timer !== undefined) {
+        window.clearInterval(timer)
+        timer = undefined
+      }
+    }
+  })
+
+  return { nowMs }
+}

package/src/composables/useTablePagination.ts

@@ -1,7 +1,13 @@
+/**
+ * 管理端表格 offset 分页状态（page / limit / total）。
+ * 列表请求与列定义仍由产品页面负责。
+ */
 import { ref, computed, type Ref, type ComputedRef } from 'vue'
 
 export interface UseTablePaginationOptions {
+  /** 初始页码；默认 1 */
   initialPage?: number
+  /** 初始每页条数；默认 20 */
   initialLimit?: number
 }
 

package/src/composables/useTableSelection.ts

@@ -5,8 +5,8 @@ export interface UseTableSelectionOptions<T> {
 }
 
 /**
- * Accepts Ref or ComputedRef of row lists (MaybeRef) so product views can pass
- * filtered computed tables without dual-package Ref assignability friction.
+ * 接受行列表的 Ref 或 ComputedRef（MaybeRef），使产品视图可以直接传入
+ * 过滤后的 computed 表格，避免双包 Ref 类型赋值的摩擦。
  */
 export function useTableSelection<T>(
   rows: MaybeRef<T[]>,

package/src/composables/useToast.ts

@@ -1,3 +1,6 @@
+/**
+ * 全局 toast 队列（模块单例）。应用根节点挂一次 `<ToastContainer />` 即可。
+ */
 import { ref } from 'vue'
 
 export type ToastType = 'success' | 'error' | 'info'
@@ -7,7 +10,7 @@ export type ToastItem = { id: number; message: string; type: ToastType }
 const toasts = ref<ToastItem[]>([])
 let count = 0
 
-/** Max stacked toasts; older entries drop when exceeded (lottery hardening). */
+/** 最多叠加显示的 toast 数；超过后丢弃较早的条目（抽奖加固）。 */
 export const MAX_TOASTS = 5
 
 function showToast(message: string, type: ToastType = 'info', duration = 3000) {

package/src/env.d.ts

@@ -12,8 +12,8 @@ declare module '*.css' {
 }
 
 /**
- * Host apps (shop/lottery/auth) inject vue-i18n; kit components call `$t('pagination.*')` etc.
- * Declared on both entry points so vue-tsc consumers share one augmentation path.
+ * 宿主应用（shop / lottery / auth）注入 vue-i18n；套件组件会调用 `$t('pagination.*')` 等。
+ * 在两个入口都声明，便于 vue-tsc 消费方共用同一处类型增强。
  */
 declare module 'vue' {
   interface ComponentCustomProperties {

package/src/i18n/index.ts

@@ -0,0 +1,8 @@
+export {
+  adminKitMessages,
+  adminKitMessagesZhCN,
+  adminKitMessagesEn,
+  mergeAdminKitMessages,
+  type AdminKitLocale,
+  type AdminKitMessageTree,
+} from './kit-messages'

package/src/i18n/kit-messages.ts

@@ -0,0 +1,297 @@
+/**
+ * kit 组件所需的最小 i18n 消息集。
+ * 宿主应用应将它们深度合并到本地化消息中，使批量复制的
+ * 管理端不缺 `pagination.*` / `confirm.*` / ConfigField 键。
+ *
+ * 产品专属菜单（`adminLayout.menu*`）保留在产品侧。
+ */
+
+export type AdminKitLocale = 'zh-CN' | 'en'
+
+/** 与 vue-i18n `messages` 兼容的嵌套消息树 */
+export type AdminKitMessageTree = {
+  pagination: Record<string, string>
+  confirm: Record<string, string>
+  adminModal: Record<string, string>
+  adminConfigField: Record<string, string>
+  adminLayout: Record<string, string>
+  adminLogs: Record<string, string>
+  adminConfig: Record<string, string>
+}
+
+export const adminKitMessagesZhCN: AdminKitMessageTree = {
+  pagination: {
+    listLabel: '分页',
+    total: '共 {total} 条',
+    perPage: '每页',
+    perPageUnit: '条',
+    prev: '上一页',
+    next: '下一页',
+    prevLabel: '上一页',
+    nextLabel: '下一页',
+    page: '第 {page} 页',
+    pageOf: '{page} / {total}',
+    jumpTo: '跳至',
+    jumpPage: '页',
+    jump: '跳转',
+    jumpLabel: '页码',
+  },
+  confirm: {
+    confirm: '确认',
+    cancel: '取消',
+    delete: '删除选项',
+    requirePhrase: '请键入 {phrase} 以确认',
+  },
+  adminModal: {
+    title: '对话框',
+    close: '关闭',
+  },
+  adminConfigField: {
+    reset: '重置',
+    saving: '保存中…',
+    range: '范围 {min} ~ {max}',
+    yuanUnit: '元',
+    hint: '按元编辑，入库为分',
+    override: '已配置，留空不修改',
+    notConfigured: '未配置',
+    enumEmptyHint: '至少保留一项',
+    unlimited: '不限',
+    placeholder: '请输入有效金额',
+    minError: '不能小于 {min}',
+    maxError: '不能大于 {max}',
+  },
+  adminLayout: {
+    logout: '退出',
+    toggleSidebar: '菜单',
+    admin: '管理员',
+    title: '管理后台',
+    loggedOut: '已退出登录',
+  },
+  adminLogs: {
+    title: '操作日志',
+    search: '搜索操作类型',
+    targetSearch: '搜索目标类型',
+    targetSearchPlaceholder: '搜索目标',
+    searchBtn: '查询',
+    clearing: '清除中…',
+    clearAll: '清除全部日志',
+    allLogs: '全部日志',
+    clearFilters: '清空筛选条件',
+    reload: '重新加载',
+    selectedCount: '当前页已选 {count} 条日志',
+    clearSelection: '清空选择',
+    copySelected: '复制已选',
+    exportSelectedCsv: '导出已选 CSV',
+    batchDelete: '批量删除（{count}）',
+    deleting: '删除中…',
+    colTime: '时间',
+    colOperator: '操作人',
+    colAction: '操作类型',
+    colTarget: '目标类型',
+    colTargetId: '目标标识',
+    colIpFingerprint: 'IP 标识',
+    colMetadata: '元数据',
+    colDetail: '详情',
+    noData: '暂无日志',
+    viewMetadata: '查看',
+    tableScrollArea: '日志表格滚动区域',
+    tableLabel: '管理日志列表',
+    selectAllPage: '选择当前页日志',
+    selectRow: '选择日志 {log}',
+    metadataTitle: '日志详情',
+    basicInfo: '基本信息',
+    labelAction: '操作',
+    labelTargetType: '目标类型',
+    labelTargetId: '目标 ID',
+    labelTime: '时间',
+    labelIpFingerprint: 'IP 标识（哈希）',
+    labelMetadata: '元数据',
+    presetOrder: '订单处理',
+    presetOrderDesc: '付款确认、取消、补偿备注',
+    presetStock: '库存维护',
+    presetStockDesc: '导入、启停、批量禁用卡密',
+    presetProduct: '商品调整',
+    presetProductDesc: '创建、更新、删除商品',
+    presetCleanup: '系统清理',
+    presetCleanupDesc: '过期订单和锁定库存清理',
+    confirmClearAll: '确认清除全部操作日志？此操作不可撤销。',
+    exportSelectedSuccess: '已导出 {count} 条日志',
+    batchDeleteConfirm: '确认删除选中的 {count} 条日志？',
+    batchDeleteSuccess: '已删除 {count} 条日志',
+    batchDeleteFailed: '批量删除日志失败',
+    copySelectedSuccess: '已复制 {count} 条日志',
+    copySelectedFailed: '复制失败，请手动查看或导出 CSV',
+  },
+  adminConfig: {
+    title: '系统配置',
+    refresh: '刷新',
+    reload: '重新加载',
+    search: '搜索配置项',
+    colKey: '配置项',
+    colValue: '值',
+    colAction: '操作',
+    actionEdit: '编辑',
+    save: '保存',
+    saved: '保存成功',
+    saveFailed: '保存失败',
+    noData: '暂无配置',
+    sectionTabsLabel: '系统配置分区',
+    itemCount: '{count} 项',
+    loadFailed: '加载系统配置失败',
+    notSynced: '，但当前页面未能刷新前台配置；重新加载页面后可同步',
+    resetConfirm: '确认重置 {key} 为默认值？',
+    resetFailed: '重置失败',
+    resetSuccess: '已重置',
+    clearing: '清除中…',
+  },
+}
+
+export const adminKitMessagesEn: AdminKitMessageTree = {
+  pagination: {
+    listLabel: 'Pagination',
+    total: '{total} total',
+    perPage: 'Per page',
+    perPageUnit: '',
+    prev: 'Prev',
+    next: 'Next',
+    prevLabel: 'Previous page',
+    nextLabel: 'Next page',
+    page: 'Page {page}',
+    pageOf: '{page} / {total}',
+    jumpTo: 'Go to',
+    jumpPage: '',
+    jump: 'Go',
+    jumpLabel: 'Page number',
+  },
+  confirm: {
+    confirm: 'Confirm',
+    cancel: 'Cancel',
+    delete: 'Delete options',
+    requirePhrase: 'Type {phrase} to confirm',
+  },
+  adminModal: {
+    title: 'Dialog',
+    close: 'Close',
+  },
+  adminConfigField: {
+    reset: 'Reset',
+    saving: 'Saving…',
+    range: 'Range {min} ~ {max}',
+    yuanUnit: 'CNY',
+    hint: 'Edit in yuan; stored as cents',
+    override: 'Configured — leave blank to keep',
+    notConfigured: 'Not configured',
+    enumEmptyHint: 'Keep at least one option',
+    unlimited: 'Unlimited',
+    placeholder: 'Enter a valid amount',
+    minError: 'Must be ≥ {min}',
+    maxError: 'Must be ≤ {max}',
+  },
+  adminLayout: {
+    logout: 'Log out',
+    toggleSidebar: 'Menu',
+    admin: 'Admin',
+    title: 'Admin',
+    loggedOut: 'Signed out',
+  },
+  adminLogs: {
+    title: 'Audit Logs',
+    search: 'Search action type',
+    targetSearch: 'Search target type',
+    targetSearchPlaceholder: 'Search target',
+    searchBtn: 'Search',
+    clearing: 'Clearing…',
+    clearAll: 'Clear all logs',
+    allLogs: 'All logs',
+    clearFilters: 'Clear filters',
+    reload: 'Reload',
+    selectedCount: '{count} logs selected',
+    clearSelection: 'Clear selection',
+    copySelected: 'Copy selected',
+    exportSelectedCsv: 'Export CSV',
+    batchDelete: 'Batch delete ({count})',
+    deleting: 'Deleting…',
+    colTime: 'Time',
+    colOperator: 'Operator',
+    colAction: 'Action',
+    colTarget: 'Target type',
+    colTargetId: 'Target ID',
+    colIpFingerprint: 'IP fingerprint',
+    colMetadata: 'Metadata',
+    colDetail: 'Details',
+    noData: 'No logs',
+    viewMetadata: 'View',
+    tableScrollArea: 'Log table scroll area',
+    tableLabel: 'Audit log list',
+    selectAllPage: 'Select all on this page',
+    selectRow: 'Select log {log}',
+    metadataTitle: 'Log details',
+    basicInfo: 'Basic info',
+    labelAction: 'Action',
+    labelTargetType: 'Target type',
+    labelTargetId: 'Target ID',
+    labelTime: 'Time',
+    labelIpFingerprint: 'IP fingerprint (hash)',
+    labelMetadata: 'Metadata',
+    presetOrder: 'Order Processing',
+    presetOrderDesc: 'Payment confirmation, cancellation, compensation notes',
+    presetStock: 'Stock Management',
+    presetStockDesc: 'Import, enable/disable, batch disable cards',
+    presetProduct: 'Product Adjustment',
+    presetProductDesc: 'Create, update, delete products',
+    presetCleanup: 'System Cleanup',
+    presetCleanupDesc: 'Clean expired orders and locked stock',
+    confirmClearAll: 'Confirm clearing all logs? This action is irreversible.',
+    exportSelectedSuccess: 'Exported {count} logs',
+    batchDeleteConfirm: 'Confirm deleting {count} selected logs?',
+    batchDeleteSuccess: 'Deleted {count} logs',
+    batchDeleteFailed: 'Batch delete failed',
+    copySelectedSuccess: 'Copied {count} logs',
+    copySelectedFailed: 'Copy failed, please view or export CSV instead',
+  },
+  adminConfig: {
+    title: 'System Config',
+    refresh: 'Refresh',
+    reload: 'Reload',
+    search: 'Search config items',
+    colKey: 'Key',
+    colValue: 'Value',
+    colAction: 'Action',
+    actionEdit: 'Edit',
+    save: 'Save',
+    saved: 'Saved',
+    saveFailed: 'Save failed',
+    noData: 'No configuration',
+    sectionTabsLabel: 'Config sections',
+    itemCount: '{count} items',
+    loadFailed: 'Failed to load system config',
+    notSynced:
+      ', but the public config could not be refreshed on this page. Reload the page to sync.',
+    resetConfirm: 'Confirm reset {key} to default?',
+    resetFailed: 'Reset failed',
+    resetSuccess: 'Reset successfully',
+    clearing: 'Clearing…',
+  },
+}
+
+export const adminKitMessages: Record<AdminKitLocale, AdminKitMessageTree> = {
+  'zh-CN': adminKitMessagesZhCN,
+  en: adminKitMessagesEn,
+}
+
+/**
+ * 将套件消息浅合并进宿主本地化对象。
+ * 默认：套件补空缺，宿主同名键覆盖套件（产品文案优先）。
+ */
+export function mergeAdminKitMessages<T extends Record<string, unknown>>(
+  host: T,
+  locale: AdminKitLocale = 'zh-CN',
+): T & AdminKitMessageTree {
+  const kit = adminKitMessages[locale]
+  const out = { ...host } as T & AdminKitMessageTree
+  for (const section of Object.keys(kit) as (keyof AdminKitMessageTree)[]) {
+    const hostSection = (host[section as string] as Record<string, string> | undefined) ?? {}
+    ;(out as Record<string, unknown>)[section] = { ...kit[section], ...hostSection }
+  }
+  return out
+}