@usethink/cf-admin-fe 0.2.6 → 0.2.9

package/README.md

@@ -2,7 +2,7 @@
 
 面向 Cloudflare 产品家族（`cf-shop`、`cf-lottery`、`cf-auth` 以及未来的 CF 管理端应用）的 Vue 3 **管理端基础套件（admin foundation）**。
 
-**状态：** **0.2.6** — 基础套件 + 双会话模型 + 错误/批处理助手 + 日志元数据/`offset` 查询 + **`copyWithToast`** + 列表 recipe。完整用法见 **[`docs/002_cf-admin-fe使用说明书与注意事项.md`](./docs/002_cf-admin-fe使用说明书与注意事项.md)**；起步清单见 `recipes/README.md`。
+**状态：** **0.2.8** — P0 三件套：`resolveAdminT` / `tKit`、AdminShell/ConfigField/MetadataDetail 契约测、`size-report`。完整用法见 **[`docs/002_cf-admin-fe使用说明书与注意事项.md`](./docs/002_cf-admin-fe使用说明书与注意事项.md)**；起步清单见 `recipes/README.md`；路线图见 **[`docs/003_cf-admin-fe极致化方案与取舍_2026-08-05.md`](./docs/003_cf-admin-fe极致化方案与取舍_2026-08-05.md)**。
 
 **核心目标：** 最大化共享 **管理端前端基础套件**，让 CF 产品快速搭建 — **不**通过克隆业务页面实现，也 **不** 强迫每个产品套用 shop 的 Bearer 模式。
 
@@ -40,6 +40,22 @@
 - 坏：只有 cf-lottery 需要 → 留在产品内。
 - 坏：为了“一致性”而包装第三方日期选择器 → 在产品里用轻量专用库。
 
+### 与 `@usethink/cf-core` 的边界（正交分工，禁止越界）
+
+本套件与 cf-core 是**互补而非重叠**的两个包，职责分工固定：
+
+| 域 | 归属包 | 示例 |
+|---|---|---|
+| 管理端前端（Vue 组件/composables/utils/i18n/styles） | **本包** | AdminShell、createAdminRequest、useTableSelection |
+| Worker/API 基础设施（后端优先 + 前后端可用的纯 TS） | **cf-core** | http、crypto、rate-limit、JWT、features/email |
+| storefront 端共享 composable | **cf-core** | features/telegram-miniapp（前台，非管理端） |
+
+**硬性纪律（`npm run verify:boundaries` 强制执行）**：
+- **禁止 `import` 自 `@usethink/cf-core`**：本包保持零运行时依赖（仅 peer `vue`），不被后端内核污染。
+- **`dependencies` 必须为空**：任何新增运行时依赖都是越界（可选 peer 依赖需先在 docs/003 裁决）。
+- **禁止 `import 'node:'` / 后端逻辑**：本包是浏览器/Vue 端，Node 专有 API 不得进入。
+- 边界规则以本表为准，与 cf-core README 的 A′ 边界段互为单向引用，不复制全文（避免双份规则漂移）。
+
 ## 安装
 
 ```bash
@@ -263,11 +279,14 @@ import '@usethink/cf-admin-fe/styles/login-primitives.css'  // .admin-login / .l
 
 ```bash
 npm install
+npm run pre-release   # type-check → test → size-report:check + 消费方 bump 提示（不 publish）
+# 或分步：
 npm test
 npm run type-check
