@usethink/cf-admin-fe 0.1.1 → 0.2.8

package/docs/003_cf-admin-fe/346/236/201/350/207/264/345/214/226/346/226/271/346/241/210/344/270/216/345/217/226/350/210/215_2026-08-05.md

@@ -0,0 +1,332 @@
+# @usethink/cf-admin-fe 极致化方案与取舍
+
+> **版本锚点：** 以 `package.json` 为准（**0.2.8** 已落地 §9.1 P0 三件套；起草基线为 0.2.7）  
+> **日期：** 2026-08-05（P0 落地修订同日）  
+> **性质：** 路线图与决策备忘（**不是**待办全开的 backlog；**不是**对外 API 说明书）  
+> **配套：** [`002` 使用说明书](./002_cf-admin-fe使用说明书与注意事项.md) · [`001` 提取差距结案](./001_cf-admin-fe提取差距分析报告_2026-08-05.md) · 根 [`README.md`](../README.md) · [`recipes/README.md`](../recipes/README.md)
+
+---
+
+## 0. 文档怎么用
+
+| 读者问题 | 读哪里 |
+|----------|--------|
+| 怎么接套件、有哪些 API | **002** + README + recipes |
+| 当初抽了什么、故意不抽什么 | **001**（结案，勿当未完成清单） |
+| **下一步该不该做、做到什么程度** | **本文 003** |
+| 某条观察项（如 number offset）何时可提 API | 本文 §5.2 + 001 **R5** + 002 §5.8 / 不做清单 |
+
+**维护约定：**
+
+- 实施完成后，把对应条目改成「已落地（版本号）」，**不要**删决策理由。  
+- 新想法先对照 §1 定位与 §2 提取纪律；通不过则记入 §7「冻结 / 触发条件」，勿直接开码。  
+- 本文可随迭代修订；**破坏性结论变更**须在文末修订表留一行。
+
+---
+
+## 1. 核心定位（一切极致化的前提）
+
+### 1.1 一句话
+
+`@usethink/cf-admin-fe` 是 **CF 产品族 Vue 3 管理端「业务模式」基础套件**，不是通用 UI 组件库，不是业务中台，不是 Worker/API 包。
+
+### 1.2 已验证边界（0.2.x 守住的）
+
+| 是 | 不是 |
+|----|------|
+| 壳（AdminShell / LoginShell）、表格 UX、分页/选择/确认/Toast | Element / Ant 式通用控件集 |
+| 双会话工厂（Bearer token / Cookie+flag）+ request 旋钮 | 产品域 `api/admin.ts` 方法全集 |
+| ConfigField、列表 loader、错误/批量助手、offset **string** 查询助手 | 订单/抽奖/OAuth/RBAC 页面 |
+| i18n **种子** + recipes 复制清单 | 「一条命令生成完整业务后台」的产品本身 |
+| 在 **≥2 真实消费方**（或第 3 路径验证出的通用缺口）后提取 | 为对齐单一产品而抹平特殊性 |
+
+**线上验证面（起草时）：**
+
+| 产品 | 会话 | 在套件中的角色 |
+|------|------|----------------|
+| **cf-shop** | Bearer | 主路径参考 |
+| **cf-lottery** | Bearer + 平台/仿冒胶水 | Bearer 扩展；布局可有产品自有部分 |
+| **cf-auth** | Cookie + flag | **检验 cookie 路径**；禁止把 OAuth/业务页抽进 kit |
+
+### 1.3 「极致」在本仓库的定义
+
+对 solo / 小团队维护者，**极致 = 减少摩擦 + 提高改动安全感**，**不是**功能表面积最大化。
+
+优先序：
+
+1. **改组件不踩雷**（契约可测）  
+2. **重复逻辑有单一真相**（如 i18n fallback）  
+3. **体积与依赖不偷偷膨胀**  
+4. **提取纪律可执行**（≥2 同形，写进政策）  
+5. 仅在摩擦真实变大时，再上脚手架 / 文档站 / 更深工厂  
+
+---
+
+## 2. 治理纪律（建议升格为公开政策）
+
+以下三条应与 001/002 一致，并在评审新 PR 时当作硬门禁：
+
+1. **不进** Element/Ant 式通用组件库路线。  
+2. **不抽** 仅单产品出现的页面编排（业务列定义、域 CRUD、产品特有批量语义）。  
+3. **提取门槛：**  
+   - 同形模式出现在 **≥2 个消费方**，或  
+   - **同一产品 ≥3 处**稳定复制且契约不再摇摆，或  
+   - **第 3 条路径**（如 cookie）验证出的通用缺口。  
+
+**禁止：** 为「看起来整齐」而预抽；为「对齐 shop」而抹平 auth。
+
+---
+
+## 3. 现状快照（相对极致化议题）
+
+| 维度 | 起草时实况 | 含义 |
+|------|------------|------|
+| 测试 | ~27 个测试文件，**composable / utils 为主**；**8 个 `.vue` 几乎无渲染测** | 模板/插槽回归靠手测，套件信任短板 |
+| 交付形态 | `exports` 指向 **`src/`**；`build` 主要产 **`.d.ts`**；CSS 在 `src/styles` | 体积 KPI 不能按「单一 runtime bundle」幻想来设计 |
+| i18n | `AdminShell.tFallback` 与 `ConfigField.tSafe` **同构重复**；部分组件模板直接 `$t` | 收口 ROI 高、对外行为可兼容 |
+| 请求层 | `createAdminRequest` 已有 `resultMode` / `credentials` 等；产品仍自写 `api/*` | 实例级配置已够用；路径级 registry 证据不足 |
+| 分页 | `buildAdminOffsetParams` **仅 string**（URLSearchParams）；number body 手写 | 与 001 **R5** / 002 一致，默认不扩 API |
+| 样式 | `.table-wrap` 已在 **0.2.7** 去掉 `scrollbar-gutter: stable`（消除无溢出右侧缺口） | 表格以视觉对齐优先；弹层/卡片列表仍可 stable |
+| 接入 | recipes **清单式复制**，无官方脚手架 | 3 内部消费方阶段可接受 |
+
+---
+
+## 4. 分层裁决总表
+
+图例：**采纳** = 应排期；**轻量采纳** = 做，但改写目标；**暂缓** = 有条件再开；**冻结** = 默认不做。
+
+| 层级 | 议题 | 裁决 | 一句话理由 |
+|------|------|------|------------|
+| **P0** | 组件 SFC 契约测试 | **已落地（0.2.8）** | `tests/AdminShell|ConfigField|AdminMetadataDetail.test.ts` + happy-dom |
+| **P0** | 体积 / 依赖监控 | **已落地（0.2.8）** | `scripts/size-report.mjs` + `size-baseline.json`；`size-report` / `:write` / `:check` |
+| **P0** | 统一 i18n fallback（`tKit` 等） | **已落地（0.2.8）** | `resolveAdminT` / `tKit`；Shell + ConfigField 收口 |
+| **P1** | `createAdminApi` 路径 resultMode 工厂 | **暂缓** | 第二真相源；现主流是一产品一 request 配置 |
+| **P1** | `create-cf-admin` 脚手架 | **后置** | 模板双维护税 > 当前 onboarding 痛 |
+| **P1** | VitePress 组件演示站 | **冻结（现阶段）** | 卖的是模式套件；002 已够内部用 |
+| **P2** | number offset helper | **观察（R5）** | 先审计同形，默认不提 API |
+| **P2** | Light 主题全集 | **冻结** | 产品族暗色；变量可覆盖即可 |
+| **P2** | dist 过期「玄学」强化 | **低优** | prepack clean 对发布已够 |
+| 架构 | AdminShell 注入式侧栏 | **有第二行为再做** | 现硬依赖 `useAdminSidebar` 合理 |
+| 架构 | 源码交付改 dist-only runtime | **需单独 RFC** | 改变调试与消费模型，非默认极致 |
+
+---
+
+## 5. P0 — 高影响、值得做（细则）
+
+### 5.1 组件级测试（SFC / 契约测试）
+
+**问题：** composable 测得再满，**插槽条件、cents 编辑、元数据安全回退**仍可能被「只改模板」弄坏。
+
+**目标重写（重要）：**
+
+- 要的是 **行为契约**（渲染条件、emit、边界 props），不是行覆盖率表演。  
+- 与产品仓「读源码 contract」互补：  
+  - **kit 内 SFC 测** = 套件契约  
+  - **产品 contract** = 接线/业务约定  
+
+**建议优先级：**
+
+| 优先级 | 组件 | 覆盖要点 |
+|--------|------|----------|
+| 必做 | `AdminShell` | `#sidebar-footer` 有/无才渲染；`showUser` / `showLogout`；`#header-actions` 与用户区相对位置；`navigate` / `logout` emit；窄屏名称可藏（若可稳定断言） |
+| 必做 | `ConfigField` | cents 往返；枚举空校验；sensitive 占位；status 文案（saving/saved/error） |
+| 应做 | `AdminMetadataDetail` | 空、非法结构、循环/过深时的安全回退展示 |
+| 可后做 | `AdminPagination` / `ConfirmDialog` / `ToastContainer` | 逻辑多在 composable 已测则 **薄测** 即可 |
+| 低 | `AdminLoginShell` / `AdminModal` | 结构 + 关键 a11y 点；少绑 class 字符串 |
+
+**基建建议：** Vitest + `@vue/test-utils` + **happy-dom**（相对 jsdom 更轻）。  
+**反模式：** 为冲 80% 组件行覆盖写脆测试；断言大段 HTML 快照无说明。
+
+**预期发版形态：** 行为兼容 → **0.2.x patch**（如与 i18n 收口同发 0.2.8）。
+
+---
+
+### 5.2 构建产物与「体积」监控（轻量版）
+
+**问题重定义：**  
+本包 **不是**「npm 只下 dist JS、运行全走打包产物」。消费者 Vite 直接编 **`src/*.vue` + CSS`**；`tsc` 的 `dist/` 以声明为主。  
+因此「打一个假入口把全部 subpath 打成一个 app 再 gzip」可以做实验，但 **不宜当主 KPI**，否则会优化错对象。
+
+**建议监控（按优先级）：**
+
+1. **`src/styles/*.css` raw / gzip 体积**（`admin-primitives.css` 是大头之一）  
+2. **按 exports 子路径的源码规模**（composables / components / utils / i18n：文件数、近似 LOC）——防 utils 黑洞  
+3. **依赖门禁：** 除 `peerDependencies`（`vue`；可选 `vue-i18n`）外，**禁止悄悄增加 runtime dependency**（比多 2KB CSS 更致命）  
+4. 可选：对 **纯 TS、无 SFC** 的子树做 esbuild metafile 抽样  
+
+**CI / 脚本形态：**
+
+- `scripts/size-report.mjs`（或同等）输出可读报告 + 可提交的 baseline JSON  
+- **仅在明显膨胀时失败**（例如 CSS gzip +15% 且无说明），避免每次微改必红  
+
+**明确不做（现阶段）：** 把套件改成「唯一预打包 runtime bundle」作为默认交付——除非另开 RFC 并改所有消费方调试习惯。
+
+---
+
+### 5.3 统一 i18n 辅助（P0 中 ROI 最高、风险最低）
+
+**事实：** `AdminShell` 的 `tFallback` 与 `ConfigField` 的 `tSafe` 同为：
+
+`getCurrentInstance()` → `proxy.$t` → 失败或 key 原样则 **fallback**（ConfigField 另支持 params）。
+
+**建议 API 形态（实现时二选一，文档写死）：**
+
+| 形态 | 适用 | 注意 |
+|------|------|------|
+| `tKit(key, fallback, params?)` 在 **setup 内** 调用 | 组件 script | 依赖 `getCurrentInstance`，勿在模块顶层调用 |
+| 纯函数 `resolveAdminT(proxy, key, fallback, params?)` | 可单测、可非 setup | 组件内一行薄封装 |
+
+**策略必须统一（避免半套）：**
+
+- **A：** 套件组件展示文案 **全部** 走 `tKit` / `resolveAdminT`（无 vue-i18n 也能跑中文 fallback）；或  
+- **B：** 文档强制消费方 `mergeAdminKitMessages`，模板可用 `$t`，但 **kit 内仍建议统一走 tKit** 以免漏 merge 时白屏/露 key。  
+
+推荐 **A 为主**（与「vue-i18n 为 optional peer」一致）。
+
+**范围：** 先收 `AdminShell`、`ConfigField`，再扫其他组件是否有第三份拷贝。  
+**发版：** 对外行为不变 → **patch**。
+
+---
+
+## 6. P1 — 中等影响，看 ROI
+
+### 6.1 通信协议：`createAdminApi` 路径级工厂 — **暂缓**
+
+**设想：** 按 path 注册 `resultMode` / `errorField`，调用时自动匹配。
+
+**暂缓理由（硬）：**
+
+- 现抽象已在 **`createAdminRequest` 实例级**；shop / auth / lottery 主流是 **一产品一配置**，不是「一 path 一 envelope」为主矛盾。  
+- 路径表会成为 **第二份路由真相**，与产品 `api/admin.ts` 双维护。  
+- 强类型 path→响应要么弱（近 `any`），要么维护税接近 OpenAPI。  
+
+**触发条件（同时满足再评估）：**
+
+- ≥2 产品在 **同一 request 实例内** 出现多 envelope，且手写分支重复；  
+- 配置表能明显减少重复，而不是只是搬家。  
+
+**更贴定位的替代：** 强化 recipes 中「如何组织 `api/admin.ts`」；必要时只加 **小纯函数**（如 envelope 断言），不建 path registry。
+
+---
+
+### 6.2 准入脚手架 `create-cf-admin` — **后置**
+
+**痛点真实，但养模板仓库的成本更高：** kit 每个 API 变更要 **双改模板**，solo 最易腐烂。
+
+**更极致、更便宜的中间态：**
+
+1. recipes 保持权威清单；  
+2. 可选 **`examples/minimal`**（可运行的最小壳，仍非业务后台）；  
+3. 可选 **检查脚本**（是否 import styles、是否 merge i18n 种子）——**验证**优于**生成**。  
+
+**触发条件：** 第 4 个消费方（尤其外部）或公开 onboarding 压力明显，再开脚手架。
+
+---
+
+### 6.3 VitePress 文档站 — **现阶段冻结**
+
+- 对内：002 + recipes 已是高水位。  
+- 对外：本包卖 **模式与纪律**，不是组件货架；Playground 维护税高。  
+
+**例外：** 若只需 ConfigField / AdminShell **静态一页 demo**，可放 recipes 或单页，**不上**完整文档站基建。
+
+---
+
+## 7. P2 与架构 — 低优先 / 触发后再做
+
+### 7.1 number 版 offset helper（R5）
+
+- 说明书已标明：string 给 `URLSearchParams`；**number body 手写**。  
+- shop 全仓大量 `limit/offset` **不等于** 前端构造参数「同形」；服务层分页与 admin API 拼装要分开看。  
+
+**允许动作：** 审计 `cf-shop/frontend`（及 lottery）里 number body 分页构造；若 **稳定同形 ≥2 处跨产品或 ≥3 处单产品**，再提 `buildAdminOffsetBody` 之类。  
+**默认：** 不增 API；结论写回 001 R5 / 002。
+
+### 7.2 CSS 主题（Light）
+
+- 产品族管理端 **暗色**；无第二套视觉 QA 面需求。  
+- **保持** CSS 变量可被消费方覆盖即可；kit **不维护**官方 light 主题包。
+
+### 7.3 dist 过期防护
+
+- `prepack` → clean → build 对 **发布** 足够。  
+- IDE 误解析：以 `exports`→`src` 为准；不必为开发体验叠加复杂 outDir 策略。
+
+### 7.4 AdminShell ↔ `useAdminSidebar`
+
+- 三家断点一致时，**硬依赖是合理默认**，不是缺陷。  
+- **注入整棵侧栏状态机** = 有第二套断点/行为时再做。  
+- 现阶段扩展优先靠 **已有插槽**（`#nav` / `#nav-extra` / `#sidebar-footer` / `#header-actions` / `#banner`）。
+
+### 7.5 模板中的 `$t`
+
+- 根因是 **optional `vue-i18n`**，不是缺 DI 容器。  
+- 用 **统一 tKit + merge 种子契约** 收敛，优于「注入 i18n 实例」大重构。
+
+---
+
+## 8. 摩擦点：愿景 vs 可执行极致
+
+| 摩擦点 | 常见「极致」想象 | **本仓库建议的极致** |
+|--------|------------------|----------------------|
+| 新产品接入 | `npx create-cf-admin` | recipes + 可选 minimal example + 可选检查脚本 |
+| 改套件后验证 | 全自动消费方 monorepo CI | **kit SFC 契约测** + 发版前三仓 `vue-tsc`（可先脚本化） |
+| 组件行为确认 | 读源码 / 全量快照 | **高风险 SFC 行为测** |
+| 升级影响 | 类型断崖吓阻 | **0.2 尽量兼容**；破坏性进 0.3；changelog 记行为 |
+| 是否该提取 | 自动模式挖掘工具 | **人工 ≥2 + R 观察列表**（工具 ROI 过低） |
+
+---
+
+## 9. 推荐落地路线图
+
+### 9.1 近端 — **0.2.8 三件套（已完成）**
+
+1. ~~抽取 **`tKit` / `resolveAdminT`**~~ → `src/utils/i18n.ts`；Shell / ConfigField 收口；`tests/i18n-resolve.test.ts`。  
+2. ~~SFC 测试基建 + 契约测~~ → vitest `happy-dom`；AdminShell / ConfigField / AdminMetadataDetail。  
+3. ~~**轻量 size-report**~~ → `npm run size-report` / `size-report:write` / `size-report:check`。  
+
+**刻意不碰（仍有效）：** path 级 `createAdminApi`、脚手架、VitePress、双主题、注入式侧栏。
+
+### 9.2 中端（有余力）
+
+4. 发版辅助脚本：`type-check` + `test` + `size-report` + 提示消费方 bump。  
+5. number offset **审计笔记** 写入 R5（有同形再 API，无则结案「维持手写」）。  
+6. recipes「最小接入」补强（仍非脚手架）。
+
+### 9.3 冻结直到触发条件
+
+| 项 | 触发条件（示例） |
+|----|------------------|
+| `createAdminApi` 路径表 | §6.1 条件 |
+| `create-cf-admin` | 第 4 消费方或外部 onboarding 压力 |
+| VitePress | 明确对外品牌/演示需求且有维护带宽 |
+| Light 主题 | 真实产品浅色管理端需求 |
+| 注入式侧栏 | 第二套断点/行为无法用插槽解决 |
+| dist-only runtime | 书面 RFC + 消费方迁移窗 |
+
+---
+
+## 10. 与「极致」容易打架的三条钉死原则
+
+1. **源码交付是优势**（可跳进 SFC 调试）；勿为「像标准组件库」默认改成仅 dist 运行时。  
+2. **测试的极致是契约稳定**，不是测试文件数量或行覆盖率。  
+3. **每多一个工厂 / 脚手架 / 主题，就多一条要与 shop·lottery·auth 同步的真理之源**；在 3 仓阶段，**少真相源才是极致**。
+
+---
+
+## 11. 总结（给决策者的一页）
+
+- **定位与 ≥2 提取纪律：全盘坚持，并当 PR 门禁。**  
+- **P0 三件套已在 0.2.8 落地**（契约测 + i18n 收口 + size-report）。  
+- **API 路径工厂、脚手架、文档站、双主题：远见可记，默认冻结。**  
+- **R5 number offset：可审计，不可默认加 API。**  
+- **下一列车：** 中端（发版辅助脚本 / R5 审计笔记 / recipes 最小接入），仍不扩冻结项。
+
+---
+
+## 12. 修订记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-08-05 | 初版：基于 0.2.7 现状与消费方（shop / lottery / auth）对照；固化 P0/P1/P2 裁决、触发条件与 0.2.8 三件套路线；明确极致定义=减摩擦+安全感而非扩面 |
+| 2026-08-05 | **0.2.8 P0 落地**：`tKit`/`resolveAdminT`、SFC 契约测、size-report；§4/§9.1/§11 状态同步 |

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@usethink/cf-admin-fe",
-  "version": "0.1.1",
-  "description": "Vue 3 frontend admin kit for CF product family — composables, shell components, design tokens (FE only; not cf-core)",
+  "version": "0.2.8",
+  "description": "Vue 3 frontend admin kit for CF product family — composables, shell, ConfigField, list loader, login chrome, request/token/raw factories, error/batch helpers, system-config engine, nav helpers, i18n seeds, recipes (FE only; not cf-core)",
   "type": "module",
   "private": false,
   "files": [
     "src",
     "dist",
-    "README.md"
+    "recipes",
+    "docs",
+    "README.md",
+    "LICENSE"
   ],
   "main": "./src/index.ts",
   "module": "./src/index.ts",
@@ -26,14 +29,32 @@
       "types": "./src/components/index.ts",
       "import": "./src/components/index.ts"
     },
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "import": "./src/utils/index.ts"
+    },
+    "./types": {
+      "types": "./src/types/index.ts",
+      "import": "./src/types/index.ts"
+    },
+    "./i18n": {
+      "types": "./src/i18n/index.ts",
+      "import": "./src/i18n/index.ts"
+    },
     "./styles": "./src/styles/index.css",
     "./styles/tokens.css": "./src/styles/tokens.css",
     "./styles/admin-primitives.css": "./src/styles/admin-primitives.css",
+    "./styles/login-primitives.css": "./src/styles/login-primitives.css",
     "./package.json": "./package.json",
     "./components/AdminPagination.vue": "./src/components/AdminPagination.vue",
     "./components/AdminModal.vue": "./src/components/AdminModal.vue",
     "./components/ConfirmDialog.vue": "./src/components/ConfirmDialog.vue",
-    "./components/ToastContainer.vue": "./src/components/ToastContainer.vue"
+    "./components/ToastContainer.vue": "./src/components/ToastContainer.vue",
+    "./components/ConfigField.vue": "./src/components/ConfigField.vue",
+    "./components/AdminShell.vue": "./src/components/AdminShell.vue",
+    "./components/AdminLoginShell.vue": "./src/components/AdminLoginShell.vue",
+    "./recipes/*": "./recipes/*",
+    "./components/AdminMetadataDetail.vue": "./src/components/AdminMetadataDetail.vue"
   },
   "sideEffects": [
     "**/*.css"
