@usethink/cf-admin-fe 0.2.8 → 0.2.9

package/README.md

@@ -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/ 为准
 ```
 
 **封包注意：**
@@ -289,6 +308,7 @@ npm pack         # 触发 prepack→build；入口仍以 src/ 为准
 - **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/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';

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,11 +177,28 @@
 
 | 候选 | 现状 | 触发条件 |
 |---|---|---|
-| `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 集合稳定 |
 
+#### 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

@@ -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 三端接线冻结摘要（部署对照）
 
 | 产品 | 会话 | 本版关键接线 | 部署前至少 |
@@ -801,5 +810,6 @@ R5 观察项（number offset helper、silent copy 选项、cursor helper、batch
 | 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

@@ -287,11 +287,11 @@
 
 **刻意不碰（仍有效）：** path 级 `createAdminApi`、脚手架、VitePress、双主题、注入式侧栏。
 
-### 9.2 中端（有余力）
+### 9.2 中端（已落地，无 API / 无发版号 bump）
 
-4. 发版辅助脚本：`type-check` + `test` + `size-report` + 提示消费方 bump。  
-5. number offset **审计笔记** 写入 R5（有同形再 API，无则结案「维持手写」）。  
-6. recipes「最小接入」补强（仍非脚手架）。
+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 冻结直到触发条件
 
@@ -319,8 +319,8 @@
 - **定位与 ≥2 提取纪律：全盘坚持，并当 PR 门禁。**  
 - **P0 三件套已在 0.2.8 落地**（契约测 + i18n 收口 + size-report）。  
 - **API 路径工厂、脚手架、文档站、双主题：远见可记，默认冻结。**  
-- **R5 number offset：可审计，不可默认加 API。**  
-- **下一列车：** 中端（发版辅助脚本 / R5 审计笔记 / recipes 最小接入），仍不扩冻结项。
+- **R5 number offset：已审计，维持不增 API**（优先 `useTablePagination().offset`）。  
+- **中端三项已落地**（pre-release / R5 笔记 / recipes 最小接入清单）；仍不扩冻结项。下一动作按触发条件或消费方 bump 0.2.8。
 
 ---
 
@@ -330,3 +330,4 @@
 |------|------|
 | 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.8",
+  "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,
@@ -87,7 +87,10 @@
     "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"
+    "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

@@ -5,6 +5,27 @@
 **完整用法、注意事项、能力榨干清单：** 见 [`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) 为准；上表只防「漏一步导致假接入」。
+
 ## 推荐复制顺序
 
 | 步骤 | Recipe | 产品路径（示例） |
@@ -20,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`） |
 
 ### 两种一等会话模型
 
@@ -95,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/index.ts

@@ -132,6 +132,9 @@ export {
   applyAdminOffsetParams,
   resolveAdminT,
   tKit,
+  collectModalFocusable,
+  handleModalTabTrap,
+  blockOverlayTabKeydown,
 } from './utils'
 
 export type { AdminI18nProxy } from './utils'

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 {

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()
+}