@usethink/cf-admin-fe 0.1.0 → 0.2.6

package/src/utils/batch-result.ts

@@ -0,0 +1,81 @@
+/**
+ * 供管理端批量操作 toast / 汇总文案使用的纯辅助函数。
+ *
+ * 各产品在 i18n 键和成功文案上存在差异；kit 只负责判定
+ * 成功/失败基调，以及可选的 `{success}` / `{failed}` / `{count}` 填充。
+ */
+
+export type AdminBatchCounts = {
+  success: number
+  failed: number
+}
+
+export type AdminBatchToast = {
+  message: string
+  type: 'success' | 'error'
+}
+
+export function hasBatchFailures(result: AdminBatchCounts): boolean {
+  return (result.failed ?? 0) > 0
+}
+
+export function resolveBatchToastType(result: AdminBatchCounts): 'success' | 'error' {
+  return hasBatchFailures(result) ? 'error' : 'success'
+}
+
+/**
+ * 在模板中替换 `{success}`、`{failed}` 和 `{count}`（success 的别名）。
+ * 不依赖 vue-i18n — 产品可传入已翻译好的模板。
+ */
+export function formatBatchCountsMessage(
+  template: string,
+  result: AdminBatchCounts,
+): string {
+  const success = String(result.success ?? 0)
+  const failed = String(result.failed ?? 0)
+  // 使用 split/join 使 TS lib 目标保持在 ES2021 以下（产品 vue-tsc 消费方）。
+  return template
+    .split('{success}')
+    .join(success)
+    .split('{failed}')
+    .join(failed)
+    .split('{count}')
+    .join(success)
+}
+
+/**
+ * 从混合/成功模板构建 toast 载荷。
+ *
+ * @example
+ * buildBatchToast(res, {
+ *   mixed: '完成：成功 {success}，失败 {failed}',
+ *   success: '已处理 {count} 条',
+ * })
+ */
+export function buildBatchToast(
+  result: AdminBatchCounts,
+  templates: {
+    /** 当存在任一失败项时 */
+    mixed: string
+    /** 当失败数 === 0 时 */
+    success: string
+  },
+): AdminBatchToast {
+  const type = resolveBatchToastType(result)
+  const message = formatBatchCountsMessage(
+    type === 'error' ? templates.mixed : templates.success,
+    result,
+  )
+  return { message, type }
+}
+
+/**
+ * cf-auth 管理端页面大量使用的默认中文混合汇总文案。
+ * 有产品 i18n 时优先使用；这是零依赖的回退方案。
+ */
+export function formatDefaultBatchMixedMessage(
+  result: AdminBatchCounts,
+  prefix = '完成',
+): string {
+  return formatBatchCountsMessage(`${prefix}：成功 {success}，失败 {failed}`, result)
+}

package/src/utils/body-scroll-lock.ts

@@ -0,0 +1,63 @@
+/**
+ * 供叠加弹层（确认框 → 弹窗交接）共用的 body 滚动锁定。
+ * - 引用计数，保证嵌套层级不会让页面闪烁解锁
+ * - 用 padding-right 补偿滚动条宽度，避免布局跳动
+ *
+ * 仅修改 document.body 的内联样式；无 document 环境（SSR/测试）下为空操作。
+ */
+
+let lockCount = 0
+let previousOverflow = ''
+let previousPaddingRight = ''
+
+function scrollbarWidthPx(): number {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return 0
+  return Math.max(0, window.innerWidth - document.documentElement.clientWidth)
+}
+
+/** 当前模块是否持有 body 滚动锁（测试 / 调试用）。 */
+export function isBodyScrollLocked(): boolean {
+  return lockCount > 0
+}
+
+/** 仅供测试使用的重置 — 请勿在生产路径中调用。 */
+export function __resetBodyScrollLockForTests(): void {
+  lockCount = 0
+  previousOverflow = ''
+  previousPaddingRight = ''
+  if (typeof document !== 'undefined') {
+    document.body.style.overflow = ''
+    document.body.style.paddingRight = ''
+  }
+}
+
+export function lockBodyScroll(): void {
+  if (typeof document === 'undefined') return
+  lockCount += 1
+  if (lockCount !== 1) return
+
+  previousOverflow = document.body.style.overflow
+  previousPaddingRight = document.body.style.paddingRight
+
+  const gap = scrollbarWidthPx()
+  document.body.style.overflow = 'hidden'
+  if (gap > 0) {
+    const currentPad = Number.parseFloat(previousPaddingRight || '0') || 0
+    document.body.style.paddingRight = `${currentPad + gap}px`
+  }
+}
+
+export function unlockBodyScroll(): void {
+  if (typeof document === 'undefined') return
+  if (lockCount <= 0) {
+    lockCount = 0
+    return
+  }
+  lockCount -= 1
+  if (lockCount !== 0) return
+
+  document.body.style.overflow = previousOverflow
+  document.body.style.paddingRight = previousPaddingRight
+  previousOverflow = ''
+  previousPaddingRight = ''
+}

