@usethink/cf-admin-fe 0.2.6 → 0.2.8

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 模式。
 
@@ -287,6 +287,8 @@ 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 门禁）
 
 ## 许可证
 

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

@@ -10,3 +10,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/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

@@ -182,7 +182,8 @@
 | cursor 分页 helper | 字段命名因产品而异 | ≥2 产品同一 cursor/`hasMore` 约定 |
 | batch 默认 limit「产品 profile」工厂 | 显式 `{ limit: N }` 已够清晰 | 三端都厌倦每次写 limit **且** N 集合稳定 |
 
-**维护文档真相源：** 接线细节以 [`002` §5.8](./002_cf-admin-fe使用说明书与注意事项.md) 为准；本文只记决策与结案，**勿把 R5 当立即开工的 backlog**。
+**维护文档真相源：** 接线细节以 [`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 说明书）
 
 ---
 
@@ -784,7 +784,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 +798,8 @@ 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`；版本锚点同步 |
 
 **维护约定：** 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,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,6 +1,6 @@
 {
   "name": "@usethink/cf-admin-fe",
-  "version": "0.2.6",
+  "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,
@@ -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,10 @@
     "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"
   },
   "keywords": [
     "admin",

package/recipes/README.md

@@ -2,7 +2,8 @@
 
 这些文件是**起点模板**，不是运行时导入。将它们复制（或重新导出）到你的产品 `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 步骤替代）。
 
 ## 推荐复制顺序
 

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,12 @@ export {
   formatMetadata,
   buildAdminOffsetParams,
   applyAdminOffsetParams,
+  resolveAdminT,
+  tKit,
 } 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

@@ -79,3 +79,9 @@ export {
   applyAdminOffsetParams,
   type AdminOffsetParams,
 } from './admin-query'
+
+export {
+  resolveAdminT,
+  tKit,
+  type AdminI18nProxy,
+} from './i18n'