@usethink/cf-admin-fe 0.1.1 → 0.2.6

package/src/index.ts

@@ -1,9 +1,10 @@
 /**
- * @usethink/cf-admin-fe — Vue 3 admin foundation for CF product family.
+ * @usethink/cf-admin-fe — CF 产品族 Vue 3 管理端基础套件。
  *
- * Import composables from root or `@usethink/cf-admin-fe/composables`.
- * Import components from `@usethink/cf-admin-fe/components`.
- * Import styles: `import '@usethink/cf-admin-fe/styles'`.
+ * - 组合式：根入口或 `@usethink/cf-admin-fe/composables`
+ * - 组件：`@usethink/cf-admin-fe/components`
+ * - 工具：`@usethink/cf-admin-fe/utils`
+ * - 样式：`import '@usethink/cf-admin-fe/styles'`
  */
 
 export {
@@ -39,9 +40,147 @@ export {
 export {
   writeClipboardText,
   copyText,
+  copyWithToast,
+  type CopyWithToastOptions,
 } from './composables/useClipboard'
 
+export {
+  createAdminTokenSession,
+  useAdminTokenSession,
+  parseStoredAdminToken,
+  readAdminTokenFromStorage,
+  DEFAULT_ADMIN_TOKEN_TTL_MS,
+  type StoredAdminToken,
+  type CreateAdminTokenSessionOptions,
+  type AdminTokenSession,
+} from './composables/createAdminTokenSession'
+
+export {
+  createAdminFlagSession,
+  readAdminFlagFromStorage,
+  writeAdminFlagToStorage,
+  DEFAULT_ADMIN_FLAG_TRUTHY,
+  type CreateAdminFlagSessionOptions,
+  type AdminFlagSession,
+} from './composables/createAdminFlagSession'
+
+export {
+  createAdminRequest,
+  createAdminRequestRaw,
+  AdminRequestError,
+  type CreateAdminRequestOptions,
+  type AdminRequestCallOptions,
+  type AdminRequestFn,
+  type AdminRequestRawFn,
+  type AdminRequestResultMode,
+} from './composables/createAdminRequest'
+
+export {
+  useAdminSidebar,
+  type UseAdminSidebarOptions,
+  type UseAdminSidebarReturn,
+} from './composables/useAdminSidebar'
+
+export {
+  useAdminListLoader,
+  type UseAdminListLoaderOptions,
+  type UseAdminListLoaderReturn,
+  type AdminListLoadContext,
+  type AdminListRunLoadOptions,
+} from './composables/useAdminListLoader'
+
+export {
+  useNow,
+} from './composables/useNow'
+
+export {
+  formatDate,
+  toDateTimeLocalValue,
+  dateTimeLocalToIso,
+  isoToDateTimeLocal,
+  formatIpFingerprint,
+  downloadCsv,
+  safeCsvCell,
+  lockBodyScroll,
+  unlockBodyScroll,
+  isBodyScrollLocked,
+  __resetBodyScrollLockForTests,
+  normalizeCents,
+  formatCents,
+  parseYuanToCents,
+  createAdminUnauthorizedHandler,
+  decideAdminRouteAccess,
+  resolveAdminLoginRedirect,
+  groupDefinitionsByName,
+  countSectionItems,
+  buildActiveGroupedDefinitions,
+  countAdvancedItems,
+  resolveSystemConfigSectionId,
+  getSystemConfigSection,
+  listedSystemConfigGroups,
+  auditSystemConfigSectionCoverage,
+  toErrorMessage,
+  hasBatchFailures,
+  resolveBatchToastType,
+  formatBatchCountsMessage,
+  buildBatchToast,
+  formatDefaultBatchMixedMessage,
+  DEFAULT_ADMIN_BATCH_LIMIT,
+  checkAdminBatchLimit,
+  formatMetadata,
+  buildAdminOffsetParams,
+  applyAdminOffsetParams,
+} from './utils'
+
+export {
+  normalizeOtpDigits,
+  isOtpComplete,
+  OTP_CODE_LENGTH,
+} from './utils/otp-input'
+
+export type {
+  CreateAdminUnauthorizedHandlerOptions,
+  AdminRouteAuthDecision,
+  DecideAdminRouteAccessOptions,
+  ResolveAdminLoginRedirectOptions,
+  SystemConfigDefinitionLike,
+  SystemConfigSectionLike,
+  SystemConfigGroupedBlock,
+  BuildActiveGroupedOptions,
+  SystemConfigCoverageAudit,
+  AdminBatchCounts,
+  AdminBatchToast,
+  AdminBatchLimitOk,
+  AdminBatchLimitExceeded,
+  AdminBatchLimitCheck,
+  CheckAdminBatchLimitOptions,
+  AdminOffsetParams,
+} from './utils'
+
+export {
+  adminKitMessages,
+  adminKitMessagesZhCN,
+  adminKitMessagesEn,
+  mergeAdminKitMessages,
+} from './i18n'
+
+export type { AdminKitLocale, AdminKitMessageTree } from './i18n'
+
+export type {
+  AdminConfigFieldType,
+  AdminConfigFieldUnit,
+  AdminSystemConfigFieldDefinition,
+  AdminSystemConfigDefinition,
+  ConfigFieldStatus,
+} from './types'
+
 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'
+export { default as ConfigField } from './components/ConfigField.vue'
+export { default as AdminShell } from './components/AdminShell.vue'
+export { default as AdminLoginShell } from './components/AdminLoginShell.vue'
+export { default as AdminMetadataDetail } from './components/AdminMetadataDetail.vue'
+export type { AdminShellMenuItem } from './components/AdminShell.vue'
+export type { AdminLogEntry } from './components/AdminMetadataDetail.vue'

package/src/styles/admin-primitives.css

@@ -2004,3 +2004,26 @@
     white-space: normal;
   }
 }