package/src/utils/csv-export.ts

@@ -0,0 +1,25 @@
+/**
+ * CSV 下载，针对电子表格客户端做了公式注入防护。
+ * 语义与后端服务端导出 CSV 的产品实现保持一致。
+ */
+
+/** 转义单个单元格：加引号 + 内部双引号加倍；中和开头的公式字符。 */
+export function safeCsvCell(value: unknown): string {
+  const text = String(value ?? '')
+  const escaped = text.replace(/"/g, '""')
+  // Excel/Sheets 将 = + - @（以及 tab/换行）视为公式起始字符。
+  return /^[=+\-@\t\n]/.test(escaped) ? `"\t${escaped}"` : `"${escaped}"`
+}
+
+/** 通过临时 object URL 下载 UTF-8 BOM 的 CSV。 */
+export function downloadCsv(filename: string, rows: string[][]): void {
+  if (typeof document === 'undefined') return
+  const content = `\uFEFF${rows.map((row) => row.map(safeCsvCell).join(',')).join('\n')}`
+  const blob = new Blob([content], { type: 'text/csv;charset=utf-8' })
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = filename
+  anchor.click()
+  URL.revokeObjectURL(url)
+}

package/src/utils/currency-cents.ts

@@ -0,0 +1,30 @@
+/**
+ * 供管理表单使用的纯最小单位（分）辅助函数。
+ * 不依赖产品资金库 — 人民币风格 2 位小数主单位。
+ * 使用多币种的产品应保留 `@shared/money`，仅对 ConfigField 风格的整数分字段
+ * 重新导出或包装这些函数。
+ */
+
+/** 将未知值强制转换为安全的整数分；否则返回 0。 */
+export function normalizeCents(value: unknown): number {
+  const cents = Number(value)
+  return Number.isSafeInteger(cents) ? cents : 0
+}
+
+/** 分 → 保留 2 位小数的主单位字符串（`123` → `"1.23"`）。 */
+export function formatCents(cents: number | unknown): string {
+  if (!Number.isFinite(Number(cents))) return '0.00'
+  return (normalizeCents(cents) / 100).toFixed(2)
+}
+
+/**
+ * 主单位字符串 → 整数分。
+ * 空 / 非数字 → `null`，让调用方可以拒绝非法输入
+ * （避免意外把 `"50"` 元写成 50 分）。
+ */
+export function parseYuanToCents(yuan: string): number | null {
+  if (!yuan.trim()) return null
+  const num = Number.parseFloat(yuan)
+  if (!Number.isFinite(num)) return null
+  return Math.round(num * 100)
+}

package/src/utils/datetime.ts

@@ -0,0 +1,54 @@
+/**
+ * 供 CF 产品管理员共用的日期时间辅助函数。
+ * 纯函数 — 不依赖 Vue，不含领域标签。
+ */
+
+function pad(num: number): string {
+  return String(num).padStart(2, '0')
+}
+
+/**
+ * ISO 字符串 / Date → 本地 `YYYY-MM-DD HH:mm:ss`；空值 → `-`。
+ * 接受 `Date` 对象，使 cookie/JSON 管理表格无需产品包装层（cf-auth）。
+ */
+export function formatDate(value?: string | Date | null): string {
+  if (value == null || value === '') return '-'
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return '-'
+    return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())} ${pad(value.getHours())}:${pad(value.getMinutes())}:${pad(value.getSeconds())}`
+  }
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return value
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
+}
+
+/** 后端时间 → `datetime-local` 输入值（本地挂钟时间，不含秒） */
+export function toDateTimeLocalValue(value?: string | null): string {
+  if (!value) return ''
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return value.slice(0, 16)
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`
+}
+
+/** `datetime-local` 值 → ISO 字符串（跨浏览器稳定） */
+export function dateTimeLocalToIso(value?: string | null): string {
+  if (!value) return ''
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? value : date.toISOString()
+}
+
+/** {@link toDateTimeLocalValue} 的别名，用于编辑表单回填 */
+export function isoToDateTimeLocal(iso?: string | null): string {
+  return toDateTimeLocalValue(iso)
+}
+
+/**
+ * 对长不透明字符串（如哈希后的客户端 IP）生成短指纹。
+ * 完整值保留用于详情/导出；列表展示缩写形式。
+ */
+export function formatIpFingerprint(value?: string | null, maxPlain = 18): string {
+  const text = value?.trim()
+  if (!text) return '-'
+  if (text.length <= maxPlain) return text
+  return `${text.slice(0, 10)}...${text.slice(-6)}`
+}

