@usethink/cf-admin-fe 0.1.1 → 0.2.8

package/dist/composables/useClipboard.d.ts

@@ -1,4 +1,26 @@
-/** 剪贴板工具：一键复制文本到剪贴板，带按钮视觉反馈 */
-/** 复制文本，更新按钮文字反馈 */
+/** 剪贴板工具：一键复制；按钮视觉反馈；或成功/失败 toast（管理端列表/详情常用） */
+import { type ToastType } from './useToast';
+/** 写入剪贴板（无 UI 反馈） */
 export declare function writeClipboardText(text: string): Promise<void>;
+/**
+ * 复制到剪贴板，并用全局 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 declare function copyWithToast(text: string, options: CopyWithToastOptions): Promise<boolean>;
+/** 复制文本，更新触发按钮的文字反馈（前台交付明细等） */
 export declare function copyText(text: string, e: Event): void;

package/dist/composables/useConfirmDialog.d.ts

@@ -3,7 +3,7 @@ export type ConfirmOptionDef = {
     label: string;
     /** 补充说明，显示在 label 下方 */
     hint?: string;
-    /** 默认 false */
+    /** 默认是否勾选；默认 false */
     defaultChecked?: boolean;
 };
 export type ConfirmAskOptions = {
@@ -11,6 +11,11 @@ export type ConfirmAskOptions = {
     danger?: boolean;
     /** 可选勾选项，默认全部未勾选；打开弹窗时按 defaultChecked 重置 */
     options?: ConfirmOptionDef[];
+    /**
+     * 须键入的确认短语（如硬删除的 "DELETE"）。
+     * 有值时确认按钮在输入完全匹配前禁用；与服务端 confirm 字面量对齐。
+     */
+    requirePhrase?: string;
 };
 export type ConfirmResult = {
     confirmed: boolean;
@@ -24,19 +29,20 @@ export declare function useConfirmDialog(): {
         key: string;
         label: string;
         hint?: string
-        /** 默认 false */
+        /** 默认是否勾选；默认 false */
          | undefined;
         defaultChecked?: boolean | undefined;
     }[], ConfirmOptionDef[] | {
         key: string;
         label: string;
         hint?: string
-        /** 默认 false */
+        /** 默认是否勾选；默认 false */
          | undefined;
         defaultChecked?: boolean | undefined;
     }[]>;
     confirmOptionValues: import("vue").Ref<Record<string, boolean>, Record<string, boolean>>;
-    askConfirm: (message: string) => Promise<boolean>;
+    confirmRequirePhrase: import("vue").Ref<string | null, string | null>;
+    askConfirm: (message: string, options?: ConfirmAskOptions) => Promise<boolean>;
     askConfirmWithOptions: (message: string, options?: ConfirmAskOptions) => Promise<ConfirmResult>;
     onConfirm: () => void;
     setConfirmOption: (key: string, checked: boolean) => void;

package/dist/composables/useNow.d.ts

@@ -0,0 +1,3 @@
+export declare function useNow(): {
+    nowMs: import("vue").Ref<number, number>;
+};

package/dist/composables/useTablePagination.d.ts

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

package/dist/composables/useTableSelection.d.ts

@@ -3,8 +3,8 @@ export interface UseTableSelectionOptions<T> {
     isSelectable?: (row: T) => boolean;
 }
 /**
- * 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 declare function useTableSelection<T>(rows: MaybeRef<T[]>, getKey: (row: T) => string, options?: UseTableSelectionOptions<T>): {
     selectedIds: import("vue").Ref<string[], string[]>;

package/dist/composables/useToast.d.ts

@@ -4,7 +4,7 @@ export type ToastItem = {
     message: string;
     type: ToastType;
 };
-/** Max stacked toasts; older entries drop when exceeded (lottery hardening). */
+/** 最多叠加显示的 toast 数；超过后丢弃较早的条目（抽奖加固）。 */
 export declare const MAX_TOASTS = 5;
 declare function showToast(message: string, type?: ToastType, duration?: number): void;
 export declare function useToast(): {

package/dist/types/index.d.ts

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

package/dist/types/system-config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 供 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/dist/utils/admin-navigation.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 供批量脚手架生成的 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 declare function createAdminUnauthorizedHandler(options?: CreateAdminUnauthorizedHandlerOptions): () => void;
+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 declare function decideAdminRouteAccess(options: DecideAdminRouteAccessOptions): AdminRouteAuthDecision;
+export type ResolveAdminLoginRedirectOptions = {
+    /** 登录后的默认落地页；默认 `/admin` */
+    defaultPath?: string;
+    /**
+     * 仅允许此前缀下的跳转（开放重定向防护）。
+     * 默认 `/admin`。平台应用可传入 `/platform` 或自定义校验器。
+     */
+    allowPrefix?: string;
+    /** 额外的白名单谓词（如 lottery 平台路径） */
+    isAllowed?: (path: string) => boolean;
+};
+/**
+ * 从 `route.query.redirect` 解析登录后跳转目标。
+ * 拒绝协议相对路径和前缀之外的路径。
+ */
+export declare function resolveAdminLoginRedirect(redirectQuery: unknown, options?: ResolveAdminLoginRedirectOptions): string;

package/dist/utils/admin-query.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 管理端列表常用的 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 declare function buildAdminOffsetParams(page: number, limit: number, options?: {
+    fallbackLimit?: number;
+}): AdminOffsetParams;
+/**
+ * 将 limit/offset 写入已有 URLSearchParams（会覆盖同名键）。
+ */
+export declare function applyAdminOffsetParams(params: URLSearchParams, page: number, limit: number, options?: {
+    fallbackLimit?: number;
+}): URLSearchParams;

package/dist/utils/batch-limit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 在调用服务端批量接口前，守卫管理端的多选数量。
+ *
+ * 默认上限 {@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 declare 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;
+};
+/**
+ * @param selection - 选中的 id 列表，或预先计算好的数量
+ * @param options.limit - 单次最大条数；省略则用 {@link DEFAULT_ADMIN_BATCH_LIMIT}（20）
+ */
+export declare function checkAdminBatchLimit(selection: readonly unknown[] | number, options?: CheckAdminBatchLimitOptions): AdminBatchLimitCheck;

package/dist/utils/batch-result.d.ts

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

package/dist/utils/body-scroll-lock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 供叠加弹层（确认框 → 弹窗交接）共用的 body 滚动锁定。
+ * - 引用计数，保证嵌套层级不会让页面闪烁解锁
+ * - 用 padding-right 补偿滚动条宽度，避免布局跳动
+ *
+ * 仅修改 document.body 的内联样式；无 document 环境（SSR/测试）下为空操作。
+ */
+/** 当前模块是否持有 body 滚动锁（测试 / 调试用）。 */
+export declare function isBodyScrollLocked(): boolean;
+/** 仅供测试使用的重置 — 请勿在生产路径中调用。 */
+export declare function __resetBodyScrollLockForTests(): void;
+export declare function lockBodyScroll(): void;
+export declare function unlockBodyScroll(): void;

package/dist/utils/csv-export.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CSV 下载，针对电子表格客户端做了公式注入防护。
+ * 语义与后端服务端导出 CSV 的产品实现保持一致。
+ */
+/** 转义单个单元格：加引号 + 内部双引号加倍；中和开头的公式字符。 */
+export declare function safeCsvCell(value: unknown): string;
+/** 通过临时 object URL 下载 UTF-8 BOM 的 CSV。 */
+export declare function downloadCsv(filename: string, rows: string[][]): void;

package/dist/utils/currency-cents.d.ts

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

package/dist/utils/datetime.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 供 CF 产品管理员共用的日期时间辅助函数。
+ * 纯函数 — 不依赖 Vue，不含领域标签。
+ */
+/**
+ * ISO 字符串 / Date → 本地 `YYYY-MM-DD HH:mm:ss`；空值 → `-`。
+ * 接受 `Date` 对象，使 cookie/JSON 管理表格无需产品包装层（cf-auth）。
+ */
+export declare function formatDate(value?: string | Date | null): string;
+/** 后端时间 → `datetime-local` 输入值（本地挂钟时间，不含秒） */
+export declare function toDateTimeLocalValue(value?: string | null): string;
+/** `datetime-local` 值 → ISO 字符串（跨浏览器稳定） */
+export declare function dateTimeLocalToIso(value?: string | null): string;
+/** {@link toDateTimeLocalValue} 的别名，用于编辑表单回填 */
+export declare function isoToDateTimeLocal(iso?: string | null): string;
+/**
+ * 对长不透明字符串（如哈希后的客户端 IP）生成短指纹。
+ * 完整值保留用于详情/导出；列表展示缩写形式。
+ */
+export declare function formatIpFingerprint(value?: string | null, maxPlain?: number): string;

package/dist/utils/error-message.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 将未知的 catch 值规范化为管理端 toast / loading 展示用的字符串。
+ *
+ * 供 cf-shop / cf-lottery / cf-auth 管理端 UI 共用，它们反复编写：
+ * `err instanceof Error ? err.message : fallback`。
+ */
+export declare function toErrorMessage(error: unknown, fallback?: string): string;

package/dist/utils/format-metadata.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 格式化元数据为可读的 JSON 字符串。
+ * 用于日志详情等场景展示结构化数据。
+ */
+export declare function formatMetadata(metadata: Record<string, unknown>): string;

package/dist/utils/i18n.d.ts

@@ -0,0 +1,14 @@
+export type AdminI18nProxy = {
+    $t?: (key: string, params?: Record<string, unknown>) => unknown;
+    $te?: (key: string) => boolean;
+} | null | undefined;
+/**
+ * 纯函数：可在单测中直接注入 proxy，不依赖 setup。
+ */
+export declare function resolveAdminT(proxy: AdminI18nProxy, key: string, fallback: string, params?: Record<string, unknown>): string;
+/**
+ * 从当前组件实例的 appContext.globalProperties 读取 `$t` / `$te`。
+ * 使用 globalProperties 而非 `proxy.$t`，避免未安装 vue-i18n 时访问实例代理触发 Vue warn。
+ * 勿在模块顶层调用。
+ */
+export declare function tKit(key: string, fallback: string, params?: Record<string, unknown>): string;

package/dist/utils/index.d.ts

@@ -0,0 +1,13 @@
+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';
+export { resolveAdminT, tKit, type AdminI18nProxy, } from './i18n';

package/dist/utils/otp-input.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OTP 输入规范化（纯函数）。
+ *
+ * - 只保留数字，最长 6 位
+ * - 便于 SMS/邮件自动填充后触发「满 6 位自动提交」
+ */
+export declare const OTP_CODE_LENGTH = 6;
+/** 去掉非数字并截断到 OTP 长度 */
+export declare function normalizeOtpDigits(raw: string, maxLen?: number): string;
+/** 是否已满位、可触发自动提交 */
+export declare function isOtpComplete(digits: string, maxLen?: number): boolean;

package/dist/utils/system-config-engine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare function groupDefinitionsByName<T extends SystemConfigDefinitionLike>(definitions: readonly T[], fallbackGroupName?: string): Map<string, T[]>;
+/**
+ * 按分区 id 统计定义项数量（所列分组长度之和）。
+ */
+export declare function countSectionItems(groupsByName: Map<string, readonly unknown[]>, sections: readonly SystemConfigSectionLike[]): Record<string, number>;
+export type BuildActiveGroupedOptions = {
+    /**
+     * 为 false 时，隐藏 `difficulty === 'advanced'` 的项（lottery 基础模式）。
+     * 默认 true = 显示全部（shop）。
+     */
+    showAdvanced?: boolean;
+};
+/**
+ * 为当前激活分区构建有序分组块；丢弃空分组。
+ */
+export declare function buildActiveGroupedDefinitions<T extends SystemConfigDefinitionLike>(sectionGroups: readonly string[], groupsByName: Map<string, readonly T[]>, options?: BuildActiveGroupedOptions): SystemConfigGroupedBlock<T>[];
+/** 统计给定分区分组中高级难度的项数。 */
+export declare function countAdvancedItems<T extends SystemConfigDefinitionLike>(sectionGroups: readonly string[], groupsByName: Map<string, readonly T[]>): number;
+/**
+ * 将 `?tab=` 解析为已知分区 id；无效/为空 → defaultId（绝不凭空编造 id）。
+ */
+export declare function resolveSystemConfigSectionId<T extends string>(raw: unknown, validIds: readonly T[], defaultId: T): T;
+export declare function getSystemConfigSection<T extends SystemConfigSectionLike>(sections: readonly T[], id: string): T;
+/** 按声明顺序展平 section.groups，并去重。 */
+export declare function listedSystemConfigGroups(sections: readonly SystemConfigSectionLike[]): string[];
+export type SystemConfigCoverageAudit = {
+    ok: boolean;
+    unmappedGroups: string[];
+    unmappedKeys: string[];
+    duplicateGroups: string[];
+    extraGroupsInMap: string[];
+    sectionKeyCounts: Record<string, number>;
+    totalKeys: number;
+};
+/**
+ * 校验分区映射 ↔ 定义分组覆盖情况（单元/契约测试）。
+ * `fallbackGroupName` 必须与 UI 对空 `group` 字段的分组方式一致。
+ */
+export declare function auditSystemConfigSectionCoverage(definitions: readonly SystemConfigDefinitionLike[], sections: readonly SystemConfigSectionLike[], fallbackGroupName?: string): SystemConfigCoverageAudit;