@@ -47,7 +68,10 @@
     }
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "@vitejs/plugin-vue": "^5.2.1",
+    "@vue/test-utils": "^2.4.11",
+    "happy-dom": "^20.11.1",
     "typescript": "^5.7.2",
     "vite": "^6.0.0",
     "vitest": "^3.0.0",
@@ -55,10 +79,15 @@
     "vue-tsc": "^2.1.10"
   },
   "scripts": {
-    "type-check": "tsc --noEmit && vue-tsc --noEmit -p tsconfig.json",
+    "type-check": "tsc --noEmit -p tsconfig.build.json && vue-tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "build": "tsc -p tsconfig.build.json"
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "clean": "node scripts/clean-dist.mjs",
+    "size-report": "node scripts/size-report.mjs",
+    "size-report:write": "node scripts/size-report.mjs --write",
+    "size-report:check": "node scripts/size-report.mjs --check"
   },
   "keywords": [
     "admin",

package/recipes/AdminLayout.vue

@@ -0,0 +1,73 @@
+<template>
+  <!--
+    RECIPE — 产品 AdminLayout 外壳。
+    将 menuItems + brand 替换为产品的 i18n / 配置。
+    可选插槽：#nav-extra（平台链接）、#banner（仿冒登录）、#header-actions（语言，在顶栏用户信息左侧）。
+    用户头像/名称/退出默认在顶栏右上；侧栏底默认不占位（菜单多时省高）。
+    若需自定义侧栏底：#sidebar-footer（有内容才渲染）。
+  -->
+  <AdminShell
+    :brand="brand"
+    :menu-items="shellMenuItems"
+    :current-name="currentName ?? null"
+    :page-title="pageTitle"
+    :user-name="t('adminLayout.admin')"
+    @logout="handleLogout"
+    @navigate="onNavClick"
+  >
+    <template #header-actions>
+      <!-- 产品：语言选择、环境徽标等（出现在用户信息与退出左侧） -->
+      <slot name="header-actions" />
+    </template>
+
+    <RouterView v-slot="{ Component }">
+      <transition name="admin-fade" mode="out-in">
+        <component :is="Component" />
+      </transition>
+    </RouterView>
+  </AdminShell>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { useI18n } from 'vue-i18n'
+import { AdminShell, type AdminShellMenuItem } from '@usethink/cf-admin-fe/components'
+import { useAdminAuth } from '@/composables/useAdminAuth'
+import { useToast } from '@/composables/useToast'
+
+const route = useRoute()
+const router = useRouter()
+const { t } = useI18n()
+const { clearToken } = useAdminAuth()
+const { showToast } = useToast()
+
+/** PRODUCT: 品牌标题 */
+const brand = computed(() => t('adminLayout.title'))
+
+/** PRODUCT: 替换为真实菜单 */
+const menuItems = computed(() => [
+  { name: 'AdminDashboard', to: '/admin', label: t('adminLayout.title'), icon: '📊' },
+  // { name: 'AdminOrders', to: '/admin/orders', label: '…', icon: '📋' },
+])
+
+const shellMenuItems = computed<AdminShellMenuItem[]>(() => menuItems.value)
+
+const currentName = computed(() => route.name as string | undefined)
+
+const pageTitle = computed(() => {
+  const item = menuItems.value.find((m) => m.name === currentName.value)
+  return item?.label || t('adminLayout.title')
+})
+
+function onNavClick(to: string) {
+  if (route.fullPath === to) return
+  router.push(to)
+}
+
+function handleLogout() {
+  clearToken()
+  showToast(t('adminLayout.loggedOut'), 'success')
+  router.replace('/admin/login')
+}
+</script>

package/recipes/README.md

@@ -0,0 +1,131 @@
+# Recipes — 复制到新的 CF 管理后台前端
+
+这些文件是**起点模板**，不是运行时导入。将它们复制（或重新导出）到你的产品 `src/` 目录下，然后补齐产品专属部分（菜单、领域 API 方法、登录 UI）。
+
+**完整用法、注意事项、能力榨干清单：** 见 [`docs/002_cf-admin-fe使用说明书与注意事项.md`](../docs/002_cf-admin-fe使用说明书与注意事项.md)。  
+**套件下一步该做什么 / 明确不做：** 见 [`docs/003_cf-admin-fe极致化方案与取舍_2026-08-05.md`](../docs/003_cf-admin-fe极致化方案与取舍_2026-08-05.md)（路线图，非本 recipes 步骤替代）。
+
+## 推荐复制顺序
+
+| 步骤 | Recipe | 产品路径（示例） |
+|---|---|---|
+| 1 | `reexports/` | `src/composables/*`、`src/components/*`、`src/lib/*` |
+| 2a | **Bearer：** `useAdminAuth.shop.ts` | `src/composables/useAdminAuth.ts` |
+| 2b | **Cookie：** `useAdminAuth.cookie.ts` | 同上 — 使用 `createAdminFlagSession` |
+| 3a | **Bearer：** `useAdminRequest.ts` | `src/composables/useAdminRequest.ts`（或 `api/admin.ts`） |
+| 3b | **Cookie：** `useAdminRequest.cookie.ts` | `credentials: 'include'` + `onSuccess` 标志修复 |
+| 4 | `AdminLayout.vue` | `src/views/AdminLayout.vue` |
+| 5 | `router-guard.snippet.ts` | 粘贴到 `src/router/index.ts`（Bearer 用 `hasToken`；cookie 产品可在**产品内**添加健康探测） |
+| 6 | `i18n-merge.snippet.ts` | 粘贴到 `src/i18n/index.ts` |
+| 7 | 样式 | `import '@usethink/cf-admin-fe/styles'` **或** `@import` 基础样式（+ 登录 CSS） |
+| 8 | 应用外壳 | 在应用根节点挂载一次 `ToastContainer` |
+| 9 | 登录 | 用 `AdminLoginShell` 包裹**产品**表单；用 `resolveAdminLoginRedirect` 处理 `?redirect=` |
+| 10 | 列表页 | 见 `list-page.snippet.ts`：`useAdminListLoader` + 分页/多选 + `toErrorMessage` / `copyWithToast`；**先确认**后端是 string query 还是 number body offset |
+
+### 两种一等会话模型
+
+| 模型 | 工具包工厂 | 请求 | 实际参考 |
+|---|---|---|---|
+| Bearer JWT | `createAdminTokenSession` | `getToken` + 可选 Bearer | **cf-shop**、**cf-lottery** |
+| Cookie + 本地标志 | `createAdminFlagSession` | `credentials: 'include'`，可选 `onSuccess` 修复 | **cf-auth** |
+
+Cookie 产品**不应**被强制套用 token TTL / 密码表单。它们的特性（OAuth、健康探测、登出 cookie）留在产品侧；工具包只提供标志存储 + 请求工厂 + 外壳 UI。
+
+## 不要放入工具包 / 不要按领域复制
+
+- 领域页面（`views/admin/*` 业务 CRUD）
+- 领域 API 方法目录
+- 抽奖仿冒登录 / 平台角色（产品 L3）
+- Better Auth / OAuth / PKCE **流程**和允许列表策略（产品）
+- 多币种 / 订单状态映射
+- 通用组件（日期选择器、级联选择、树、富文本）— 产品自选轻量库
+- 一次性产品辅助函数“以防将来共享”
+
+## 导入风格
+
+产品重新导出时优先使用**子路径**导入，这样 Vitest/node 不会解析根 SFC barrel 文件：
+
+```ts
+from '@usethink/cf-admin-fe/composables'
+from '@usethink/cf-admin-fe/utils'
+from '@usethink/cf-admin-fe/components/ConfigField.vue'
+from '@usethink/cf-admin-fe/i18n'
+```
+
+## 错误 / 批量纯辅助函数（0.2.6+）
+
+```ts
+import {
+  toErrorMessage,
+  buildBatchToast,
+  resolveBatchToastType,
+  checkAdminBatchLimit,
+} from '@usethink/cf-admin-fe/utils'
+
+// catch
+showToast(toErrorMessage(e), 'error')
+// 列表 loader
+onError: (err) => toErrorMessage(err, t('…loadFailed'))
+
+// 服务端批量响应 { success, failed }
+const toast = buildBatchToast(res, {
+  mixed: '完成：成功 {success}，失败 {failed}',
+  success: '已处理 {count} 条',
+})
+showToast(toast.message, toast.type)
+
+// 或保留 vue-i18n 文案，只复用成功/失败色调：
+showToast(t('…', counts), resolveBatchToastType(counts))
+
+// POST 前多选上限
+// 默认 20 = auth / docs 风格；后端若 z.array.max(200) 必须传 limit: 200
+const limitCheck = checkAdminBatchLimit(ids, { unit: '人' })
+// shop 示例：checkAdminBatchLimit(ids, { limit: 200, unit: '单' })
+if (!limitCheck.ok) {
+  showToast(limitCheck.message, 'error')
+  return
+}
+```
+
+不要把业务成功文案或硬删除策略用语放进套件——只放纯形状。  
+**`limit` 必须与后端单次批量 max 一致**，默认 20 不是「所有 CF 产品的真理」。
+
+## 列表 limit / offset（string vs number）
+
+| 形态 | 工具 | 参考产品 |
+|---|---|---|
+| `URLSearchParams` / query：`limit`、`offset` 为 **字符串** | `buildAdminOffsetParams(page, limit)` 或 `applyAdminOffsetParams` | cf-lottery 平台审计、租户、webhook、兑换码 |
+| 类型化 filter / body：`limit`、`offset` 为 **数字** | **手写** `(page - 1) * limit`；**不要**套 string helper | cf-shop 余额 / 充值 / 代金券等 |
+| Cursor | 产品自管 | shop 部分订单/日志 |
+
+`buildAdminOffsetParams` 的返回值是 `{ limit: string; offset: string }`，塞进需要 `number` 的 TypeScript filter 会类型错误或静默把数字变成字符串——属于误用，不是「再抽一个兼容层就能糊弄过去」。
+
+完整对照与升级清单：`docs/002` **§5.8**。
+
+## 复制 + toast（0.2.6+）
+
+```ts
+import { copyWithToast } from '@usethink/cf-admin-fe/composables'
+// 或产品 reexport：@/composables/useClipboard
+
+const ok = await copyWithToast(text, {
+  successMessage: t('…copySuccess'),
+  errorMessage: t('…copyFailed'),
+})
+if (ok) {
+  // 可选：关弹层、清选中
+}
+```
+
+- **`copyWithToast`**：剪贴板 + 全局 toast（管理端列表/详情主路径）
+- **`copyText(text, event)`**：按钮内 ✅/❌（前台交付明细等，不抢 toast）
+- **`writeClipboardText`**：仅写入，由调用方自管反馈（例如创建成功后静默复制链接）
+
+## 列表页骨架
+
+见 [`list-page.snippet.ts`](./list-page.snippet.ts)（含形态 A/B 注释与 batch `limit` 提示）。
+
+## 审计元数据
+
+- 纯函数：`formatMetadata`（旧页、自研详情 markup 足够时只用这个）
+- 组件：`AdminMetadataDetail` — **新审计详情页优先**；已有产品详情 DOM 的旧页 **不必** 为对齐而全量迁移（见 docs/001 R4 尾巴、docs/002 步骤 11）

package/recipes/i18n-merge.snippet.ts

@@ -0,0 +1,29 @@
+/**
+ * RECIPE — 合并工具包消息种子，使 ConfigField / Pagination / Confirm 在新产品
+ * 上不会显示原始 key。冲突时产品宿主 key 始终优先。
+ *
+ * 示例（vue-i18n）：
+ *
+ *   import { mergeAdminKitMessages } from '@usethink/cf-admin-fe/i18n'
+ *   import zhHost from './zh-CN'
+ *   import enHost from './en'
+ *
+ *   const i18n = createI18n({
+ *     locale: 'zh-CN',
+ *     messages: {
+ *       'zh-CN': mergeAdminKitMessages(zhHost, 'zh-CN'),
+ *       en: mergeAdminKitMessages(enHost, 'en'),
+ *     },
+ *   })
+ */
+import { mergeAdminKitMessages } from '@usethink/cf-admin-fe/i18n'
+
+export function withAdminKitI18n<T extends Record<string, unknown>>(
+  zhHost: T,
+  enHost: T,
+): { 'zh-CN': T; en: T } {
+  return {
+    'zh-CN': mergeAdminKitMessages(zhHost, 'zh-CN'),
+    en: mergeAdminKitMessages(enHost, 'en'),
+  }
+}