-npm run clean    # 清空 dist/，避免过期声明混入
-npm run build    # clean + 仅生成 composables/utils/types 的 .d.ts
-npm pack         # 触发 prepack→build；入口仍以 src/ 为准
+npm run size-report   # CSS/源码规模；:check 相对 baseline 门禁
+npm run clean         # 清空 dist/，避免过期声明混入
+npm run build         # clean + 仅生成 composables/utils/types 的 .d.ts
+npm pack              # 触发 prepack→build；入口仍以 src/ 为准
 ```
 
 **封包注意：**
@@ -287,6 +306,9 @@ npm pack         # 触发 prepack→build；入口仍以 src/ 为准
 - **0.2.5** — `createAdminFlagSession`、request `onSuccess` / credentials、cookie recipes（cf-auth 验证）
 - **0.2.6** — `toErrorMessage`、批量 toast/数量上限；`formatMetadata` + `AdminMetadataDetail`；`buildAdminOffsetParams` / `applyAdminOffsetParams`；`copyWithToast`；`recipes/list-page.snippet.ts`；封包 clean/prepack/LICENSE；完整说明书 `docs/002_…`
 - **0.2.6 文档收口（无 API 变更）** — README/recipes/001/002 对齐：string vs number offset、batch `limit` 须跟后端 max、shop §5.8 接线对照、MetadataDetail「新页优先」
+- **0.2.7** — `.table-wrap` 去掉 `scrollbar-gutter: stable`，消除无溢出时表格右侧缺口
+- **0.2.8** — `resolveAdminT` / `tKit`；AdminShell / ConfigField / AdminMetadataDetail 契约测；`npm run size-report`（CSS/源码规模 + runtime dep 门禁）
+- **0.2.8 中端（无 API）** — `npm run pre-release`；001 R5 number offset 审计（维持不增 helper，推荐 `offset.value`）；recipes「最小可跑通」清单
 
 ## 许可证
 

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

@@ -1,6 +1,7 @@
 export { formatDate, toDateTimeLocalValue, dateTimeLocalToIso, isoToDateTimeLocal, formatIpFingerprint, } from './datetime';
 export { downloadCsv, safeCsvCell } from './csv-export';
 export { lockBodyScroll, unlockBodyScroll, isBodyScrollLocked, __resetBodyScrollLockForTests, } from './body-scroll-lock';
+export { collectModalFocusable, handleModalTabTrap, blockOverlayTabKeydown, } from './modal-focus-trap';
 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';
@@ -10,3 +11,4 @@ export { hasBatchFailures, resolveBatchToastType, formatBatchCountsMessage, buil
 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/modal-focus-trap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 弹窗焦点陷阱纯函数（docs/326 · 与 cf-lottery modal-focus-trap 对齐）
+ *
+ * 与 body-scroll-lock 分工：scroll lock 由 AdminModal 统一；各弹窗只负责 Tab 循环 + 初始 focus。
+ */
+/** 收集弹窗内可聚焦元素（顺序与 DOM 一致） */
+export declare function collectModalFocusable(root: HTMLElement): HTMLElement[];
+/** 弹窗根节点内 Tab 循环 */
+export declare function handleModalTabTrap(e: KeyboardEvent, root: HTMLElement | null): void;
+/** 遮罩层：禁止 Tab 把焦点漏到背景页 */
+export declare function blockOverlayTabKeydown(e: KeyboardEvent): void;

package/docs/001_cf-admin-fe/346/217/220/345/217/226/345/267/256/350/267/235/345/210/206/346/236/220/346/212/245/345/221/212_2026-08-05.md

@@ -1,10 +1,10 @@
 # cf-admin-fe 提取差距分析报告（结案版）
 
 **原日期:** 2026-08-05  
-**结案修订:** 2026-08-05（对照仓库实况；含 shop §5.8 接线与文档收口）  
-**项目:** `@usethink/cf-admin-fe`（**v0.2.6** — foundation + cookie/flag + 错误/批处理助手）  
+**结案修订:** 2026-08-05（对照仓库实况；含 shop §5.8 接线、0.2.8 P0、R5 number offset 审计笔记）  
+**项目:** `@usethink/cf-admin-fe`（**v0.2.8** — P0 契约测 / tKit / size-report；foundation 自 0.2.6）  
 **源项目:** cf-shop / cf-lottery / cf-auth frontends  
-**状态:** foundation **0.2.6 封版维护态**（无阻塞 API 缺口；三端 type-check/build/测试已对齐）；**cf-auth 角色 = 检验 cookie 路径，不是 shop 克隆目标**；文档与源码注释以**中文**为准
+**状态:** foundation **维护态**（无阻塞 API 缺口）；**cf-auth 角色 = 检验 cookie 路径，不是 shop 克隆目标**；文档与源码注释以**中文**为准
 
 > 本文原为差距清单。实施后多项已落地，**勿再把全文当待办路线图**。  
 > 历史错误 claim（如 kit 无 `requirePhrase`、`./components` 未导出、adminLogs「60+ 完全一致」）已纠正。
@@ -177,12 +177,30 @@
 
 | 候选 | 现状 | 触发条件 |
 |---|---|---|
-| `buildAdminOffsetNumbers`（number limit/offset） | shop 手写 1 行公式足够 | ≥2 产品出现同形 number filter 且复制粘贴成税 |
+| `buildAdminOffsetNumbers`（number limit/offset） | **2026-08-05 审计：维持不增 API**（见下方笔记） | 仅当 ≥2 产品出现**无法**用 `useTablePagination().offset` 表达、且同形复制成税时再评估 |
 | `copyWithToast` silent / success-fallback 选项 | 开启/创建链等产品语义分支 | ≥2 处同一套「失败仍业务成功」稳定复制 |
 | cursor 分页 helper | 字段命名因产品而异 | ≥2 产品同一 cursor/`hasMore` 约定 |
 | batch 默认 limit「产品 profile」工厂 | 显式 `{ limit: N }` 已够清晰 | 三端都厌倦每次写 limit **且** N 集合稳定 |
 
-**维护文档真相源：** 接线细节以 [`002` §5.8](./002_cf-admin-fe使用说明书与注意事项.md) 为准；本文只记决策与结案，**勿把 R5 当立即开工的 backlog**。
+#### R5 审计笔记 — number offset（2026-08-05，对照源码，非记忆）
+
+| 产品 | number body / filter 形态 | string query（`buildAdminOffsetParams`） |
+|------|---------------------------|------------------------------------------|
+| **cf-shop** | `AdminRechargesView` / `AdminVouchersView` / `AdminBalanceView`（账户+流水）手写 `offset: (page - 1) * limit`（**4 处**）；**无** `buildAdminOffsetParams` | 无（1-based 页码 → string query 列表几乎无） |
+| **cf-lottery** | `AdminLotteryView` 抽奖列表 **1 处** 手写同一公式 | 平台审计 / 租户 / webhook / 兑换码 **4 页** 已用 string helper |
+| **cf-auth** | `AdminUsers` / `AdminClients` / `AdminBlocklist` 等：`limit: limit.value, offset: offset.value`（**直接用** `useTablePagination` 的 `offset` ComputedRef） | 无（本审计未检出 string helper 列表） |
+
+**结论（钉死）：**
+
+1. **不新增** `buildAdminOffsetNumbers` / 对称 number helper。  
+2. 摩擦不是「缺工厂」，而是写法不统一：  
+   - 推荐 number body：`{ limit: limit.value, offset: offset.value }`（pagination 已算好）；  
+   - 手写 `(page - 1) * limit` 与 `offset.value` **等价**，1 行不算提取税。  
+3. string 与 number **契约不同**（URLSearchParams vs 类型化 filter），继续用现有 string helper；禁止为「对齐」互转。  
+4. 触发条件收紧：只有出现 **无法** 用现有 `offset` 表达的同形 number 拼装（例如额外字段包装、多 offset 轴）且跨产品复制，才重开评估。
+
+**维护文档真相源：** 接线细节以 [`002` §5.8](./002_cf-admin-fe使用说明书与注意事项.md) 为准；本文只记决策与结案，**勿把 R5 当立即开工的 backlog**。  
+**后续取舍与近端路线（含 P0 三件套、脚手架/文档站冻结条件）：** 见 [`003` 极致化方案与取舍](./003_cf-admin-fe极致化方案与取舍_2026-08-05.md)。
 
 ---
 

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

@@ -1,9 +1,9 @@
 # @usethink/cf-admin-fe 使用说明书与注意事项
 
-> **版本：** 0.2.6（以 `package.json` 为准）  
+> **版本：** 0.2.8（以 `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)（提取决策背景）
+> **配套：** 根 [`README.md`](../README.md)（API 面速查）· [`recipes/README.md`](../recipes/README.md)（复制清单）· [`docs/001_…差距分析`](./001_cf-admin-fe提取差距分析报告_2026-08-05.md)（提取决策背景）· [`docs/003_…极致化取舍`](./003_cf-admin-fe极致化方案与取舍_2026-08-05.md)（路线图与做/不做裁决，非 API 说明书）
 
 ---
 