package/src/utils/error-message.ts

@@ -0,0 +1,32 @@
+/**
+ * 将未知的 catch 值规范化为管理端 toast / loading 展示用的字符串。
+ *
+ * 供 cf-shop / cf-lottery / cf-auth 管理端 UI 共用，它们反复编写：
+ * `err instanceof Error ? err.message : fallback`。
+ */
+
+export function toErrorMessage(error: unknown, fallback = ''): string {
+  if (error instanceof Error) {
+    const message = error.message.trim()
+    return message || fallback
+  }
+
+  if (typeof error === 'string') {
+    const message = error.trim()
+    return message || fallback
+  }
+
+  if (error != null && typeof error === 'object' && 'message' in error) {
+    const raw = (error as { message: unknown }).message
+    if (typeof raw === 'string') {
+      const message = raw.trim()
+      if (message) return message
+    }
+  }
+
+  if (fallback) return fallback
+  if (error == null) return ''
+
+  const asString = String(error).trim()
+  return asString || fallback
+}

package/src/utils/format-metadata.ts

@@ -0,0 +1,11 @@
+/**
+ * 格式化元数据为可读的 JSON 字符串。
+ * 用于日志详情等场景展示结构化数据。
+ */
+export function formatMetadata(metadata: Record<string, unknown>): string {
+  try {
+    return JSON.stringify(metadata, null, 2)
+  } catch {
+    return String(metadata)
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,81 @@
+export {
+  formatDate,
+  toDateTimeLocalValue,
+  dateTimeLocalToIso,
+  isoToDateTimeLocal,
+  formatIpFingerprint,
+} from './datetime'
+
+export { downloadCsv, safeCsvCell } from './csv-export'
+
+export {
+  lockBodyScroll,
+  unlockBodyScroll,
+  isBodyScrollLocked,
+  __resetBodyScrollLockForTests,
+} from './body-scroll-lock'
+
+export { normalizeCents, formatCents, parseYuanToCents } from './currency-cents'
+
+export {
+  createAdminUnauthorizedHandler,
+  decideAdminRouteAccess,
+  resolveAdminLoginRedirect,
+  type CreateAdminUnauthorizedHandlerOptions,
+  type AdminRouteAuthDecision,
+  type DecideAdminRouteAccessOptions,
+  type ResolveAdminLoginRedirectOptions,
+} from './admin-navigation'
+
+export {
+  groupDefinitionsByName,
+  countSectionItems,
+  buildActiveGroupedDefinitions,
+  countAdvancedItems,
+  resolveSystemConfigSectionId,
+  getSystemConfigSection,
+  listedSystemConfigGroups,
+  auditSystemConfigSectionCoverage,
+  type SystemConfigDefinitionLike,
+  type SystemConfigSectionLike,
+  type SystemConfigGroupedBlock,
+  type BuildActiveGroupedOptions,
+  type SystemConfigCoverageAudit,
+} from './system-config-engine'
+
+export {
+  normalizeOtpDigits,
+  isOtpComplete,
+  OTP_CODE_LENGTH,
+} from './otp-input'
+
+export { toErrorMessage } from './error-message'
+
+export {
+  hasBatchFailures,
+  resolveBatchToastType,
+  formatBatchCountsMessage,
+  buildBatchToast,
+  formatDefaultBatchMixedMessage,
+  type AdminBatchCounts,
+  type AdminBatchToast,
+} from './batch-result'
+
+export {
+  DEFAULT_ADMIN_BATCH_LIMIT,
+  checkAdminBatchLimit,
+  type AdminBatchLimitOk,
+  type AdminBatchLimitExceeded,
+  type AdminBatchLimitCheck,
+  type CheckAdminBatchLimitOptions,
+} from './batch-limit'
+
+export {
+  formatMetadata,
+} from './format-metadata'
+
+export {
+  buildAdminOffsetParams,
+  applyAdminOffsetParams,
+  type AdminOffsetParams,
+} from './admin-query'

package/src/utils/otp-input.ts

@@ -0,0 +1,18 @@
+/**
+ * OTP 输入规范化（纯函数）。
+ *
+ * - 只保留数字，最长 6 位
+ * - 便于 SMS/邮件自动填充后触发「满 6 位自动提交」
+ */
+
+export const OTP_CODE_LENGTH = 6
+
+/** 去掉非数字并截断到 OTP 长度 */
+export function normalizeOtpDigits(raw: string, maxLen = OTP_CODE_LENGTH): string {
+  return String(raw || '').replace(/\D/g, '').slice(0, maxLen)
+}
+
+/** 是否已满位、可触发自动提交 */
+export function isOtpComplete(digits: string, maxLen = OTP_CODE_LENGTH): boolean {
+  return digits.length === maxLen
+}

package/src/utils/system-config-engine.ts

@@ -0,0 +1,212 @@
+/**
+ * shop/lottery AdminSystemConfigView 共用的纯系统配置页面引擎。
+ *
+ * 产品负责：分区 id 联合、分组名列表、危险区 UI、API 加载/保存。
+ * 套件负责：分组、分区计数、高级筛选、tab 解析、覆盖率审计。
+ */
+
+/** 引擎使用的最小定义结构（ConfigField 项满足此结构）。 */
+export type SystemConfigDefinitionLike = {
+  key: string
+  group?: string
+  order?: number
+  difficulty?: 'basic' | 'advanced' | string
+}
+
+/** 最小分区结构 — 产品负责填充标签/描述。 */
+export type SystemConfigSectionLike = {
+  id: string
+  groups: readonly string[]
+  includeDangerZone?: boolean
+}
+
+export type SystemConfigGroupedBlock<T> = {
+  name: string
+  items: T[]
+}
+
+/**
+ * 按 `group` 对定义分组（为空时使用回退名称），并按 `order` 对每组排序。
+ */
+export function groupDefinitionsByName<T extends SystemConfigDefinitionLike>(
+  definitions: readonly T[],
+  fallbackGroupName = '其他',
+): Map<string, T[]> {
+  const map = new Map<string, T[]>()
+  for (const item of definitions) {
+    const name = item.group || fallbackGroupName
+    const bucket = map.get(name)
+    if (bucket) bucket.push(item)
+    else map.set(name, [item])
+  }
+  for (const items of map.values()) {
+    items.sort((a, b) => (a.order ?? 999) - (b.order ?? 999))
+  }
+  return map
+}
+
+/**
+ * 按分区 id 统计定义项数量（所列分组长度之和）。
+ */
+export function countSectionItems(
+  groupsByName: Map<string, readonly unknown[]>,
+  sections: readonly SystemConfigSectionLike[],
+): Record<string, number> {
+  const counts: Record<string, number> = {}
+  for (const section of sections) {
+    let n = 0
+    for (const group of section.groups) {
+      n += groupsByName.get(group)?.length ?? 0
+    }
+    counts[section.id] = n
+  }
+  return counts
+}
+
+export type BuildActiveGroupedOptions = {
+  /**
+   * 为 false 时，隐藏 `difficulty === 'advanced'` 的项（lottery 基础模式）。
+   * 默认 true = 显示全部（shop）。
+   */
+  showAdvanced?: boolean
+}
+
+/**
+ * 为当前激活分区构建有序分组块；丢弃空分组。
+ */
+export function buildActiveGroupedDefinitions<T extends SystemConfigDefinitionLike>(
+  sectionGroups: readonly string[],
+  groupsByName: Map<string, readonly T[]>,
+  options: BuildActiveGroupedOptions = {},
+): SystemConfigGroupedBlock<T>[] {
+  const showAdvanced = options.showAdvanced !== false
+  return sectionGroups
+    .map((name) => {
+      const raw = groupsByName.get(name) ?? []
+      const items = showAdvanced
+        ? [...raw]
+        : raw.filter((item) => item.difficulty !== 'advanced')
+      return { name, items }
+    })
+    .filter((group) => group.items.length > 0)
+}
+
+/** 统计给定分区分组中高级难度的项数。 */
+export function countAdvancedItems<T extends SystemConfigDefinitionLike>(
+  sectionGroups: readonly string[],
+  groupsByName: Map<string, readonly T[]>,
+): number {
+  let count = 0
+  for (const name of sectionGroups) {
+    const items = groupsByName.get(name) ?? []
+    count += items.filter((item) => item.difficulty === 'advanced').length
+  }
+  return count
+}
+
+/**
+ * 将 `?tab=` 解析为已知分区 id；无效/为空 → defaultId（绝不凭空编造 id）。
+ */
+export function resolveSystemConfigSectionId<T extends string>(
+  raw: unknown,
+  validIds: readonly T[],
+  defaultId: T,
+): T {
+  if (typeof raw !== 'string') return defaultId
+  const id = raw.trim()
+  if ((validIds as readonly string[]).includes(id)) return id as T
+  return defaultId
+}
+
+export function getSystemConfigSection<T extends SystemConfigSectionLike>(
+  sections: readonly T[],
+  id: string,
+): T {
+  const found = sections.find((s) => s.id === id)
+  return found ?? sections[0]!
+}
+
+/** 按声明顺序展平 section.groups，并去重。 */
+export function listedSystemConfigGroups(
+  sections: readonly SystemConfigSectionLike[],
+): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const section of sections) {
+    for (const group of section.groups) {
+      if (seen.has(group)) continue
+      seen.add(group)
+      out.push(group)
+    }
+  }
+  return out
+}
+
+export type SystemConfigCoverageAudit = {
+  ok: boolean
+  unmappedGroups: string[]
+  unmappedKeys: string[]
+  duplicateGroups: string[]
+  extraGroupsInMap: string[]
+  sectionKeyCounts: Record<string, number>
+  totalKeys: number
+}
+
+/**
+ * 校验分区映射 ↔ 定义分组覆盖情况（单元/契约测试）。
+ * `fallbackGroupName` 必须与 UI 对空 `group` 字段的分组方式一致。
+ */
+export function auditSystemConfigSectionCoverage(
+  definitions: readonly SystemConfigDefinitionLike[],
+  sections: readonly SystemConfigSectionLike[],
+  fallbackGroupName = '其他',
+): SystemConfigCoverageAudit {
+  const defGroups = new Set<string>()
+  for (const d of definitions) {
+    defGroups.add(d.group || fallbackGroupName)
+  }
+
+  const groupToSection = new Map<string, string>()
+  const duplicateGroups: string[] = []
+  for (const section of sections) {
+    for (const group of section.groups) {
+      if (groupToSection.has(group)) {
+        duplicateGroups.push(group)
+        continue
+      }
+      groupToSection.set(group, section.id)
+    }
+  }
+
+  const unmappedGroups = [...defGroups].filter((g) => !groupToSection.has(g)).sort()
+  const extraGroupsInMap = [...groupToSection.keys()].filter((g) => !defGroups.has(g)).sort()
+
+  const unmappedKeys: string[] = []
+  const sectionKeyCounts: Record<string, number> = {}
+  for (const section of sections) {
+    sectionKeyCounts[section.id] = 0
+  }
+  for (const d of definitions) {
+    const g = d.group || fallbackGroupName
+    const sectionId = groupToSection.get(g)
+    if (!sectionId) {
+      unmappedKeys.push(d.key)
+      continue
+    }
+    sectionKeyCounts[sectionId] = (sectionKeyCounts[sectionId] ?? 0) + 1
+  }
+
+  return {
+    ok:
+      unmappedGroups.length === 0
+      && unmappedKeys.length === 0
+      && duplicateGroups.length === 0
+      && extraGroupsInMap.length === 0,
+    unmappedGroups,
+    unmappedKeys,
+    duplicateGroups,
+    extraGroupsInMap,
+    sectionKeyCounts,
+    totalKeys: definitions.length,
+  }
+}

