@usethink/cf-admin-fe 0.1.1 → 0.2.8

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

@@ -0,0 +1,225 @@
+# cf-admin-fe 提取差距分析报告（结案版）
+
+**原日期:** 2026-08-05  
+**结案修订:** 2026-08-05（对照仓库实况；含 shop §5.8 接线与文档收口）  
+**项目:** `@usethink/cf-admin-fe`（**v0.2.6** — foundation + cookie/flag + 错误/批处理助手）  
+**源项目:** cf-shop / cf-lottery / cf-auth frontends  
+**状态:** foundation **0.2.6 封版维护态**（无阻塞 API 缺口；三端 type-check/build/测试已对齐）；**cf-auth 角色 = 检验 cookie 路径，不是 shop 克隆目标**；文档与源码注释以**中文**为准
+
+> 本文原为差距清单。实施后多项已落地，**勿再把全文当待办路线图**。  
+> 历史错误 claim（如 kit 无 `requirePhrase`、`./components` 未导出、adminLogs「60+ 完全一致」）已纠正。
+
+---
+
+## 0. 一句话结论
+
+| 目标 | 状态 |
+|---|---|
+| 可批量脚手架 CF admin 的 **FE foundation** | **进行中（主目标）** — 持续丰富 kit |
+| shop / lottery **消费 kit**（Bearer） | **完成** |
+| cf-auth **作为第 3 消费者检验 cookie 路径** | **0.2.5 起一等**（flag session + credentials 测 + recipes） |
+| 把 auth 业务页 / OAuth 流程做成 shop 同构 | **明确不做**（特殊性保留在产品） |
+| 再抽业务页 / 域 API / OAuth 全文案 | **明确不做** |
+
+**治理原则：** kit 只承载壳、表 UX、请求/**双会话模型**工厂、ConfigField、竞态 loader、i18n 种子、recipes。列定义、业务 API、域页面、**Better Auth/OAuth/白名单**留产品。新抽取须满足「≥2 真实消费者或第 3 路径验证出的通用缺口」；**禁止**为对齐 shop 而抹平 auth 特殊性。
+
+---
+
+## 一、已交付基线（0.2.3 → 0.2.4）
+
+### 组件
+
+| 组件 | 说明 |
+|---|---|
+| AdminShell | 侧栏 + 品牌 + 导航插槽 + 移动遮罩；**用户区默认顶栏右上**（侧栏底仅 `#sidebar-footer` 可选） |
+| AdminLoginShell | 登录页卡片外壳 |
+| AdminPagination | offset / cursor |
+| AdminModal | v-model / 键盘 / 焦点 |
+| ConfirmDialog | 可选勾选 + **requirePhrase** + danger |
+| ToastContainer | Teleport |
+| ConfigField | boolean/enum/cents/integer/string/textarea/sensitive |
+
+### Composables
+
+| API | 说明 |
+|---|---|
+| useTablePagination / useTableSelection | 表分页与多选 |
+| useConfirmDialog | 含 requirePhrase / options |
+| useToast / useAdminBatchOperation / useClipboard | 通知 / 批量 / 剪贴板 |
+| createAdminTokenSession | Bearer localStorage（8h TTL） |
+| **createAdminFlagSession** | Cookie 产品本地守卫 flag（**0.2.5**，cf-auth 验证） |
+| createAdminRequest (+ Raw) | `http-ok` \| `ok-envelope`；**credentials**；**onSuccess** heal |
+| useAdminSidebar / useAdminListLoader | 侧栏；列表竞态 loading/loadError |
+| useNow | 共享分钟级时钟（前台亦可） |
+
+### Utils / i18n / styles
+
+| 模块 | 说明 |
+|---|---|
+| datetime / csv-export / body-scroll-lock / currency-cents | 通用工具 |
+| admin-navigation | 401 handler / 路由决策 / 登录 redirect |
+| system-config-engine | 分组 / 计数 / 高级筛选 |
+| otp-input | OTP 数字规范化 |
+| adminKitMessages | pagination/confirm/modal/configField/layout/**adminLogs**/**adminConfig** |
+| mergeAdminKitMessages | kit 垫底，**host 覆盖** |
+| styles | tokens + admin-primitives（含 `.lang-select`）+ login-primitives |
+| recipes | Bearer 主路径 checklist + reexports |
+
+### 消费端接线（验收快照）
+
+| 产品 | kit 依赖 | 要点 |
+|---|---|---|
+| **cf-shop** | `file:../../cf-admin-fe` | Shell / LoginShell / 薄 re-export / token+request / system-config engine / **admin 列表 loader 全覆盖** / merge i18n |
+| **cf-lottery** | 同上 | 同上；loader 覆盖除 Dashboard / QuotaRedeem（非同构 race，有意不接） |
+| **cf-auth** | `file:../../cf-admin-fe` | **检验场**：`createAdminFlagSession` + cookie request/`onSuccess` + AdminShell/LoginShell + list loader；OAuth/health/白名单/域页留产品 |
+
+**测试（kit）：** vitest 全绿（含 useAdminListLoader / useNow / otp / ConfirmDialog requirePhrase）。
+
+---
+
+## 二、原 P 表实施对照
+
+| 原项 | 结论 |
+|---|---|
+| P0-1 cf-auth 迁 kit | **已完成**（cookie request + Shell + 组件/composable re-export + 最小 i18n） |
+| P1-1 adminLogs + adminConfig 种子 | **已进 kit**；产品侧改为 **kit 真相 + delta**（见收口） |
+| P2-1 useNow | **已进 kit**；shop 去重 re-export |
+| P2-2 otp-input | **已进 kit**；lottery 去重 re-export |
+| P2-3 语言切换 SFC | **不做**；CSS 已共享，handler 留产品 |
+| P2-4 menu divider | **不做**（可用 `#nav-extra`）；第 3 消费者再议 |
+| 6.1 `./components` 导出 | **已具备**（子路径 + `.vue` 双路径，推荐 subpath） |
+| 6.2 L3/cookie recipes | cookie 随 cf-auth 实装补短 recipe；L3 等痛点再现 |
+| 6.3 createAdminI18n | **不做**；`mergeAdminKitMessages` 已够 |
+
+### 原文档错误（已作废）
+
+- kit ConfirmDialog **无** requirePhrase → **现有**  
+- `./components` **未定义** → **已导出**  
+- adminLogs 两边「60+ 键完全相同」→ 实际 **共享 53**；lottery **+5** 特有  
+- preset*「仅 shop」→ 曾两边拷贝；**以 kit adminLogs 为共享真相**  
+- useNow/otp「暂不提取」→ **已提取**
+
+---
+
+## 三、结案后仍可选的残留项
+
+### R1 — cf-auth 迁 kit / cookie 一等路径
+
+**0.2.5：** kit 具备 `createAdminFlagSession`、`onSuccess`、credentials 测试、cookie recipes；auth **最小接线**验证。  
+**不是**把 auth 列表/登录业务改成 shop 副本。
+
+### R2 — i18n 单一真相
+
+**已完成策略落地：** kit 持共享 `adminLogs` + 扩展 `adminConfig` 通用键；shop/lottery 产品文件只留 **delta**。
+
+### R3 — 明确不做
+
+- 业务 `Admin*View`、域 API catalog、OAuth/PKCE/**Better Auth 流程**全文案  
+- 强迫 cookie 产品使用 Bearer token TTL / 密码-only 登录壳内容  
+- storefront `ShopView` catalog/deeplink sequence（非 admin）  
+- menu `divider` / `createAdminI18n` / 语言切换 SFC（无第 3 痛点不抽）  
+- npm publish（非用户明确要求不主动做）  
+- **通用组件库扩张**：日期选择器 / 级联 / 树 / 富文本 / 完整 DataTable 框架 —— 用现成轻量库，不与 Element Plus 比功能数  
+- **为以后可能有用而抽象**；只为「≥2 消费者已写同样代码」或已验证第 3 路径而提取  
+- 单产品特有逻辑（例：仅 lottery 的奖品池启发式）强行进 kit  
+
+**维护税提醒：** 每次改 kit 都要 shop + lottery + auth 不坏、跑满测试。三端分摊才值得；单端项目不必硬上 kit。
+
+### R4 — 持续丰富 kit（主线）
+
+从 **真实消费者缺口** 回填（auth 验证 cookie；shop/lottery 验证 Bearer/config），优先：
+
+- 已有能力的测试/文档/recipe 对称（Bearer ↔ Cookie）  
+- 仅当 ≥2 产品或明确第 3 路径需要时再加 API  
+- 禁止「为同构而同构」的产品侧大搬家
+
+**0.2.6 已回填（R4 切片）：**
+
+| Kit API | 来源缺口 | 接线 |
+|---|---|---|
+| `toErrorMessage` | auth 22× + shop/lottery catch 文案 | auth admin 页全量；shop vouchers loader；re-export useFormat |
+| `buildBatchToast` / `resolveBatchToastType` | auth `res.failed` toast；shop coupons；lottery platform members | 三端最小 |
+| `checkAdminBatchLimit` | auth 上限 20 / 硬删 10；shop 服务端 batch max(200) | auth 默认 20；shop Orders/Cards/EmailLogs/Logs 显式 `{ limit: 200 }` |
+| raw `onSuccess` | cookie heal 与 JSON 路径不对称 | kit only（下载场景） |
+
+**0.2.6 接线加深（不增 API）：** shop/lottery **admin 路径** 同构 `toErrorMessage` / `resolveBatchToastType` 批量替换；**不碰** storefront/会员前台；**不碰** 商品价格校验等带域前缀的 catch；产品 `useFormat` re-export 降低 import 噪音。
+
+**接线第二波：** `err.message || fb` / `err?.message || fb` / `onError: (err) => err?.message || fb` → `toErrorMessage`（admin + lottery platform）；成功路径 `res.message`、事件流 `event.message`、域前缀 catch **不改**；顺带去掉若干 `catch (err: any)`。
+
+**文档与注释：** kit README / recipes / 001 / 源码 JSDoc，以及 shop·lottery·auth 的薄再导出注释，统一为中文；用户可见默认兜底文案（如列表 `加载失败`、请求 `管理端请求失败：…`）同步中文化。i18n **en** 种子与 npm 包 `description` 字段可保留英文（面向英语宿主与 registry）。
+
+**封包前接线收口（不增 API）：**
+
+| 项 | 状态 |
+|---|---|
+| lottery admin/platform 批量 toast → `resolveBatchToastType` | 已补：Blacklist / Members / Redemption / Integrations / Prizes 启停 / Logs / Lottery 批量删与 toastBatch 助手 / Platform Webhooks |
+| shop `AdminLotteryView` 批量删 / `AdminLoginView` catch | 已接 `resolveBatchToastType` / `toErrorMessage` |
+| 邮件重试 `sent`/`failed`（非纯 success/failed 计数） | **刻意保留**域语义，不强行套 `AdminBatchCounts` |
+| 商品价格域前缀 catch、`api/admin` 重抛、`res.message` 成功文案 | **刻意保留** |
+| 前台 PayModal / 会员页 err.message | **不在 admin 边界**，不接线 |
+| `dist/` 过期根 `index.d.ts`（旧名 `@usethink/cf-admin`） | 已删除；`prepack` → `build` 再生成声明；包入口仍以 **`src/`** 为准 |
+
+
+**封包产物收口 + 0.2.6 尾巴：**
+
+| 项 | 状态 |
+|---|---|
+| `npm run clean` 清空 dist | 已加；`build`/`prepack` 先 clean 再 `tsc` |
+| `LICENSE`（MIT）纳入 `files` | 已加 |
+| 深路径 `./components/AdminMetadataDetail.vue` | 已导出 |
+| shop/lottery `AdminLogsView` 本地 `formatMetadata` | 已改再导出 kit |
+| lottery 列表 string `limit/offset` | **已结案**：`buildAdminOffsetParams`（平台审计 / 租户 / webhook / 兑换码） |
+| shop 服务端 batch 数量守卫 | **已结案**：Orders / Cards / EmailLogs / Logs → `checkAdminBatchLimit(..., { limit: 200 })`（后端 `max(200)`，**非**默认 20） |
+| shop number body offset 列表 | **有意不接** string helper；手写数字 `(page-1)*limit`（Balance / Recharges / Vouchers 等） |
+| 全量迁 `AdminMetadataDetail` 组件 | **明确不做旧页搬家**；纯函数已共享；**新审计详情页**优先用组件（P3 约定） |
+
+### R5 — 观察期（不增 API，直至 ≥2 同形消费者）
+
+| 候选 | 现状 | 触发条件 |
+|---|---|---|
+| `buildAdminOffsetNumbers`（number limit/offset） | shop 手写 1 行公式足够 | ≥2 产品出现同形 number filter 且复制粘贴成税 |
+| `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**。  
+**后续取舍与近端路线（含 P0 三件套、脚手架/文档站冻结条件）：** 见 [`003` 极致化方案与取舍](./003_cf-admin-fe极致化方案与取舍_2026-08-05.md)。
+
+---
+
+## 四、禁止提取（业务域 · 仍有效）
+
+### cf-shop
+
+类型 / `api/admin.ts` / 前台业务组件 / 17+ admin 业务页 / marketing·checkout 工具 / 业务 composables / 业务 i18n 命名空间。
+
+### cf-lottery
+
+games 组件 / 抽奖与平台页 / cf-auth-session·L3·impersonation / lottery UX 启发式 / 产品侧 useAdminAuth 扩展。
+
+### 共享库
+
+`@shared/money`、`@shared/order-status` 等 **不进** kit。
+
+---
+
+## 五、批量脚手架（现行）
+
+1. `npm i file:../cf-admin-fe`（或 registry 版本）  
+2. `@import` kit styles；根挂 `ToastContainer`  
+3. 复制 `recipes/`：auth / request / layout / guard / i18n-merge  
+4. 菜单、列、API、危险区文案留产品  
+5. 列表加载用 `useAdminListLoader`；配置页用 ConfigField + system-config-engine  
+
+活参考：**cf-shop**（Bearer）、**cf-lottery**（ok-envelope + L3 胶水）、**cf-auth**（cookie · R1）。
+
+---
+
+## 六、附录：路径
+
+- kit: `templates/cf-admin-fe`  
+- shop: `templates/cf-shop/frontend`  
+- lottery: `templates/cf-lottery/frontend`  
+- auth: `templates/cf-auth/frontend`  
+
+**分析方式:** 直接读源码 + key diff + typecheck/vitest；结案时以仓库为准，不以过期 P 表为准。