+
+/* ── Header 语言切换（AdminShell #header-actions） ── */
+.lang-select {
+  height: 28px;
+  padding: 0 8px;
+  border: 1px solid var(--border, rgba(255, 255, 255, 0.1));
+  border-radius: var(--r-sm, 6px);
+  background: var(--tg-secondary-bg, #151b28);
+  color: var(--tg-text, #f0f2f5);
+  font-size: 12px;
+  color-scheme: dark;
+  cursor: pointer;
+  outline: none;
+}
+
+.lang-select:focus-visible {
+  border-color: var(--admin-accent, #f59e0b);
+}
+
+.lang-select option {
+  background: var(--tg-secondary-bg, #151b28);
+  color: var(--tg-text, #f0f2f5);
+}

package/src/styles/index.css

@@ -1,3 +1,4 @@
 /* @usethink/cf-admin-fe styles entry */
 @import './tokens.css';
 @import './admin-primitives.css';
+@import './login-primitives.css';

package/src/styles/login-primitives.css

@@ -0,0 +1,149 @@
+/* ═══════════════════════════════════════════════════════
+   @usethink/cf-admin-fe — Admin login chrome primitives
+   Shared by shop (token) / lottery (password+OTP+OAuth) shells.
+   Product owns form fields and auth logic.
+   ═══════════════════════════════════════════════════════ */
+
+.admin-login {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: var(--tg-bg, #0a0e17);
+  box-sizing: border-box;
+}
+
+.admin-login .login-card {
+  width: 100%;
+  max-width: 420px;
+  background: var(--tg-secondary-bg, #151b28);
+  border: 1px solid var(--border, rgba(255, 255, 255, 0.1));
+  border-radius: var(--r-lg, 12px);
+  padding: 26px 22px;
+  box-shadow: var(--shadow-lg, 0 20px 50px rgba(0, 0, 0, 0.45));
+  color: var(--tg-text, #f0f2f5);
+  box-sizing: border-box;
+}
+
+.admin-login .login-header {
+  margin-bottom: 0;
+}
+
+.admin-login .login-title {
+  margin: 0 0 6px;
+  font-size: 20px;
+  font-weight: 700;
+  text-align: center;
+  color: var(--tg-text, #f0f2f5);
+}
+
+.admin-login .login-subtitle {
+  margin: 0 0 18px;
+  font-size: 13px;
+  color: var(--tg-hint, #9aa4b2);
+  text-align: center;
+}
+
+.admin-login .login-form,
+.admin-login .register-form {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.admin-login .field-label {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 13px;
+  color: var(--tg-text, #f0f2f5);
+}
+
+.admin-login .field-label input {
+  box-sizing: border-box;
+  width: 100%;
+  height: 40px;
+  padding: 0 12px;
+  border: 1px solid var(--border, rgba(255, 255, 255, 0.1));
+  border-radius: var(--r-md, 8px);
+  background: var(--surface, rgba(255, 255, 255, 0.04));
+  color: var(--tg-text, #f0f2f5);
+  font-size: 14px;
+  outline: none;
+}
+
+.admin-login .field-label input:focus {
+  border-color: var(--admin-accent, #f59e0b);
+}
+
+.admin-login .field-label input:disabled {
+  opacity: 0.65;
+  cursor: not-allowed;
+}
+
+.admin-login .login-btn {
+  margin-top: 4px;
+  height: 40px;
+  font-size: 14px;
+}
+
+.admin-login .login-error {
+  margin: 0;
+  font-size: 13px;
+  color: var(--admin-danger, #ef4444);
+  text-align: center;
+}
+
+.admin-login .login-footer {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  margin-top: 16px;
+  font-size: 13px;
+  color: var(--tg-hint, #9aa4b2);
+}
+
+.admin-login .field-hint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--tg-hint, #9aa4b2);
+  line-height: 1.4;
+}
+
+/* Optional OAuth / divider chrome (lottery-style) */
+.admin-login .oauth-section {
+  margin-top: 16px;
+}
+
+.admin-login .oauth-section.oauth-primary {
+  margin: 0 0 20px;
+}
+
+.admin-login .oauth-btn {
+  width: 100%;
+  height: 42px;
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.admin-login .oauth-divider {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin: 12px 0;
+}
+
+.admin-login .oauth-divider::before,
+.admin-login .oauth-divider::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: var(--border, rgba(255, 255, 255, 0.1));
+}
+
+.admin-login .divider-text {
+  font-size: 12px;
+  color: var(--tg-hint, #9aa4b2);
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export type {
+  AdminConfigFieldType,
+  AdminConfigFieldUnit,
+  AdminSystemConfigFieldDefinition,
+  AdminSystemConfigDefinition,
+  ConfigFieldStatus,
+} from './system-config'

package/src/types/system-config.ts

@@ -0,0 +1,38 @@
+/**
+ * 供 Admin ConfigField UI 共用的系统配置字段定义。
+ * 是 shop + lottery 结构的超集（enum / difficulty 可选）。
+ */
+export type AdminConfigFieldType = 'string' | 'boolean' | 'integer'
+
+export type AdminConfigFieldUnit = 'cents' | 'count'
+
+export interface AdminSystemConfigFieldDefinition {
+  key: string
+  label: string
+  description?: string
+  type: AdminConfigFieldType
+  /** 整数存储单位：cents → 在 UI 中按主货币单位编辑 */
+  unit?: AdminConfigFieldUnit
+  sensitive?: boolean
+  configured?: boolean
+  defaultValue?: string
+  min?: number
+  max?: number
+  maxLength?: number
+  effect?: string
+  group?: string
+  order?: number
+  scope?: 'public' | 'admin'
+  difficulty?: 'basic' | 'advanced'
+  /** 多选枚举（以逗号分隔的字符串存储） */
+  enum?: string[]
+  enumLabels?: Record<string, string>
+}
+
+/**
+ * shop/lottery 历史使用的产品别名（`AdminSystemConfigDefinition`）。
+ * 在领域类型的再导出中优先使用此名称，便于无缝对齐。
+ */
+export type AdminSystemConfigDefinition = AdminSystemConfigFieldDefinition
+
+export type ConfigFieldStatus = 'idle' | 'saving' | 'saved' | 'error'

package/src/utils/admin-navigation.ts

@@ -0,0 +1,138 @@
+/**
+ * 供批量脚手架生成的 CF 管理端应用共用的导航辅助函数。
+ *
+ * 纯 / 可注入 — 不依赖 Vue Router。产品将决策映射到
+ * `router.push` / 命名路由，并注入产品特定的会话清理逻辑。
+ */
+
+export type CreateAdminUnauthorizedHandlerOptions = {
+  /** 登录路径前缀；默认 `/admin/login` */
+  loginPath?: string
+  /** 当前地址为空时，编码进 `?redirect=` 的回退路径 */
+  defaultRedirectPath?: string
+  /** 产品侧清除 token / 完整业务会话 */
+  clearSession?: () => void
+  /**
+   * 覆盖 location（测试用）。默认在可用时使用 `window.location`。
+   * 存在 `assign` 时使用它，否则设置 `href`。
+   */
+  location?: {
+    pathname: string
+    search: string
+    hash: string
+    assign?: (url: string) => void
+    href?: string
+  }
+}
+
+/**
+ * 构建 shop + lottery 使用的标准 401 副作用：
+ * 清除会话 → 带 `redirect` 查询参数硬跳转到登录页 → 已在登录页则跳过。
+ */
+export function createAdminUnauthorizedHandler(
+  options: CreateAdminUnauthorizedHandlerOptions = {},
+): () => void {
+  const loginPath = options.loginPath ?? '/admin/login'
+  const defaultRedirectPath = options.defaultRedirectPath ?? '/admin'
+
+  return function handleUnauthorized(): void {
+    try {
+      options.clearSession?.()
+    } catch {
+      /* 隐私模式 / 存储失败 — 仍尝试跳转 */
+    }
+
+    const loc =
+      options.location ??
+      (typeof window !== 'undefined'
+        ? {
+            pathname: window.location.pathname,
+            search: window.location.search,
+            hash: window.location.hash,
+            assign: (url: string) => window.location.assign(url),
+          }
+        : null)
+
+    if (!loc) return
+
+    try {
+      if (loc.pathname === loginPath || loc.pathname.startsWith(`${loginPath}/`)) {
+        return
+      }
+      const current = `${loc.pathname}${loc.search}${loc.hash}`
+      const target = `${loginPath}?redirect=${encodeURIComponent(current || defaultRedirectPath)}`
+      if (typeof loc.assign === 'function') {
+        loc.assign(target)
+      } else if (loc.href !== undefined) {
+        loc.href = target
+      }
+    } catch {
+      /* 忽略导航失败；调用方仍会抛出 AdminRequestError */
+    }
+  }
+}
+
+export type AdminRouteAuthDecision =
+  | { type: 'allow' }
+  | { type: 'login'; redirect: string }
+  | { type: 'home' }
+
+export type DecideAdminRouteAccessOptions = {
+  hasToken: boolean
+  requiresAuth?: boolean
+  requiresGuest?: boolean
+  /** 登录跳转查询参数使用的当前完整路径（如 `to.fullPath`） */
+  fullPath: string
+}
+
+/**
+ * shop-simple 和 lottery 共用的核心 Bearer 管理员路由守卫（在
+ * 产品专属的引导 / 平台 / 模拟身份规则之前执行）。
+ */
+export function decideAdminRouteAccess(
+  options: DecideAdminRouteAccessOptions,
+): AdminRouteAuthDecision {
+  if (options.requiresAuth && !options.hasToken) {
+    return { type: 'login', redirect: options.fullPath }
+  }
+  if (options.requiresGuest && options.hasToken) {
+    return { type: 'home' }
+  }
+  return { type: 'allow' }
+}
+
+export type ResolveAdminLoginRedirectOptions = {
+  /** 登录后的默认落地页；默认 `/admin` */
+  defaultPath?: string
+  /**
+   * 仅允许此前缀下的跳转（开放重定向防护）。
+   * 默认 `/admin`。平台应用可传入 `/platform` 或自定义校验器。
+   */
+  allowPrefix?: string
+  /** 额外的白名单谓词（如 lottery 平台路径） */
+  isAllowed?: (path: string) => boolean
+}
+
+/**
+ * 从 `route.query.redirect` 解析登录后跳转目标。
+ * 拒绝协议相对路径和前缀之外的路径。
+ */
+export function resolveAdminLoginRedirect(
+  redirectQuery: unknown,
+  options: ResolveAdminLoginRedirectOptions = {},
+): string {
+  const defaultPath = options.defaultPath ?? '/admin'
+  const allowPrefix = options.allowPrefix ?? '/admin'
+
+  if (typeof redirectQuery !== 'string' || !redirectQuery) return defaultPath
+  if (redirectQuery.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(redirectQuery)) {
+    return defaultPath
+  }
+  if (options.isAllowed) {
+    return options.isAllowed(redirectQuery) ? redirectQuery : defaultPath
+  }
+  if (redirectQuery === allowPrefix || redirectQuery.startsWith(`${allowPrefix}/`) || redirectQuery.startsWith(`${allowPrefix}?`)) {
+    return redirectQuery
+  }
+  return defaultPath
+}

package/src/utils/admin-query.ts

@@ -0,0 +1,51 @@
+/**
+ * 管理端列表常用的 offset 分页查询字段（**字符串**形态）。
+ *
+ * 适用：URLSearchParams / query string（如 lottery 平台审计、租户、webhook、兑换码）。
+ * 不适用：类型化 filter / JSON body 需要 **number** 的 limit/offset（如 shop 余额/充值/代金券）—
+ * 那些场景请产品手写 `offset: (page - 1) * limit`，不要把本函数的 string 结果硬塞进 number 字段。
+ *
+ * 过滤器键名因产品而异，只抽取这两项稳定字段。
+ * 完整对照见 docs/002 §5.8。
+ */
+
+export type AdminOffsetParams = {
+  limit: string
+  offset: string
+}
+
+/**
+ * 由 1-based 页码与每页条数生成 **字符串化** 的 limit/offset（便于 URLSearchParams）。
+ * 非法页码回退为 1；非法 limit 回退为 20。
+ *
+ * @returns `{ limit: string, offset: string }` — 不是 number
+ */
+export function buildAdminOffsetParams(
+  page: number,
+  limit: number,
+  options?: { fallbackLimit?: number },
+): AdminOffsetParams {
+  const fallbackLimit = options?.fallbackLimit ?? 20
+  const safePage = Number.isFinite(page) && page > 0 ? Math.floor(page) : 1
+  const safeLimit =
+    Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : fallbackLimit
+  return {
+    limit: String(safeLimit),
+    offset: String((safePage - 1) * safeLimit),
+  }
+}
+
+/**
+ * 将 limit/offset 写入已有 URLSearchParams（会覆盖同名键）。
+ */
+export function applyAdminOffsetParams(
+  params: URLSearchParams,
+  page: number,
+  limit: number,
+  options?: { fallbackLimit?: number },
+): URLSearchParams {
+  const built = buildAdminOffsetParams(page, limit, options)
+  params.set('limit', built.limit)
+  params.set('offset', built.offset)
+  return params
+}

package/src/utils/batch-limit.ts

@@ -0,0 +1,66 @@
+/**
+ * 在调用服务端批量接口前，守卫管理端的多选数量。
+ *
+ * 默认上限 {@link DEFAULT_ADMIN_BATCH_LIMIT}（20）对齐 **cf-auth** / docs 风格 API。
+ * 后端若为 `z.array(...).max(N)` 且 N≠20（例如 cf-shop 订单/卡密/日志批量 **200**），
+ * 必须传入 `options.limit: N`，否则会在未达后端上限前误拦，或（反过来）默认过宽时漏拦。
+ *
+ * 单位词 `unit` 只影响默认中文提示；完整文案可用 `message` 覆盖。
+ */
+
+export const DEFAULT_ADMIN_BATCH_LIMIT = 20
+
+export type AdminBatchLimitOk = {
+  ok: true
+  count: number
+  limit: number
+}
+
+export type AdminBatchLimitExceeded = {
+  ok: false
+  count: number
+  limit: number
+  message: string
+}
+
+export type AdminBatchLimitCheck = AdminBatchLimitOk | AdminBatchLimitExceeded
+
+export type CheckAdminBatchLimitOptions = {
+  /** 每次请求的最大条数；默认 {@link DEFAULT_ADMIN_BATCH_LIMIT} */
+  limit?: number
+  /**
+   * 默认中文消息中的单位词，如 `人` / `条` / `个`。
+   * 设置了 `message` 时忽略。
+   */
+  unit?: string
+  /** 超限时的完整覆盖消息 */
+  message?: string
+}
+
+function defaultOverLimitMessage(limit: number, unit?: string): string {
+  if (unit) return `单次最多 ${limit} ${unit}，请缩小选择`
+  return `单次最多 ${limit} 条，请缩小选择`
+}
+
+/**
+ * @param selection - 选中的 id 列表，或预先计算好的数量
+ * @param options.limit - 单次最大条数；省略则用 {@link DEFAULT_ADMIN_BATCH_LIMIT}（20）
+ */
+export function checkAdminBatchLimit(
+  selection: readonly unknown[] | number,
+  options: CheckAdminBatchLimitOptions = {},
+): AdminBatchLimitCheck {
+  const count = typeof selection === 'number' ? selection : selection.length
+  const limit = options.limit ?? DEFAULT_ADMIN_BATCH_LIMIT
+
+  if (count <= limit) {
+    return { ok: true, count, limit }
+  }
+
+  return {
+    ok: false,
+    count,
+    limit,
+    message: options.message ?? defaultOverLimitMessage(limit, options.unit),
+  }
+}