package/dist/components/index.d.ts

@@ -1,4 +0,0 @@
-export { default as AdminPagination } from './AdminPagination.vue';
-export { default as AdminModal } from './AdminModal.vue';
-export { default as ConfirmDialog } from './ConfirmDialog.vue';
-export { default as ToastContainer } from './ToastContainer.vue';

package/dist/index.d.ts

@@ -1,17 +0,0 @@
-/**
- * @usethink/cf-admin — Vue 3 admin foundation for CF product family.
- *
- * Import composables from root or `@usethink/cf-admin/composables`.
- * Import components from `@usethink/cf-admin/components`.
- * Import styles: `import '@usethink/cf-admin/styles'`.
- */
-export { useTablePagination, type UseTablePaginationOptions, type UseTablePaginationReturn, } from './composables/useTablePagination.ts';
-export { useTableSelection, type UseTableSelectionOptions, } from './composables/useTableSelection.ts';
-export { useConfirmDialog, type ConfirmOptionDef, type ConfirmAskOptions, type ConfirmResult, } from './composables/useConfirmDialog.ts';
-export { useToast, MAX_TOASTS, type ToastType, type ToastItem, } from './composables/useToast.ts';
-export { useAdminBatchOperation, type AdminBatchOperationResult, } from './composables/useAdminBatchOperation.ts';
-export { writeClipboardText, copyText, } from './composables/useClipboard.ts';
-export { default as AdminPagination } from './components/AdminPagination.vue';
-export { default as AdminModal } from './components/AdminModal.vue';
-export { default as ConfirmDialog } from './components/ConfirmDialog.vue';
-export { default as ToastContainer } from './components/ToastContainer.vue';