@@ -283,16 +283,18 @@ applyAdminOffsetParams(
 
 非法页码 → 1；非法 limit → `fallbackLimit` 或 20。
 
-**number body 列表（shop 常见）手写即可：**
+**number body 列表（shop / 部分 lottery 抽奖列表）— 推荐用 pagination 自带 offset：**
 
 ```ts
-await listApi({
-  ...filters,
-  limit: limit.value,
-  offset: (page.value - 1) * limit.value, // number
-})
+const { page, limit, offset, setTotal } = useTablePagination()
+// 推荐（与手写公式等价，少一处算术）：
+await listApi({ limit: limit.value, offset: offset.value })
+// 等价手写：
+// await listApi({ limit: limit.value, offset: (page.value - 1) * limit.value })
 ```
 
+历史页面常见手写 `(page-1)*limit` 亦可，**不必**为对齐而改。**不要**为此新增 kit number helper（001 R5 审计）。
+
 **`runLoad` 推荐形态（string query）：**
 
 ```ts
@@ -661,7 +663,7 @@ Vite 需 `dedupe: ['vue']`，避免套件与应用两份 Vue（peer 类型/运
 | 复制 | 多数路径 `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） |
+| **offset 查询** | **多为 number body**：`limit`/`offset` 数字；推荐 `offset: offset.value`（`useTablePagination` 已算好），或手写 `(page-1)*limit`（与 offset 等价） | **不要**强行换成 `buildAdminOffsetParams`（它产出 **string**，给 URLSearchParams）；R5 审计结论见 001 |
 | **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（产品策略） |
@@ -671,7 +673,7 @@ Vite 需 `dedupe: ['vue']`，避免套件与应用两份 Vue（peer 类型/运
 
 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。  
+3. 新增 **number** filter offset 列表 → 优先 `offset: offset.value`（或等价手写 `(page-1)*limit`）；**不**新增 kit number helper（001 R5 审计 2026-08-05：维持不增 API）。  
 4. 新增服务端 `max(N)` 批量 API → `checkAdminBatchLimit(ids, { limit: N, unit })`，N 跟后端一致。  
 5. 不要为了「对齐文档示例」把 number body 改成 string query。
 
@@ -688,7 +690,7 @@ Vite 需 `dedupe: ['vue']`，避免套件与应用两份 Vue（peer 类型/运
 - [ ] 路由：`decideAdminRouteAccess` + 登录页 `resolveAdminLoginRedirect`  
 - [ ] `AdminShell` 布局 + 产品菜单  
 - [ ] 登录 UI 包在 `AdminLoginShell`  
-- [ ] 第一页列表：`useAdminListLoader` + `useTablePagination` + **按契约选分页**：string query → `buildAdminOffsetParams`；number body → 手写数字 offset（见 §5.8）  
+- [ ] 第一页列表：`useAdminListLoader` + `useTablePagination` + **按契约选分页**：string query → `buildAdminOffsetParams`；number body → `offset.value` 或等价手写（见 §5.8 / 001 R5）  
 - [ ] 多选页：`useTableSelection` + `checkAdminBatchLimit`（**`limit` 对齐后端 max**，默认 20 仅 auth 风格）+ batch toast  
 - [ ] 复制：`copyWithToast`；特殊降级才 `writeClipboardText`  
 - [ ] 错误：`toErrorMessage`  
@@ -746,7 +748,7 @@ cf-admin-fe/
 - 权限指令 / RBAC 组件  
 - 图表、富文本、表单 schema 引擎  
 - 与后端共享的 RPC/SDK  
-- **number** 版 `buildAdminOffsetParams`（观察期，见 001 **R5** / §5.8 升级清单第 3 条）  
+- **number** 版 `buildAdminOffsetParams`（**R5 审计后默认不增**；见 001 R5 笔记 / §5.8 升级清单第 3 条）  
 - 强迫旧审计页迁 `AdminMetadataDetail`（组件留给**新页**）
 
 若新产品需要上述能力：在产品内选型；当 **≥2 个 CF 管理端** 出现可复用的同一薄封装时，再提案进入 `cf-admin-fe`。
@@ -767,11 +769,18 @@ cf-admin-fe/
 ### 10.2 封版前自检（kit）
 
 ```bash
-npm test              # 预期全绿（约 122）
+# 推荐一键（003 中端）：type-check → test → size-report:check + 打印消费方 bump 提示
+npm run pre-release
+
+# 或分步：
 npm run type-check
+npm test              # 0.2.8：31 文件 / 149 用例量级（以本地输出为准）
+npm run size-report:check
 npm run build         # 生成 dist 声明；可选 npm pack 干跑
 ```
 
+`pre-release` **不会**改 version、publish 或改三仓依赖；通过后人工 bump / 发版。
+
 ### 10.3 三端接线冻结摘要（部署对照）
 
 | 产品 | 会话 | 本版关键接线 | 部署前至少 |
@@ -784,7 +793,8 @@ npm run build         # 生成 dist 声明；可选 npm pack 干跑
 
 ### 10.4 明确不进本封版
 
-R5 观察项（number offset helper、silent copy 选项、cursor helper、batch profile 工厂）、旧页迁 `AdminMetadataDetail`、领域 CRUD、C 端 storefront。
+R5 观察项（number offset helper、silent copy 选项、cursor helper、batch profile 工厂）、旧页迁 `AdminMetadataDetail`、领域 CRUD、C 端 storefront。  
+后续「该不该做、做到什么程度」见 [`003` 极致化方案与取舍](./003_cf-admin-fe极致化方案与取舍_2026-08-05.md)（P0 三件套 / 冻结项与触发条件）；**勿把 003 当本说明书的 API 增补**。
 
 ---
 
@@ -797,5 +807,9 @@ R5 观察项（number offset helper、silent copy 选项、cursor helper、batch
 | 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` 可选；窄屏可藏用户名） |
+| 2026-08-05 | **0.2.7** `.table-wrap` 去掉 `scrollbar-gutter: stable`，消除全站表格右侧缺口 |
+| 2026-08-05 | 配套链增加 [`003` 极致化方案与取舍](./003_cf-admin-fe极致化方案与取舍_2026-08-05.md)；§10.4 指向 003 作路线图（非 API） |
+| 2026-08-05 | **0.2.8** P0：`resolveAdminT`/`tKit`、SFC 契约测、`size-report`；版本锚点同步 |
+| 2026-08-05 | **中端（无 API）**：`npm run pre-release`；001 R5 number offset 审计笔记（维持不增 API；推荐 `offset.value`）；recipes 最小接入清单补强 |
 
 **维护约定：** API 变更时同步改本文件、根 README 公开 API 节、`recipes/README.md` 与 `tests/public-api.test.ts`。说明书只描述已实现行为；示例代码须与 `src/` 签名一致。

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,333 @@
+# @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 中端（已落地，无 API / 无发版号 bump）
+
+4. ~~发版辅助脚本~~ → `scripts/pre-release.mjs` + `npm run pre-release`（type-check → test → size-report:check + 消费方 bump 提示；不 publish）。  
+5. ~~number offset 审计笔记~~ → 001 **R5**：shop 4 处手写 + lottery 抽奖 1 处手写 + auth 用 `offset.value`；**维持不增** number helper；推荐 number body 用 `offset.value`。  
+6. ~~recipes 最小接入补强~~ → `recipes/README.md` 增加「最小可跑通」核对清单（仍非脚手架 / 非 examples 应用）。
+
+### 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**（优先 `useTablePagination().offset`）。  
+- **中端三项已落地**（pre-release / R5 笔记 / recipes 最小接入清单）；仍不扩冻结项。下一动作按触发条件或消费方 bump 0.2.8。
+
+---
+
+## 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 状态同步 |
+| 2026-08-05 | **中端落地（无 API）**：`pre-release`、R5 number offset 审计结案、recipes 最小接入清单；§9.2/§11 同步 |

package/docs/SHARED_PACKAGE_CHANGE_PROCESS.md

@@ -0,0 +1,81 @@
+# SHARED cf-admin-fe 共用包变更纪律（复盘 + 正途）
+
+> 日期：2026-09-11  
+> 背景：Wave327 在 `@usethink/cf-admin-fe` 上犯了可避免的工程错误。
+
+---
+
+## 一、已发生的错误（事实，非推测）
+
+| # | 错误 | 后果 |
+|---|------|------|
+| E1 | cf-admin-fe 使用 `file:../../../2-node/cf-admin-fe` | VPS/CI `npm install` **必失败**（路径不存在） |
+| E2 | AdminModal 遮罩 `@keydown` **未用 `.self`**，`blockOverlayTabKeydown` 冒泡 | 弹窗内 **Tab 无法正常切换**（中间项也被 preventDefault） |
+| E3 | 未写组件级回归测试就宣称「统一 a11y」 | 缺陷进共用包，靠人工回退而非测试门禁 |
+| E4 | 出问题后 **回退依赖** 而非 **修包 + 发布 + 升级** | 公共能力未沉淀，Wave327 目标半残 |
+
+**正确态度**：共用包问题 → 在 **cf-admin-fe 仓库** 修对、测全、发版；业务仓只改 semver 升级。**禁止**用 `file:` 或回退版本糊弄。
+
+---
+
+## 二、正途流程（以后强制执行）
+
+```
+审查影响面 → 写回归测试 → 实现 → cf-admin-fe npm test + type-check
+    → npm publish 0.2.x → 各业务仓 npm install @usethink/cf-admin-fe@^x.y.z
+    → 各业务仓 vitest / vue-tsc
+```
+
+### 2.1 变更前审查清单
+
+- [ ] `rg "@usethink/cf-admin-fe"` 列出 **所有下游**（cf-admin-fe、cf-pay…）
+- [ ] 与上一版 **逐 prop / 默认值** diff，写入 cf-admin-fe `CHANGELOG.md`
+- [ ] 识别默认行为变更 → 必须提供 **opt-out prop** 或 major bump
+- [ ] **禁止**业务仓 lockfile 出现 `file:` / `link: true`
+
+### 2.2 AdminModal 0.2.9 正确设计（审查结论）
+
+| 能力 | 实现 | 测试 |
+|------|------|------|
+| Tab 循环 | `handleModalTabTrap` 绑 **弹窗容器** | 末项→首项、首项 Shift+Tab→末项、**中间 Tab 不 preventDefault** |
+| 遮罩 Tab | `@keydown.self` + `blockOverlayTabKeydown` | **禁止**无 `.self` 的 mask handler |
+| body 滚动锁 | 默认 `lockScroll=true`，`body-scroll-lock` 引用计数 | 开/关弹窗、`:lock-scroll="false"` |
+| 焦点 | 打开 focus 容器、关闭 restore | 已有 0.2.8 逻辑保留 |
+| Esc | `closeOnEscape` 时关闭 | AdminModal.test |
+
+### 2.3 下游升级（cf-admin-fe）
+
+**当前**：`frontend/package.json` 保持 `^0.2.8`（registry），直至 0.2.9 **发布到 npm**。
+
+发布后执行：
+
+```bash
+cd templates/cf-admin-fe/frontend
+npm install @usethink/cf-admin-fe@^0.2.9
+cd ..
+npm test && npm run type-check:all
+```
+
+Wave327 **已保留且安全**的部分（仅 cf-admin-fe 本地，与 cf-admin-fe 无关）：
+
+- Integrations / Blacklist / Members 的 `useTenantPendingGuard` 写 CTA
+
+---
+
+## 三、cf-admin-fe 待落地提交（在 `0-X/2-node/cf-admin-fe`）
+
+> 以下应在 **cf-admin-fe 仓库** 单独 commit + publish，**不要**在 cf-admin-fe 写 file 依赖。
+
+1. `src/utils/modal-focus-trap.ts`（已有，补 DOM 单测）
+2. `src/components/AdminModal.vue`：`lockScroll` 默认 true；mask `@keydown.self`
+3. `tests/AdminModal.test.ts`（新建）
+4. `tests/modal-focus-trap.test.ts`（补中间 Tab 不拦截用例）
+5. `docs/SHARED_PACKAGE_CHANGE_PROCESS.md` + `CHANGELOG.md` 0.2.9
+6. `npm test` → `npm publish`
+
+---
+
+## 四、一句话
+
+**共用包 = 先审后写、测试门禁、registry 发布、下游 semver 升级。**  
+回退业务仓依赖 **不是** 修复共用包；`file:` 本地链 **是** 部署灾难。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usethink/cf-admin-fe",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "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,
@@ -70,6 +70,8 @@
   "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",
@@ -82,7 +84,13 @@
     "test:watch": "vitest",
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "prepack": "npm run build",
-    "clean": "node scripts/clean-dist.mjs"
+    "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",
+    "verify:boundaries": "node scripts/verify-boundaries.mjs",
+    "pre-release": "node scripts/pre-release.mjs",
+    "prepublishOnly": "npm run type-check && npm test && npm run verify:boundaries && npm run pre-release"
   },
   "keywords": [
     "admin",

package/recipes/README.md

@@ -2,7 +2,29 @@
 
 这些文件是**起点模板**，不是运行时导入。将它们复制（或重新导出）到你的产品 `src/` 目录下，然后补齐产品专属部分（菜单、领域 API 方法、登录 UI）。
 
-**完整用法、注意事项、能力榨干清单：** 见 [`docs/002_cf-admin-fe使用说明书与注意事项.md`](../docs/002_cf-admin-fe使用说明书与注意事项.md)。
+**完整用法、注意事项、能力榨干清单：** 见 [`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 步骤替代）。
+
+## 最小可跑通（核对清单，非脚手架）
+
+目标：**壳 + 会话 + 请求 + 一页列表** 能 type-check / 手工点通。  
+**不是** `create-cf-admin`，**不是**可运行 monorepo example（003 仍冻结脚手架；有余力再加 `examples/minimal`）。
+
+| # | 必做 | 验收 |
+|---|------|------|
+| M1 | 安装 `@usethink/cf-admin-fe` + peer `vue`（可选 `vue-i18n`） | `package.json` 有依赖 |
+| M2 | `import '@usethink/cf-admin-fe/styles'`（或 tokens + primitives） | 管理端有基础 token / 表格样式 |
+| M3 | 根布局挂载 **一次** `ToastContainer` | 任意页 `showToast` 可见 |
+| M4 | 选 **一种** 会话：Bearer → `useAdminAuth.shop` + `useAdminRequest`；Cookie → `.cookie` 两件套 | 登录后请求带 token 或 `credentials: 'include'` |
+| M5 | `mergeAdminKitMessages`（见 `i18n-merge.snippet.ts`） | 无 vue-i18n 时组件仍靠 tKit fallback；有 i18n 时壳文案不露 key |
+| M6 | `AdminLayout.vue` + 产品菜单 + `decideAdminRouteAccess` | 未登录进 admin → 登录页；登录后进壳 |
+| M7 | 登录页：`AdminLoginShell` + 产品表单 + `resolveAdminLoginRedirect` | `?redirect=` 回跳安全 |
+| M8 | **一页**列表：`list-page.snippet.ts` 骨架；**先**确认 string query vs number body | string → `buildAdminOffsetParams`；number → `offset.value`（或等价手写） |
+| M9 | 产品 `vue-tsc` / type-check | 无类型红 |
+
+可选（第二页再加）：`useTableSelection` + `checkAdminBatchLimit`（**limit 对齐后端 max**）、`copyWithToast`、`ConfigField`、`AdminMetadataDetail`（**新**审计详情优先）。
+
+完整逐步说明仍以 [`docs/002`](../docs/002_cf-admin-fe使用说明书与注意事项.md) 为准；上表只防「漏一步导致假接入」。
 
 ## 推荐复制顺序
 
@@ -19,7 +41,7 @@
 | 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 |
+| 10 | 列表页 | 见 `list-page.snippet.ts`：`useAdminListLoader` + 分页/多选 + `toErrorMessage` / `copyWithToast`；**先确认**后端是 string query 还是 number body offset（number 推荐 `offset.value`） |
 
 ### 两种一等会话模型
 
@@ -94,7 +116,7 @@ if (!limitCheck.ok) {
 | 形态 | 工具 | 参考产品 |
 |---|---|---|
 | `URLSearchParams` / query：`limit`、`offset` 为 **字符串** | `buildAdminOffsetParams(page, limit)` 或 `applyAdminOffsetParams` | cf-lottery 平台审计、租户、webhook、兑换码 |
-| 类型化 filter / body：`limit`、`offset` 为 **数字** | **手写** `(page - 1) * limit`；**不要**套 string helper | cf-shop 余额 / 充值 / 代金券等 |
+| 类型化 filter / body：`limit`、`offset` 为 **数字** | **`offset.value`**（`useTablePagination`）或等价手写 `(page - 1) * limit`；**不要**套 string helper；**不**抽 number helper（001 R5） | cf-auth 多用 `offset`；cf-shop 余额/充值/代金券等多手写；lottery 抽奖列表 1 处手写 |
 | Cursor | 产品自管 | shop 部分订单/日志 |
 
 `buildAdminOffsetParams` 的返回值是 `{ limit: string; offset: string }`，塞进需要 `number` 的 TypeScript filter 会类型错误或静默把数字变成字符串——属于误用，不是「再抽一个兼容层就能糊弄过去」。

package/recipes/list-page.snippet.ts

@@ -19,10 +19,13 @@
  *    参考：cf-lottery 平台审计 / 租户 / webhook / 兑换码
  *
  * B) 类型化 filter / JSON body：limit、offset 为 number
- *    手写即可，例如：
+ *    推荐用 useTablePagination 自带 offset（与手写公式等价）：
+ *      { limit: limit.value, offset: offset.value }
+ *    等价手写：
  *      { limit: limit.value, offset: (page.value - 1) * limit.value }
- *    参考：cf-shop AdminBalance / Recharges / Vouchers
- *    禁止把 B 强行改成 A 只为「用上 helper」。number helper 观察期：≥2 产品同形再提案。
+ *    参考：cf-auth（offset.value）；cf-shop Balance/Recharges/Vouchers（多手写）；lottery 抽奖列表 1 处手写
+ *    禁止把 B 强行改成 A 只为「用上 helper」。
+ *    number helper：**R5 审计后默认不增 API**（见 docs/001 R5）；1 行公式 / offset 已够。
  *
  * 真实 API 签名（务必与 src/utils/admin-query.ts 一致）：
  *   buildAdminOffsetParams(page: number, limit: number, options?)
@@ -63,7 +66,9 @@ const {
 const { loading, loadError, runLoad } = useAdminListLoader()
 
 // 示例：产品侧 admin 请求（Bearer 或 cookie 由 useAdminRequest recipe 决定）
-declare function listDomainItems(params: Record<string, string>): Promise<{ items: Row[]; total: number }>
+declare function listDomainItems(
+  params: Record<string, string> | { limit: number; offset: number; status?: string },
+): Promise<{ items: Row[]; total: number }>
 declare function batchDisable(ids: string[]): Promise<{ success: number; failed: number }>
 declare function showToast(message: string, type?: 'success' | 'error' | 'info'): void
 declare function t(key: string, params?: Record<string, unknown>): string
@@ -71,7 +76,7 @@ declare function t(key: string, params?: Record<string, unknown>): string
 async function loadData() {
   await runLoad(
     async (ctx) => {
-      // ── 形态 A：string query（本示例）──
+      // ── 形态 A：string query（本示例主路径）──
       // 位置参数：page（1-based）、limit（每页条数）→ 字符串 limit/offset
       const params = buildAdminOffsetParams(page.value, limit.value)
       // 若已有 URLSearchParams（含业务筛选），再写入 limit/offset：
@@ -80,10 +85,11 @@ async function loadData() {
       const res = await listDomainItems(params)
 
       // ── 形态 B：number body / 类型化 filter（勿用 buildAdminOffsetParams）──
+      // 推荐：
       // const res = await listDomainItems({
       //   status: filter.status,
       //   limit: limit.value,
-      //   offset: (page.value - 1) * limit.value,
+      //   offset: offset.value, // === (page - 1) * limit
       // })
 
       if (ctx.isStale()) return
@@ -134,6 +140,7 @@ async function runBatchDisable() {
   }
 }
 
+// 形态 B 会用到 offset；形态 A 主路径下保留引用避免 snippet 被 tree-shake 误导
 void offset
 void applyAdminOffsetParams
 void total

package/src/components/AdminModal.vue

@@ -1,5 +1,5 @@
 <template>
-  <div v-if="modelValue" class="modal-mask" @click.self="handleBackdropClick">
+  <div v-if="modelValue" class="modal-mask" @click.self="handleBackdropClick" @keydown.self="handleMaskKeydown">
     <div
       ref="modalRef"
       class="modal"
@@ -9,7 +9,7 @@
       :aria-labelledby="title ? titleId : undefined"
       :aria-label="$t('adminModal.title')"
       tabindex="-1"
-      @keydown="handleKeydown"
+      @keydown="handleModalKeydown"
     >
       <h3 v-if="title" :id="titleId" class="modal-title">{{ title }}</h3>
       <div ref="bodyRef" class="modal-body">
@@ -26,6 +26,8 @@
 
 <script setup lang="ts">
 import { nextTick, onBeforeUnmount, ref, useId, watch } from 'vue'
+import { lockBodyScroll, unlockBodyScroll } from '../utils/body-scroll-lock'
+import { blockOverlayTabKeydown, handleModalTabTrap } from '../utils/modal-focus-trap'
 
 const props = withDefaults(defineProps<{
   modelValue: boolean
@@ -34,10 +36,16 @@ const props = withDefaults(defineProps<{
   hideActions?: boolean
   closeOnBackdrop?: boolean
   closeOnEscape?: boolean
+  /**
+   * 打开时是否锁定 document.body 滚动（默认 false，与 0.2.8 一致；显式 true 才锁）。
+   * 与页面级 lock 可嵌套（body-scroll-lock 引用计数）。
+   */
+  lockScroll?: boolean
 }>(), {
   hideActions: false,
   closeOnBackdrop: false,
   closeOnEscape: false,
+  lockScroll: false,
 })
 
 const emit = defineEmits<{
@@ -57,54 +65,40 @@ function handleBackdropClick() {
   if (props.closeOnBackdrop) close()
 }
 
-function getFocusableElements() {
-  return Array.from(modalRef.value?.querySelectorAll<HTMLElement>(
-    'button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), a[href], [tabindex]:not([tabindex="-1"])',
-  ) || [])
+/** 弹窗容器：Tab 循环 + 可选 Esc（边界行为同 0.2.8，实现抽到 util） */
+function tryCloseOnEscape(e: KeyboardEvent) {
+  if (e.key !== 'Escape' || !props.closeOnEscape) return
+  e.preventDefault()
+  close()
 }
 
-function handleKeydown(event: KeyboardEvent) {
-  if (event.key === 'Escape') {
-    if (!props.closeOnEscape) return
-    event.preventDefault()
-    close()
-    return
-  }
-  if (event.key !== 'Tab') return
-
-  const focusable = getFocusableElements()
-  if (focusable.length === 0) {
-    event.preventDefault()
-    modalRef.value?.focus()
-    return
-  }
+/** 遮罩 .self：仅焦点在遮罩时拦截 Tab，禁止冒泡误伤弹窗内控件 */
+function handleMaskKeydown(e: KeyboardEvent) {
+  blockOverlayTabKeydown(e)
+  tryCloseOnEscape(e)
+}
 
-  const first = focusable[0]
-  const last = focusable[focusable.length - 1]
-  if (event.shiftKey && (document.activeElement === first || document.activeElement === modalRef.value)) {
-    event.preventDefault()
-    last.focus()
-  } else if (!event.shiftKey && document.activeElement === last) {
-    event.preventDefault()
-    first.focus()
-  }
+function handleModalKeydown(e: KeyboardEvent) {
+  handleModalTabTrap(e, modalRef.value)
+  tryCloseOnEscape(e)
 }
 
 watch(() => props.modelValue, async (visible, wasVisible) => {
   if (visible && !wasVisible) {
+    if (props.lockScroll) lockBodyScroll()
     restoreFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null
     await nextTick()
-    // 长详情中的第一个按钮通常位于正文底部；若直接聚焦它，浏览器会把滚动区自动拉到底部。
-    // 打开时先回到正文顶部并聚焦对话框容器，用户可以从订单基本信息开始阅读，再用 Tab 进入控件。
     if (bodyRef.value) bodyRef.value.scrollTop = 0
     modalRef.value?.focus({ preventScroll: true })
   } else if (!visible && wasVisible) {
+    if (props.lockScroll) unlockBodyScroll()
     restoreFocus?.focus()
     restoreFocus = null
   }
-})
+}, { immediate: true })
 
 onBeforeUnmount(() => {
+  if (props.modelValue && props.lockScroll) unlockBodyScroll()
   restoreFocus?.focus()
 })
 </script>
@@ -131,14 +125,12 @@ onBeforeUnmount(() => {
   min-height: 0;
   display: flex;
   flex-direction: column;
-  /* 比页面底略抬一层，避免与遮罩糊成一团 */
   background: var(--tg-secondary-bg, #151b28);
   color: var(--tg-text);
   border-radius: var(--r-lg, 12px);
   padding: 22px;
   border: 1px solid var(--border-strong, rgba(255, 255, 255, 0.16));
   box-shadow: var(--shadow-lg, 0 20px 50px rgba(0, 0, 0, 0.45));
-  /* 勿用 overflow:hidden：会裁切 :focus-visible 描边（控件四边显示不全） */
   overflow: visible;
 }
 
@@ -161,13 +153,11 @@ onBeforeUnmount(() => {
   overflow-x: visible;
   overflow-y: auto;
   overscroll-behavior: contain;
-  /* 给 focus 描边（outline-offset: 2px）留出左右上下内边距，避免被滚动裁切 */
   padding: 4px 6px 6px;
   margin: -4px -6px -6px;
   scrollbar-gutter: stable;
 }
 
-/* 子级 form 需要吃满高度时（如商品编辑粘性脚部） */
 .modal-body > form {
   min-height: 0;
 }

package/src/components/AdminShell.vue

@@ -83,8 +83,9 @@
 </template>
 
 <script setup lang="ts">
-import { computed, getCurrentInstance } from 'vue'
+import { computed } from 'vue'
 import { useAdminSidebar } from '../composables/useAdminSidebar'
+import { tKit } from '../utils/i18n'
 
 export type AdminShellMenuItem = {
   name: string
@@ -133,24 +134,11 @@ const emit = defineEmits<{
 
 const { isMobile, sidebarOpen, toggleSidebar, closeSidebar } = useAdminSidebar()
 
-function tFallback(key: string, fallback: string): string {
-  const proxy = getCurrentInstance()?.proxy as { $t?: (k: string) => string } | undefined
-  try {
-    if (typeof proxy?.$t === 'function') {
-      const out = proxy.$t(key)
-      if (typeof out === 'string' && out !== key) return out
-    }
-  } catch {
-    /* 无 i18n */
-  }
-  return fallback
-}
-
 const resolvedLogoutLabel = computed(
-  () => props.logoutLabel || tFallback('adminLayout.logout', '退出'),
+  () => props.logoutLabel || tKit('adminLayout.logout', '退出'),
 )
 const resolvedToggleLabel = computed(
-  () => props.toggleSidebarLabel || tFallback('adminLayout.toggleSidebar', '菜单'),
+  () => props.toggleSidebarLabel || tKit('adminLayout.toggleSidebar', '菜单'),
 )
 
 const resolvedTitle = computed(() => {

package/src/components/ConfigField.vue

@@ -86,12 +86,13 @@
 </template>
 
 <script setup lang="ts">
-import { computed, getCurrentInstance, ref, watch } from 'vue'
+import { computed, ref, watch } from 'vue'
 import type {
   AdminSystemConfigFieldDefinition,
   ConfigFieldStatus,
 } from '../types/system-config'
 import { formatCents, parseYuanToCents } from '../utils/currency-cents'
+import { tKit } from '../utils/i18n'
 
 const props = defineProps<{
   item: AdminSystemConfigFieldDefinition
@@ -107,24 +108,9 @@ const emit = defineEmits<{
 
 const localError = ref('')
 
-/**
- * 可选 i18n：宿主可注入 vue-i18n 全局 `$t` / `$te`。
- * 切勿把后端自由文本作为 defaultMessage 传入（裸 `@` / `{}` 会导致解析失败）。
- */
+/** 可选 i18n：统一走 tKit（无 vue-i18n 时用中文 fallback） */
 function tSafe(key: string, fallback: string, params?: Record<string, unknown>): string {
-  const proxy = getCurrentInstance()?.proxy as
-    | { $t?: (k: string, p?: Record<string, unknown>) => string; $te?: (k: string) => boolean }
-    | undefined
-  try {
-    if (proxy?.$te && !proxy.$te(key)) return fallback
-    if (typeof proxy?.$t === 'function') {
-      const out = params ? proxy.$t(key, params) : proxy.$t(key)
-      if (typeof out === 'string' && out !== key) return out
-    }
-  } catch {
-    /* 无 i18n */
-  }
-  return fallback
+  return tKit(key, fallback, params)
 }
 
 function translateConfigText(

package/src/index.ts

@@ -130,8 +130,15 @@ export {
   formatMetadata,
   buildAdminOffsetParams,
   applyAdminOffsetParams,
+  resolveAdminT,
+  tKit,
+  collectModalFocusable,
+  handleModalTabTrap,
+  blockOverlayTabKeydown,
 } from './utils'
 
+export type { AdminI18nProxy } from './utils'
+
 export {
   normalizeOtpDigits,
   isOtpComplete,

package/src/styles/admin-primitives.css

@@ -177,6 +177,11 @@
 /* ── 表格容器 ──
  * 滚动裁剪发生在这里（overflow: auto）。sticky 表头相对 .table-wrap 吸顶。
  * 禁止在页面 scoped 再写一套 table-wrap / th sticky。
+ *
+ * 滚动条策略（勿用 scrollbar-gutter: stable）：
+ * - stable 会在无溢出时也预留纵向槽，表右侧出现「缺口」、最后一列与圆角边框不对齐；
+ * - 默认 auto：仅在真正溢出时占位；细滚动条见下方 ::-webkit-scrollbar。
+ * 弹层/长卡片列表可另用 stable（防布局跳动）；表格以视觉对齐优先。
  */
 .table-wrap {
   background: var(--tg-secondary-bg, #151b28);
@@ -184,7 +189,6 @@
   border: 1px solid var(--border, rgba(255, 255, 255, 0.1));
   overflow: auto;
   overscroll-behavior: contain;
-  scrollbar-gutter: stable;
   flex: 1;
   min-height: 0;
   /* 建立独立层叠上下文，避免表头与外部 sticky toolbar 抢 z-index */

package/src/utils/i18n.ts

@@ -0,0 +1,63 @@
+/**
+ * 套件组件统一 i18n 回退（vue-i18n 为 optional peer）。
+ *
+ * - 有 `$t` 且返回非 key 本身 → 用翻译
+ * - 有 `$te` 且 key 不存在 → 直接 fallback（避免 vue-i18n 警告/返回 key）
+ * - 无 i18n 或抛错 → fallback
+ *
+ * 切勿把后端自由文本当 fallback 里的插值模板（裸 `@` / `{}` 可能被 i18n 解析）。
+ */
+import { getCurrentInstance } from 'vue'
+
+export type AdminI18nProxy = {
+  $t?: (key: string, params?: Record<string, unknown>) => unknown
+  $te?: (key: string) => boolean
+} | null | undefined
+
+/**
+ * 纯函数：可在单测中直接注入 proxy，不依赖 setup。
+ */
+export function resolveAdminT(
+  proxy: AdminI18nProxy,
+  key: string,
+  fallback: string,
+  params?: Record<string, unknown>,
+): string {
+  try {
+    if (typeof proxy?.$te === 'function' && !proxy.$te(key)) return fallback
+    if (typeof proxy?.$t === 'function') {
+      const out = params !== undefined ? proxy.$t(key, params) : proxy.$t(key)
+      if (typeof out === 'string' && out !== key) return out
+    }
+  } catch {
+    /* 无 i18n 或运行时错误 */
+  }
+  return fallback
+}
+
+/**
+ * 从当前组件实例的 appContext.globalProperties 读取 `$t` / `$te`。
+ * 使用 globalProperties 而非 `proxy.$t`，避免未安装 vue-i18n 时访问实例代理触发 Vue warn。
+ * 勿在模块顶层调用。
+ */
+export function tKit(
+  key: string,
+  fallback: string,
+  params?: Record<string, unknown>,
+): string {
+  const instance = getCurrentInstance()
+  const gp = instance?.appContext.config.globalProperties as
+    | Record<string, unknown>
+    | undefined
+  const proxy: AdminI18nProxy = gp
+    ? {
+        $t: typeof gp.$t === 'function'
+          ? (gp.$t as (k: string, p?: Record<string, unknown>) => unknown).bind(gp)
+          : undefined,
+        $te: typeof gp.$te === 'function'
+          ? (gp.$te as (k: string) => boolean).bind(gp)
+          : undefined,
+      }
+    : undefined
+  return resolveAdminT(proxy, key, fallback, params)
+}

package/src/utils/index.ts

@@ -15,6 +15,12 @@ export {
   __resetBodyScrollLockForTests,
 } from './body-scroll-lock'
 
+export {
+  collectModalFocusable,
+  handleModalTabTrap,
+  blockOverlayTabKeydown,
+} from './modal-focus-trap'
+
 export { normalizeCents, formatCents, parseYuanToCents } from './currency-cents'
 
 export {
@@ -79,3 +85,9 @@ export {
   applyAdminOffsetParams,
   type AdminOffsetParams,
 } from './admin-query'
+
+export {
+  resolveAdminT,
+  tKit,
+  type AdminI18nProxy,
+} from './i18n'

package/src/utils/modal-focus-trap.ts

@@ -0,0 +1,37 @@
+/**
+ * 弹窗焦点陷阱纯函数（docs/326 · 与 cf-lottery modal-focus-trap 对齐）
+ *
+ * 与 body-scroll-lock 分工：scroll lock 由 AdminModal 统一；各弹窗只负责 Tab 循环 + 初始 focus。
+ */
+
+/** 收集弹窗内可聚焦元素（顺序与 DOM 一致） */
+export function collectModalFocusable(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll(
+    'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+  )) as HTMLElement[]
+}
+
+/** 弹窗根节点内 Tab 循环 */
+export function handleModalTabTrap(e: KeyboardEvent, root: HTMLElement | null): void {
+  if (e.key !== 'Tab' || !root) return
+  const items = collectModalFocusable(root)
+  if (items.length === 0) {
+    e.preventDefault()
+    root.focus()
+    return
+  }
+  const first = items[0]
+  const last = items[items.length - 1]
+  if (e.shiftKey && (document.activeElement === first || document.activeElement === root)) {
+    e.preventDefault()
+    last.focus()
+  } else if (!e.shiftKey && document.activeElement === last) {
+    e.preventDefault()
+    first.focus()
+  }
+}
+
+/** 遮罩层：禁止 Tab 把焦点漏到背景页 */
+export function blockOverlayTabKeydown(e: KeyboardEvent): void {
+  if (e.key === 'Tab') e.preventDefault()
+}