@usethink/cf-admin-fe 0.1.0 → 0.2.6

package/docs/002_cf-admin-fe/344/275/277/347/224/250/350/257/264/346/230/216/344/271/246/344/270/216/346/263/250/346/204/217/344/272/213/351/241/271.md

@@ -0,0 +1,801 @@
+# @usethink/cf-admin-fe 使用说明书与注意事项
+
+> **版本：** 0.2.6（以 `package.json` 为准）  
+> **读者：** 新建 CF 管理端前端、或把既有 admin 接到本套件的开发者  
+> **原则：** 只写仓库里真实存在的 API 与约束；不发明业务能力。  
+> **配套：** 根 [`README.md`](../README.md)（API 面速查）· [`recipes/README.md`](../recipes/README.md)（复制清单）· [`docs/001_…差距分析`](./001_cf-admin-fe提取差距分析报告_2026-08-05.md)（提取决策背景）
+
+---
+
+## 0. 一句话定位
+
+`@usethink/cf-admin-fe` 是 **Vue 3 管理端前端基础套件（admin foundation）**，不是：
+
+- 通用组件库（不是 Element Plus / Ant Design）
+- 业务中间层（没有订单/抽奖/RBAC/支付页面）
+- Worker / API 包（那是 `@usethink/cf-core` 等）
+
+它要解决的是：**每个 CF 产品都要写一遍的管理端壳、表格 UX、请求/会话工厂、错误与批量反馈、系统配置字段渲染**，在 **≥2 个线上消费方**（或已验证的第三条路径）验证后进入套件，让新产品「几分钟搭壳、业务页面自己写」。
+
+**线上消费方（验证面）：**
+
+| 产品 | 会话 | 角色 |
+|------|------|------|
+| **cf-shop** | Bearer JWT + localStorage TTL | 主路径参考 |
+| **cf-lottery** | Bearer + 产品 L3 胶水（平台/仿冒） | Bearer 扩展参考 |
+| **cf-auth** | Cookie HTTP 会话 + 本地 flag | **验证 cookie 路径**；不要克隆其 OAuth/业务页 |
+
+---
+
+## 1. 心智模型：双会话 · 三层 · 子路径
+
+### 1.1 两种一等会话（不要混）
+
+| 模型 | 套件 API | 真实会话在哪 | 路由守卫读什么 |
+|------|----------|--------------|----------------|
+| **Bearer** | `createAdminTokenSession` | localStorage 的 token+TTL；请求带 `Authorization` | `readToken()` / `hasToken` |
+| **Cookie + flag** | `createAdminFlagSession` | **HTTP cookie**（Better Auth 等，产品侧）；localStorage 只存守卫快路径 flag | `readFlag()` / `isLoggedIn` |
+
+- Bearer 产品：**不要**再发明第二套 token 读写；在 recipe 上叠产品 key / 多租户 / 仿冒。
+- Cookie 产品：**不要**被强迫用 token TTL / 密码表单；OAuth、健康探测、登出清 cookie 永远在产品侧。套件只提供 flag 存储 + 请求工厂 + 外壳 UI。
+
+### 1.2 三层分工
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 产品 L3：领域页面、领域 API、菜单文案、OAuth、平台角色   │
+├─────────────────────────────────────────────────────────┤
+│ @usethink/cf-admin-fe：壳、表格 UX、request/session、    │
+│   错误/批量纯函数、ConfigField、i18n 种子、recipes      │
+├─────────────────────────────────────────────────────────┤
+│ @usethink/cf-core 等：Worker、crypto、secrets…           │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 1.3 导入：优先子路径
+
+```ts
+// 推荐（Vitest / node 不解析根 SFC barrel）
+import { useTablePagination, copyWithToast } from '@usethink/cf-admin-fe/composables'
+import { toErrorMessage, buildAdminOffsetParams } from '@usethink/cf-admin-fe/utils'
+import { mergeAdminKitMessages } from '@usethink/cf-admin-fe/i18n'
+import AdminModal from '@usethink/cf-admin-fe/components/AdminModal.vue'
+import '@usethink/cf-admin-fe/styles'
+
+// 根入口也可以，但测试环境若扫到 .vue 可能更麻烦
+import { useToast } from '@usethink/cf-admin-fe'
+```
+
+**开发期 monorepo：** 常用 `file:../cf-admin-fe` 或 tsconfig `paths` 指到 `cf-admin-fe/src/*`（shop/lottery/auth 均已如此）。入口以 **`src/`** 为准；`dist/` 仅 `tsc` 生成的 d.ts，由 `prepack` 现场构建。
+
+---
+
+## 2. 从零搭一个新产品管理端（榨干路径）
+
+按顺序做；每一步都对应真实 recipe / API。
+
+### 步骤 0 — 安装与 peer
+
+```bash
+npm install @usethink/cf-admin-fe
+# 或 monorepo：npm install file:../cf-admin-fe
+```
+
+- **peer：** `vue` ^3.4  
+- **可选 peer：** `vue-i18n`（组件存在 `$t`/`$te` 时用；无 i18n 也能跑，回退英文/中文 fallback 字符串）
+
+### 步骤 1 — 样式
+
+```ts
+// main.ts
+import '@usethink/cf-admin-fe/styles'
+// 等价于 tokens + admin-primitives + login-primitives
+```
+
+或按需：
+
+```ts
+import '@usethink/cf-admin-fe/styles/tokens.css'
+import '@usethink/cf-admin-fe/styles/admin-primitives.css' // .admin-page / .toolbar / .lang-select …
+import '@usethink/cf-admin-fe/styles/login-primitives.css'  // .admin-login / .login-card
+```
+
+产品可再 `@import` 业务 CSS（伪装横幅、平台强调色等），**不要**把领域样式回灌进套件。
+
+### 步骤 2 — 根节点挂一次 Toast
+
+```vue
+<!-- App.vue -->
+<template>
+  <RouterView />
+  <ToastContainer />
+</template>
+```
+
+`useToast` 是 **模块单例**；多挂多次 Container 会重复渲染同一队列。`MAX_TOASTS = 5`，超出丢弃较早条目。
+
+### 步骤 3 — i18n 合并套件种子
+
+```ts
+// 见 recipes/i18n-merge.snippet.ts
+import { mergeAdminKitMessages } from '@usethink/cf-admin-fe/i18n'
+
+const messages = {
+  'zh-CN': mergeAdminKitMessages(hostZh, 'zh-CN'),
+  en: mergeAdminKitMessages(hostEn, 'en'),
+}
+```
+
+**套件种子覆盖的命名空间（宿主同名键优先覆盖）：**
+
+- `pagination.*` — AdminPagination  
+- `confirm.*` — ConfirmDialog  
+- `adminModal.*`  
+- `adminConfigField.*` — ConfigField 通用文案  
+- `adminLayout.*` — 外壳 logout / 侧栏等（**菜单项 `adminLayout.menu*` 仍由产品提供**）  
+- `adminLogs.*` — AdminMetadataDetail 等日志详情  
+- `adminConfig.*` — 系统配置页字段级文案约定：`adminConfig.fields.<key>.{label,description,effect}`；缺失时 ConfigField 用 `$te` 回退后端文本  
+
+**不要**把业务成功文案、硬删除策略用语放进套件。
+
+### 步骤 4 — 选会话模型并复制 auth recipe
+
+**Bearer（shop / lottery 风格）：** 复制 `recipes/useAdminAuth.shop.ts` → `src/composables/useAdminAuth.ts`
+
+```ts
+const session = createAdminTokenSession({
+  storageKey: 'admin_token', // 产品可改
+  ttlMs: 8 * 60 * 60 * 1000, // DEFAULT_ADMIN_TOKEN_TTL_MS
+})
+export function readAdminToken() { return session.readToken() }
+export function useAdminAuth() {
+  return {
+    token: session.token,
+    isLoggedIn: session.isLoggedIn,
+    setToken: session.setToken,
+    clearToken: session.clearToken,
+  }
+}
+```
+
+要点：
+
+- 存储形态：`{ token, expiry }` JSON；过期自动清键。  
+- 旧版裸字符串 token：解析时保留一次迁移。  
+- 路由守卫在 setup 外用 **`readAdminToken()` / `session.readToken()`**，不要只依赖组件内 ref。
+
+**Cookie（cf-auth 风格）：** 复制 `recipes/useAdminAuth.cookie.ts`
+
+```ts
+export const adminFlagSession = createAdminFlagSession({
+  storageKey: 'cf_auth_admin_ok',
+})
+// markLoggedIn / clearSession / readFlag / writeFlag
+```
+
+产品仍须实现：`/api/admin/health` 探测、登录写 cookie、登出清 cookie、允许列表。套件 **不管** cookie 本身。
+
+### 步骤 5 — 管理端请求工厂
+
+复制 `recipes/useAdminRequest.ts`（Bearer）或 `useAdminRequest.cookie.ts`。
+
+**`createAdminRequest` 关键旋钮（务必按产品对齐后端）：**
+
+| 选项 | 含义 | 典型 |
+|------|------|------|
+| `getToken` | 闭包取 Bearer；空则不带 Authorization | lottery 风格 |
+| `token`（单次调用） | 覆盖 `getToken`（含空串） | **shop** `api/admin.ts` 每方法传 token |
+| `credentials` | cookie 管理端用 `'include'` | cf-auth |
+| `resultMode` | `'http-ok'` 仅看 `res.ok`；`'ok-envelope'` 要 `res.ok && data.ok` | shop / lottery |
+| `errorField` | `'error'` \| `'message'` \| `'auto'` | 对齐 JSON 错误字段 |
+| `onUnauthorized` | 401 抛错前副作用 | 接 `createAdminUnauthorizedHandler` |
+| `onSuccess` | 成功后回调 | cookie 产品「治愈」缺失 flag |
+| `redirectOnUnauthorized` | `false` 时 401 仍抛错但跳过清会话 | **登录探测 token** 必备 |
+| `createAdminRequestRaw` | 不解析 JSON，只 `res.ok` + 401 | 导出 blob / 模板下载 |
+
+**401 标准副作用：**
+
+```ts
+import { createAdminUnauthorizedHandler } from '@usethink/cf-admin-fe/utils'
+
+const handleUnauthorized = createAdminUnauthorizedHandler({
+  clearSession: () => useAdminAuth().clearToken(),
+  loginPath: '/admin/login',
+  defaultRedirectPath: '/admin',
+})
+```
+
+行为：清会话 → 硬跳转 `loginPath?redirect=<当前 path+search+hash>` → **已在登录页则不再跳**（防死循环）。
+
+结构化错误：`AdminRequestError`（`status` / `code` / `data` / `response`），产品可映射到自有 `AdminApiError`。
+
+### 步骤 6 — 路由守卫
+
+复制 `recipes/router-guard.snippet.ts`，核心决策用纯函数：
+
+```ts
+import { decideAdminRouteAccess, resolveAdminLoginRedirect } from '@usethink/cf-admin-fe/utils'
+
+const decision = decideAdminRouteAccess({
+  hasToken: Boolean(readAdminToken()), // cookie 产品：readFlag()
+  requiresAuth: to.meta.requiresAuth,
+  requiresGuest: to.meta.requiresGuest,
+  fullPath: to.fullPath,
+})
+// allow | { type:'login', redirect } | { type:'home' }
+```
+
+登录成功落地：
+
+```ts
+const path = resolveAdminLoginRedirect(route.query.redirect, {
+  defaultPath: '/admin',
+  allowPrefix: '/admin',
+  // 平台应用可 isAllowed: (p) => p.startsWith('/platform')
+})
+```
+
+**开放重定向防护：** 拒绝 `//…`、带 scheme 的 URL；默认只允许 `allowPrefix` 下路径。平台应用务必收紧 `allowPrefix` / `isAllowed`。
+
+产品专属规则（引导页、平台角色、仿冒身份）**叠在** `decideAdminRouteAccess` 之后，不要改套件函数语义。
+
+### 步骤 7 — 布局外壳
+
+复制 `recipes/AdminLayout.vue`：
+
+- `AdminShell` + `useAdminSidebar`（默认 `max-width: 1023px` 汉堡）  
+- **菜单数据、标题** 是产品的；**用户信息默认在顶栏右上**（`userName` / `userAvatar` + 退出），侧栏底不再默认占位——菜单多时更省高、也更符合后台习惯  
+- 可选 `#header-actions`（语言等）在用户信息左侧；若必须把自定义块放回侧栏底，用 `#sidebar-footer`（有插槽才渲染）  
+- 退出：清会话 + toast + 跳转登录（`showLogout` / `showUser` 可关）  
+
+登录页：用 `AdminLoginShell` 包住 **产品表单**（密码 / OTP / OAuth 按钮都是产品的）。
+
+### 步骤 8 — 列表页标准组合（最能「榨干」的一页）
+
+完整伪代码见 **`recipes/list-page.snippet.ts`**。能力清单：
+
+| 能力 | API | 注意 |
+|------|-----|------|
+| 加载态 / 错误 / 竞态 | `useAdminListLoader` → `runLoad` | await 后 `ctx.isStale()` 则丢弃结果；`onError` 建议 `toErrorMessage` |
+| 分页 | `useTablePagination` → `page` / `limit` / `total` / `offset` / `setTotal` | **不是** `pageSize` 字段名 |
+| 多选 | `useTableSelection(rows, getKey)` | 支持 MaybeRef 行列表；shift 连选；`isSelectable` |
+| limit+offset（**string query**） | `buildAdminOffsetParams(page, limit)` | **位置参数**；产出 **字符串**；仅 URLSearchParams |
+| 写入已有 QS | `applyAdminOffsetParams(params, page, limit)` | 覆盖同名键，保留业务筛选 |
+| limit+offset（**number body**） | **产品手写** `(page-1)*limit` | **不要**套 string helper；见 §5.8 / shop |
+| 复制选中 | `copyWithToast` | 文案产品 i18n |
+| 批量上限 | `checkAdminBatchLimit(ids, { unit, limit?, message? })` | 默认 **20（auth）**；`max(N)` API 须 `{ limit: N }` |
+| 批量结果 toast | `buildBatchToast` / `resolveBatchToastType` | 服务端一次返回 `{success,failed}` |
+| 逐条串行批量 | `useAdminBatchOperation().runSequential` | 进度 ref；与「一次 HTTP 批量」不同 |
+
+**offset API 真实签名（勿写成对象；返回值是 string）：**
+
+```ts
+buildAdminOffsetParams(page: number, limit: number, options?: { fallbackLimit?: number })
+// → { limit: string, offset: string }   // 不是 number！
+
+applyAdminOffsetParams(
+  params: URLSearchParams,
+  page: number,
+  limit: number,
+  options?: { fallbackLimit?: number },
+)
+```
+
+非法页码 → 1；非法 limit → `fallbackLimit` 或 20。
+
+**number body 列表（shop 常见）手写即可：**
+
+```ts
+await listApi({
+  ...filters,
+  limit: limit.value,
+  offset: (page.value - 1) * limit.value, // number
+})
+```
+
+**`runLoad` 推荐形态（string query）：**
+
+```ts
+const { loading, loadError, runLoad, invalidate } = useAdminListLoader()
+
+await runLoad(async (ctx) => {
+  const res = await listApi(buildAdminOffsetParams(page.value, limit.value))
+  if (ctx.isStale()) return
+  items.value = res.items
+  setTotal(res.total)
+}, {
+  onError: (err) => toErrorMessage(err, t('adminXxx.loadFailed')),
+})
+
+onUnmounted(() => invalidate())
+```
+
+### 步骤 9 — 确认框 / 弹层 / 分页组件
+
+```vue
+<ConfirmDialog
+  v-model="confirmVisible"
+  :message="confirmMessage"
+  :options="confirmOptionDefs"
+  :option-values="confirmOptionValues"
+  :require-phrase="confirmRequirePhrase"
+  danger
+  @confirm="onConfirm"
+/>
+<AdminModal v-model="visible" title="…">…</AdminModal>
+<AdminPagination
+  :page="page"
+  :limit="limit"
+  :total="total"
+  @update:page="setPage"
+  @update:limit="setLimit"
+/>
+```
+
+`useConfirmDialog`：
+
+- `askConfirm(msg)` → `Promise<boolean>`  
+- `askConfirmWithOptions(msg, { options, requirePhrase, danger })` → `{ confirmed, options }`  
+- `requirePhrase`：必须键入完全匹配才可确认（硬删除对齐服务端字面量）
+
+弹层滚动：组件内部会用 `lockBodyScroll` / `unlockBodyScroll`（**引用计数**，嵌套弹层安全）。产品自写遮罩时也可直接调这两个 util。
+
+### 步骤 10 — 系统配置页（有配置中心时）
+
+1. 产品维护 **分区 id 联合、分组名列表、危险区 UI、加载/保存 API**。  
+2. 套件纯引擎（`/utils`）：
+
+   - `groupDefinitionsByName`  
+   - `countSectionItems` / `countAdvancedItems`  
+   - `buildActiveGroupedDefinitions`（`showAdvanced`）  
+   - `resolveSystemConfigSectionId` / `getSystemConfigSection` / `listedSystemConfigGroups`  
+   - `auditSystemConfigSectionCoverage`（测试里审计分区覆盖）
+
+3. 每项用 **`ConfigField`**：boolean / 枚举多选 / integer / cents / sensitive / textarea。  
+4. cents 编辑走套件 `formatCents` / `parseYuanToCents`（人民币风格 2 位小数）；**多币种订单金额**仍用产品 `@shared/money`。
+
+### 步骤 11 — 审计日志详情（可选）
+
+- **纯函数（旧页 / 自研 markup）：** `formatMetadata(record)`（安全 `JSON.stringify`，失败则 `String`）— shop/lottery 日志页已 re-export 此函数即可  
+- **组件（新页优先）：** `AdminMetadataDetail`（深路径 `components/AdminMetadataDetail.vue`）  
+- **不要**为「对齐套件」把已有详情 DOM 全量迁组件（维护税高、收益低）  
+- 依赖宿主 `adminLogs.*` i18n（已由 kit messages 提供默认种子）
+
+### 步骤 12 — 轻量 reexport（可选但推荐）
+
+复制 `recipes/reexports/*`，让旧路径 `@/composables/useX` 继续工作，视图无需大改：
+
+```ts
+// src/composables/useClipboard.ts
+export {
+  writeClipboardText,
+  copyText,
+  copyWithToast,
+  type CopyWithToastOptions,
+} from '@usethink/cf-admin-fe/composables'
+```
+
+---
+
+## 3. 能力全表：什么时候用哪个
+
+### 3.1 Composables
+
+| API | 用途 | 不要用来… |
+|-----|------|-----------|
+| `useTablePagination` | page/limit/total/offset | 存业务筛选（筛选是产品 state） |
+| `useTableSelection` | 多选、全选、shift 连选 | 跨页服务端选择模型（未实现） |
+| `useConfirmDialog` + `ConfirmDialog` | 危险确认、键入短语 | 复杂多步向导 |
+| `useToast` + `ToastContainer` | 全局提示 | 表单字段级校验（用本地 error） |
+| `useAdminBatchOperation` | **逐条**串行、要进度条 | 服务端已返回汇总的一次 POST（改用 buildBatchToast） |
+| `useAdminListLoader` | 列表竞态与 loading | 替换业务 fetch |
+| `useAdminSidebar` | 窄屏侧栏开关 | 桌面信息架构 |
+| `useNow` | 共享 60s 时钟（倒计时多组件） | 毫秒级动画时钟 |
+| `writeClipboardText` | 只写剪贴板 | 管理端主复制路径（缺反馈） |
+| `copyText(text, event)` | 按钮内 ✅/❌ | 与 toast **叠用**且不看结果 |
+| `copyWithToast` | 管理端复制主路径 | 创建成功后「失败仍业务成功」的降级文案场景 |
+| `createAdminTokenSession` | Bearer 会话 | Cookie 产品 |
+| `createAdminFlagSession` | Cookie 守卫 flag | 当真会话存储 |
+| `createAdminRequest` / `Raw` | 统一 fetch | 领域 URL 与 DTO 定义 |
+
+### 3.2 剪贴板三件套（必读）
+
+```ts
+// ① 管理端列表/详情 — 推荐
+const ok = await copyWithToast(text, {
+  successMessage: t('…success'),
+  errorMessage: t('…failed'),
+  // showToast?: 可注入，默认 useToast().showToast
+})
+if (ok) { /* 关弹层等 */ }
+
+// ② 前台交付明细按钮 — 只改按钮文字
+copyText(secret, event)
+
+// ③ 静默 / 业务降级
+try {
+  await writeClipboardText(url)
+  showToast(t('openedWithLink'), 'success')
+} catch {
+  showToast(t('openedOnly'), 'success') // 注意：仍是业务成功，不是 copy error
+}
+```
+
+**禁止：** `copyText` 后立刻无条件 `showToast(..., 'success')`（失败时假成功）。管理端交付复制应只走 `copyWithToast`。
+
+### 3.3 错误与批量纯函数
+
+```ts
+import {
+  toErrorMessage,
+  buildBatchToast,
+  resolveBatchToastType,
+  formatBatchCountsMessage,
+  formatDefaultBatchMixedMessage,
+  hasBatchFailures,
+  checkAdminBatchLimit,
+  DEFAULT_ADMIN_BATCH_LIMIT,
+} from '@usethink/cf-admin-fe/utils'
+
+// catch / loader
+showToast(toErrorMessage(e, t('loadFailed')), 'error')
+
+// 服务端 { success, failed }
+const toast = buildBatchToast(res, {
+  mixed: '完成：成功 {success}，失败 {failed}',
+  success: '已处理 {count} 条',
+})
+showToast(toast.message, toast.type)
+
+// 已有 i18n 文案，只复用色调
+showToast(t('batchDone', counts), resolveBatchToastType(counts))
+
+// POST 前
+const check = checkAdminBatchLimit(ids, { unit: '人' }) // 或 limit: 50, message: '…'
+if (!check.ok) {
+  showToast(check.message, 'error')
+  return
+}
+```
+
+`toErrorMessage` 顺序：`Error.message` → string → `object.message` → fallback → `String(error)`。  
+**空 fallback 时** 可能返回 `''`；展示给用户时请传产品默认句。
+
+### 3.4 导航纯函数
+
+- `createAdminUnauthorizedHandler` — 见步骤 5  
+- `decideAdminRouteAccess` — 见步骤 6  
+- `resolveAdminLoginRedirect` — 见步骤 6  
+
+均 **不依赖 vue-router**；产品负责 `router.push` / `location.assign`。
+
+### 3.5 其它 utils
+
+| API | 说明 |
+|-----|------|
+| `formatDate` / `toDateTimeLocalValue` / `dateTimeLocalToIso` / `isoToDateTimeLocal` | 管理表单与表格时间 |
+| `formatIpFingerprint` | 日志 IP 指纹展示 |
+| `downloadCsv` / `safeCsvCell` | 导出；单元格防 Excel 公式注入（`=+-@` 等） |
+| `lockBodyScroll` / `unlockBodyScroll` / `isBodyScrollLocked` | 引用计数滚动锁 |
+| `normalizeCents` / `formatCents` / `parseYuanToCents` | ConfigField 分/元；非多币种账本 |
+| `normalizeOtpDigits` / `isOtpComplete` / `OTP_CODE_LENGTH` | 登录 OTP（默认 6 位） |
+| `formatMetadata` | 日志 metadata 预览 |
+| `buildAdminOffsetParams` / `applyAdminOffsetParams` | 列表 **string** offset 查询（URLSearchParams）；number body 见 §5.8 |
+
+### 3.6 组件深路径
+
+发布 `exports` 已声明（可直接 deep import）：
+
+- `AdminPagination.vue` / `AdminModal.vue` / `ConfirmDialog.vue` / `ToastContainer.vue`  
+- `ConfigField.vue` / `AdminShell.vue` / `AdminLoginShell.vue` / `AdminMetadataDetail.vue`  
+
+CSS：`./styles`、`./styles/tokens.css`、`./styles/admin-primitives.css`、`./styles/login-primitives.css`  
+Recipes：`./recipes/*`
+
+---
+
+## 4. 按场景的「标准写法」
+
+### 4.1 登录成功
+
+```ts
+// Bearer
+setToken(res.token)
+router.replace(resolveAdminLoginRedirect(route.query.redirect))
+
+// Cookie
+markLoggedIn() // 写 flag；cookie 已由 Set-Cookie 完成
+router.replace(resolveAdminLoginRedirect(route.query.redirect))
+```
+
+### 4.2 列表加载失败
+
+```ts
+onError: (err) => toErrorMessage(err, t('adminXxx.loadFailed'))
+// 模板：v-if="loadError" 展示 + 重试按钮调 loadData
+```
+
+### 4.3 单行危险删除
+
+```ts
+if (!(await askConfirm(t('confirmDelete'), { danger: true, requirePhrase: 'DELETE' }))) return
+try {
+  await apiDelete(id)
+  showToast(t('deleted'), 'success')
+  await loadData()
+} catch (e) {
+  showToast(toErrorMessage(e, t('deleteFailed')), 'error')
+}
+```
+
+### 4.4 多选批量（服务端一次返回汇总）
+
+```ts
+const check = checkAdminBatchLimit(selectedIds.value, { unit: '条' })
+if (!check.ok) { showToast(check.message, 'error'); return }
+const res = await apiBatch(selectedIds.value)
+const toast = buildBatchToast(res, { mixed: t('mixed'), success: t('ok') })
+showToast(toast.message, toast.type)
+clearSelection()
+await loadData()
+```
+
+### 4.5 多选批量（只能逐条调旧 API）
+
+```ts
+const result = await runSequential(selectedItems, (row) => apiDisable(row.id))
+if (!result) return // 已在 operating
+showToast(
+  buildBatchToast(result, { mixed: t('mixed'), success: t('ok') }).message,
+  resolveBatchToastType(result),
+)
+```
+
+### 4.6 复制链接并关弹层
+
+```ts
+const ok = await copyWithToast(url, {
+  successMessage: t('linkCopied'),
+  errorMessage: t('linkCopyFailed'),
+})
+if (ok) copyLinkVisible.value = false
+```
+
+### 4.7 导出 CSV
+
+```ts
+downloadCsv(`orders-${date}.csv`, [
+  ['orderNo', 'email', 'amount'],
+  ...rows.map((r) => [r.orderNo, r.email, r.amountCents]),
+])
+// 单元格已经过 safeCsvCell；不要自己拼未转义 CSV
+```
+
+---
+
+## 5. 与三端对齐时的注意事项（实战坑）
+
+### 5.1 必须对齐的后端契约
+
+| 点 | shop 倾向 | lottery 倾向 | auth 倾向 |
+|----|-----------|-------------|-----------|
+| 成功判定 | `http-ok` | `ok-envelope` | 按接口 |
+| 错误字段 | `error` | `message` | 按接口 |
+| 认证 | 每方法 `token` 或 getToken | getToken Bearer | cookie `credentials: 'include'` |
+| 401 | 清 token + 硬跳登录 | 可能清整段业务会话 | 清 flag + 产品登出 |
+
+**工厂配错 `resultMode` 会把成功当失败或吞掉业务 `ok:false`。** 新项目先读一条真实列表响再选模式。
+
+### 5.2 有意不要用 `copyWithToast` 的路径
+
+- 开启/创建活动后：复制分享链失败时 toast 仍是「已开启/已创建」→ 保留 `writeClipboardText` + 分支成功文案。  
+- 创建后静默复制（失败不阻断）→ 空 catch + `writeClipboardText`。  
+- 前台 C 端分享 → 可用 `writeClipboardText`，不强制套件 toast 文案。
+
+### 5.3 不要抽进套件的东西
+
+- 领域 CRUD 页面、领域 API 目录  
+- OAuth / PKCE / 允许列表策略  
+- 抽奖 L3、仿冒登录、平台角色矩阵  
+- 多币种金额展示（用产品 money 库）  
+- 日期选择器、DataTable 框架、富文本  
+- 「以后可能第三个产品会用」的一次性 helper  
+
+**提取标准：** 两个产品已复制粘贴同样逻辑 → 提取；只有一个产品需要 → 留产品。
+
+### 5.4 i18n
+
+- 套件组件键用 `mergeAdminKitMessages`，避免漏 `pagination.total` 等。  
+- ConfigField 字段文案：`adminConfig.fields.<key>.*`；不要把后端自由文本当 `$t` defaultMessage（裸 `@`/`{}` 会炸解析）。  
+- 批量/复制成功失败句 **全部产品侧**；套件 `formatDefaultBatchMixedMessage` 只是零依赖中文回退。
+
+### 5.5 测试与类型
+
+- 套件：`npm test`（Vitest）+ `npm run type-check`  
+- 产品：改 reexport 或升级套件后跑本仓 `vue-tsc`  
+- 单测优先 `from '@usethink/cf-admin-fe/composables'` / `/utils`，避免根 barrel 拉 SFC  
+- `createAdminTokenSession` / flag / request 均支持注入 `storage` / 测试 double  
+
+### 5.6 封包与 dist
+
+```bash
+npm run clean    # scripts/clean-dist.mjs，防过期 d.ts
+npm run build    # clean + tsc 声明
+npm pack         # prepack → build；入口仍是 src/
+```
+
+- `files`：`src`、`dist`、`recipes`、`docs`、`README.md`、`LICENSE`  
+- **不要**手写或提交过期根 `dist/index.d.ts`  
+- 版本语义：行为兼容补丁可留在 0.2.6 文档/接线；破坏性 API 再 bump  
+
+### 5.7 monorepo paths
+
+产品 tsconfig 常见：
+
+```json
+"paths": {
+  "@usethink/cf-admin-fe": ["../../cf-admin-fe/src/index.ts"],
+  "@usethink/cf-admin-fe/*": ["../../cf-admin-fe/src/*"]
+}
+```
+
+Vite 需 `dedupe: ['vue']`，避免套件与应用两份 Vue（peer 类型/运行时分裂）。
+
+### 5.8 cf-shop 接线对照（维护用 · 非强制全量统一）
+
+> 目的：后人升级套件时知道 **shop 已经怎么接**、**哪些故意不接**。  
+> 范围仅 admin/platform foundation；**不含** storefront C 端。
+
+| 能力 | shop 现状 | 备注 |
+|------|-----------|------|
+| 会话 | `createAdminTokenSession` → `useAdminAuth` | Bearer + localStorage TTL |
+| 请求 | `createAdminRequest` / `createAdminRequestRaw` + 401 清会话 | `resultMode: 'http-ok'` 等产品约定 |
+| 路由 | `decideAdminRouteAccess` | `router/index.ts` |
+| 壳 / 登录 | `AdminShell` / `AdminLoginShell` | 产品菜单 + 登录 UI |
+| i18n | `mergeAdminKitMessages` | 中英 |
+| 样式 | kit primitives + 产品 `admin.css` | 不把 C 端视觉塞进 kit |
+| Toast / Confirm / Pagination / Modal | 产品薄 reexport 或直连 kit 组件 | `ToastContainer` 根挂一次 |
+| 表格 UX | `useTablePagination` / `useTableSelection` / `useAdminBatchOperation` reexport | |
+| 列表加载 | **17/17** admin 视图 `useAdminListLoader` | 含 isStale |
+| 错误文案 | `toErrorMessage`（via `useFormat` 再导出） | |
+| 复制 | 多数路径 `copyWithToast`；lottery 开启/创建等有意 silent/success-fallback | 见 §5.2 |
+| CSV | `downloadCsv` / `safeCsvCell` reexport | |
+| 系统配置 | `ConfigField` + 产品 `system-config-sections` | 字段文案在产品 i18n |
+| **offset 查询** | **多为 number body**：`limit`/`offset` 数字手写在 `AdminBalance` / `AdminRecharges` / `AdminVouchers` 等 filter 类型 | **不要**强行换成 `buildAdminOffsetParams`（它产出 **string**，给 URLSearchParams） |
+| **string limit/offset** | shop 几乎无 1-based 页码 → string query 列表 | **对照面在 cf-lottery**：平台审计 / 租户 / webhook / 兑换码已用 `buildAdminOffsetParams` |
+| **批量上限** | 服务端 batch：`Orders` 批量删、`Cards` 状态/删、`EmailLogs` 删、`Logs` 删 → `checkAdminBatchLimit(..., { limit: 200 })` | 后端 `z.array(...).max(200)`；**禁止**默认 20 误伤产品 |
+| 批量 UX | 逐条 `runSequential` + `resolveBatchToastType`；服务端汇总路径直接 toast | Coupons/Products 等逐条路径可按需再加 limit（产品策略） |
+| 不进 kit | 订单/支付/多币种、领域 CRUD、storefront 链接工具 | 见 §5.3 |
+
+**升级 checklist（shop）：**
+
+1. 升 `@usethink/cf-admin-fe` 后跑产品 `vue-tsc` + 相关 contract 测试。  
+2. 新增 **URLSearchParams + limit/offset 字符串** 列表 → 用 `buildAdminOffsetParams(page, limit)` 或 `applyAdminOffsetParams`。  
+3. 新增 **number** filter offset 列表 → 继续手写 `(page-1)*limit` 数字；若 ≥2 产品同形再考虑 kit number helper。  
+4. 新增服务端 `max(N)` 批量 API → `checkAdminBatchLimit(ids, { limit: N, unit })`，N 跟后端一致。  
+5. 不要为了「对齐文档示例」把 number body 改成 string query。
+
+---
+
+## 6. 新产品 Checklist（可打印）
+
+- [ ] 安装包 + peer Vue  
+- [ ] `import '@usethink/cf-admin-fe/styles'`（或 primitives）  
+- [ ] 根节点 `<ToastContainer />` 仅一次  
+- [ ] `mergeAdminKitMessages` 中英（或实际 locale）  
+- [ ] 选定 Bearer **或** Cookie，复制对应 `useAdminAuth` recipe  
+- [ ] `createAdminRequest`：`resultMode` / `errorField` / 401 /（cookie）`credentials`+`onSuccess`  
+- [ ] 路由：`decideAdminRouteAccess` + 登录页 `resolveAdminLoginRedirect`  
+- [ ] `AdminShell` 布局 + 产品菜单  
+- [ ] 登录 UI 包在 `AdminLoginShell`  
+- [ ] 第一页列表：`useAdminListLoader` + `useTablePagination` + **按契约选分页**：string query → `buildAdminOffsetParams`；number body → 手写数字 offset（见 §5.8）  
+- [ ] 多选页：`useTableSelection` + `checkAdminBatchLimit`（**`limit` 对齐后端 max**，默认 20 仅 auth 风格）+ batch toast  
+- [ ] 复制：`copyWithToast`；特殊降级才 `writeClipboardText`  
+- [ ] 错误：`toErrorMessage`  
+- [ ] 导出：`downloadCsv`  
+- [ ] （可选）系统配置：`ConfigField` + system-config-engine  
+- [ ] 产品 `vue-tsc` + 关键路径手工点一遍 401 / 登录 redirect  
+
+---
+
+## 7. 目录地图（本仓库）
+
+```
+cf-admin-fe/
+  src/
+    composables/   # 会话、请求、表格、toast、clipboard、list loader…
+    components/    # Shell / Modal / Pagination / ConfigField / …
+    utils/         # 纯函数：错误、批量、导航、query、csv、cents…
+    i18n/          # kit 消息种子 + merge
+    types/         # ConfigField 等类型
+    styles/        # tokens + primitives
+  recipes/         # 复制即用模板（非运行时依赖）
+  docs/            # 本说明书 + 差距分析
+  tests/           # 公共 API 与行为契约
+  scripts/clean-dist.mjs
+```
+
+---
+
+## 8. 常见误区速查
+
+| 误区 | 正确做法 |
+|------|----------|
+| 把业务页面放进套件「图省事」 | 业务永在产品；套件只 foundation |
+| Cookie 产品硬套 Bearer TTL | 用 `createAdminFlagSession` |
+| `buildAdminOffsetParams({ page, pageSize })` | 位置参数 `(page, limit)` |
+| shop number offset 强行套 string helper | number body 手写；string 仅 URLSearchParams（见 §5.8） |
+| 批量 `checkAdminBatchLimit` 不传 `limit` 却对接 max(200) API | 显式 `{ limit: 200 }`，默认 20 是 auth 风格 |
+| 列表不写 `isStale` | 快翻页会把旧响应写进新页 |
+| 登录探测 token 触发 401 清会话 | 该次请求 `redirectOnUnauthorized: false` |
+| `copyText` + 无条件 success toast | 改 `copyWithToast` |
+| 用套件 cents 函数做多币种账本 | 产品 money 库 |
+| 根 barrel 导入导致 vitest 挂 SFC | 子路径 `/composables` `/utils` |
+| 提交过期 dist | `clean` + `prepack` 生成 |
+| 为第三种日期库包一层进套件 | 产品自选轻量库 |
+
+---
+
+## 9. 能力边界声明（避免幻觉）
+
+本套件 **当前没有**、也不计划在未经验证前加入：
+
+- 通用 DataTable / 虚拟滚动表格框架  
+- 日期时间选择器、级联、树、上传套件  
+- OAuth/PKCE 完整流程组件  
+- 权限指令 / RBAC 组件  
+- 图表、富文本、表单 schema 引擎  
+- 与后端共享的 RPC/SDK  
+- **number** 版 `buildAdminOffsetParams`（观察期，见 001 **R5** / §5.8 升级清单第 3 条）  
+- 强迫旧审计页迁 `AdminMetadataDetail`（组件留给**新页**）
+
+若新产品需要上述能力：在产品内选型；当 **≥2 个 CF 管理端** 出现可复用的同一薄封装时，再提案进入 `cf-admin-fe`。
+
+---
+
+## 10. 封版与部署注意（0.2.6）
+
+### 10.1 本包如何被产品消费
+
+| 方式 | 说明 |
+|------|------|
+| monorepo `file:../cf-admin-fe` | **当前 shop / lottery / auth 默认**；部署机需能读到同级源码目录，或先 `npm pack` 再装 tgz |
+| registry / tgz | `npm pack` → `prepack` 会 `clean`+`build` 生成 `dist/*.d.ts`；运行时仍以 **`src/`** 为准 |
+
+**不要**只拷 `dist/` 上线；Vue SFC 与 TS 源在 `src/`。
+
+### 10.2 封版前自检（kit）
+
+```bash
+npm test              # 预期全绿（约 122）
+npm run type-check
+npm run build         # 生成 dist 声明；可选 npm pack 干跑
+```
+
+### 10.3 三端接线冻结摘要（部署对照）
+
+| 产品 | 会话 | 本版关键接线 | 部署前至少 |
+|------|------|--------------|------------|
+| **cf-shop** | Bearer | 17 列表 loader；服务端 batch `checkAdminBatchLimit({ limit: 200 })`；number offset **手写** | `type-check:frontend` + `frontend:build` |
+| **cf-lottery** | Bearer | 平台 3 页 + 兑换码 `buildAdminOffsetParams` | `type-check:frontend` + `frontend:build` |
+| **cf-auth** | Cookie flag | `checkAdminBatchLimit` 默认 20 / 硬删显式 limit；**未改**默认 20 | `frontend` type-check + `build:frontend` + 根 `verify` |
+
+升级套件后：**先**在 monorepo 跑通上表，再推生产。shop 批量 max 与 auth 默认 20 **不要**互相「统一」成同一个魔法数。
+
+### 10.4 明确不进本封版
+
+R5 观察项（number offset helper、silent copy 选项、cursor helper、batch profile 工厂）、旧页迁 `AdminMetadataDetail`、领域 CRUD、C 端 storefront。
+
+---
+
+## 11. 修订记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-08-05 | 初版：对齐 0.2.6 全量公开 API、双会话、列表/复制/批量/封包注意事项；配套修正 `list-page.snippet` 签名与 admin 复制双反馈 |
+| 2026-08-05 | §5.8 **cf-shop 接线对照**；lottery 四页 string offset 接 `buildAdminOffsetParams`；shop 四类服务端 batch 接 `checkAdminBatchLimit({ limit: 200 })` |
+| 2026-08-05 | **P1–P3 文档收口（无 API）**：README/recipes/001/002 对称 string vs number offset、batch limit 跟后端 max、MetadataDetail 新页优先、R5 观察期 |
+| 2026-08-05 | **§10 封版与部署注意**；三端验证全绿后的冻结摘要 |
+| 2026-08-05 | **AdminShell 用户区上移顶栏右上**（省侧栏高度；`#sidebar-footer` 可选；窄屏可藏用户名） |
+
+**维护约定：** API 变更时同步改本文件、根 README 公开 API 节、`recipes/README.md` 与 `tests/public-api.test.ts`。说明书只描述已实现行为；示例代码须与 `src/` 签名一致。