@usethink/cf-admin-fe 0.1.1 → 0.2.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usethink / cf-admin-fe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,104 +1,295 @@
 # @usethink/cf-admin-fe
 
-Vue 3 **admin foundation** for the Cloudflare product family (`cf-shop`, `cf-lottery`, future CF admin apps).
+面向 Cloudflare 产品家族（`cf-shop`、`cf-lottery`、`cf-auth` 以及未来的 CF 管理端应用）的 Vue 3 **管理端基础套件（admin foundation）**。
 
-This package is the **frontend** counterpart to backend `@usethink/cf-core`:
+**状态：** **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)**。
 
-| Layer | Package | Contents |
+**核心目标：** 最大化共享 **管理端前端基础套件**，让 CF 产品快速搭建 — **不**通过克隆业务页面实现，也 **不** 强迫每个产品套用 shop 的 Bearer 模式。
+
+| 会话模型 | 套件 | 线上消费方 |
+|---|---|---|
+| Bearer JWT + localStorage TTL | `createAdminTokenSession` | cf-shop, cf-lottery |
+| Cookie HTTP 会话 + 本地守卫标志 | `createAdminFlagSession` + `credentials: 'include'` + 可选 `onSuccess` | **cf-auth**（验证方，非克隆目标） |
+
+| 分层 | 包 | 内容 |
 |---|---|---|
-| Workers / infra | `@usethink/cf-core` | HTTP, crypto, media, secrets, … |
-| Admin UI kit | **`@usethink/cf-admin-fe`** | Composables, shell components, admin CSS tokens |
+| Workers / 基础设施 | `@usethink/cf-core` | HTTP、crypto、media、secrets 等 |
+| 管理端 UI 套件 | **`@usethink/cf-admin-fe`** | 表格 UX、shell、ConfigField、request/token 工厂、导航助手、i18n 种子、recipes、CSS |
+
+## 为什么叫 `cf-admin-fe`（而不是 `cf-admin`）
+
+**仅前端。** `-fe` 后缀使 UI 套件代码与 Worker/API 基础设施保持区分。
+
+**不是**业务中间层：不包含订单、抽奖、RBAC 产品页面或支付 UI。
+
+## 边界（新增 API 前请先阅读）
 
+`cf-admin-fe` 是 **管理端基础套件**，不是通用 Vue 组件库，也不是 Element Plus。
 
-## Why `cf-admin-fe` (not `cf-admin`)
+| 应做 | 不应做 |
+|---|---|
+| AdminPagination、AdminModal、ConfirmDialog、Toast、AdminShell、ConfigField | 日期选择器、级联、树、富文本、数据网格框架 |
+| 已被 **≥2 个线上消费方** 验证的纯函数助手（或经验证的第三条路径，如 cookie 认证） | “以后可能有用”的抽象 |
+| 轻量 request/session 工厂 + 列表加载器 + 导航助手 | 业务页面、OAuth 流程、抽奖 L3、商城结算 |
 
-This package is **frontend-only**. The `-fe` suffix makes that explicit next to backend `@usethink/cf-core`, so operators never confuse UI kit code with Worker/API infrastructure.
+**心智成本才是真正的成本。** 每次套件变更都必须让 cf-shop、cf-lottery、cf-auth 保持绿色（测试 + 类型检查）。有 3 个管理端时该成本可以摊销；只有 1 个管理端时就不值得。
 
-**Not** a business mid-tier: no orders, lottery draws, RBAC pages, or payment UIs.
+**提取气味的检验标准**
 
-## Install
+- 好：两个产品已经复制粘贴了同样的 10 行 → 提取。
+- 坏：只有 cf-lottery 需要 → 留在产品内。
+- 坏：为了“一致性”而包装第三方日期选择器 → 在产品里用轻量专用库。
+
+## 安装
 
 ```bash
-# monorepo / sibling template (recommended during development)
+# monorepo / 兄弟模板（开发期推荐）
 npm install file:../cf-admin-fe
 
-# or once published
+# 或发布后
 npm install @usethink/cf-admin-fe
 ```
 
-Peer: `vue` ^3.4.
+Peer 依赖：`vue` ^3.4。可选 peer 依赖：`vue-i18n`（组件在存在时会调用 `$t`）。
+
+---
+
+## 批量复制剧本（几分钟搭建新管理端）
+
+### 快速路径：复制 recipes
+
+包在 `recipes/` 下提供 **复制即用的起步代码**（monorepo 中也可通过 `@usethink/cf-admin-fe/recipes/*` import 路径阅读）：
+
+| Recipe | 用途 |
+|---|---|
+| `recipes/README.md` | 有序检查清单 |
+| `recipes/reexports/*` | 轻量 composable/组件/utils 再导出 |
+| `recipes/useAdminAuth.shop.ts` | 单键 Bearer 会话 |
+| `recipes/useAdminRequest.ts` | `createAdminRequest` + 401 处理器 |
+| `recipes/AdminLayout.vue` | `AdminShell` + 产品菜单 hooks |
+| `recipes/router-guard.snippet.ts` | `decideAdminRouteAccess` 守卫 |
+| `recipes/i18n-merge.snippet.ts` | `mergeAdminKitMessages` |
+| `recipes/main-styles.snippet.ts` | CSS 入口选项 |
+
+参考线上消费方：**cf-shop**（Bearer）、**cf-lottery**（Bearer + L3 胶水）、**cf-auth**（cookie + flag — 用于 **验证** 套件 cookie 路径，不要复制其 OAuth/业务页面）。
 
-## Quick start (new admin app)
+### 1. 接入包 + 样式 + 全局 toast
 
 ```ts
 // main.ts
 import { createApp } from 'vue'
 import App from './App.vue'
-import '@usethink/cf-admin-fe/styles' // tokens + admin primitives
-
-createApp(App).mount('#app')
+import '@usethink/cf-admin-fe/styles' // 或仅 primitives，见 assets/admin.css
+createApp(App).use(router).use(i18n).mount('#app')
 ```
 
 ```vue
-<script setup lang="ts">
-import {
-  useTablePagination,
-  useTableSelection,
-  useConfirmDialog,
-  useToast,
-  useAdminBatchOperation,
-} from '@usethink/cf-admin-fe'
-import {
-  AdminPagination,
-  ConfirmDialog,
-  ToastContainer,
-  AdminModal,
-} from '@usethink/cf-admin-fe/components'
-</script>
+<!-- App.vue：根节点挂一次 -->
+<ToastContainer />
 ```
 
-Products may keep thin re-exports under `@/composables/*` so existing views do not mass-rewrite.
+### 2. 导入清单（最大化复用套件——不要重新实现）
+
+| 需求 | 从哪导入 | 备注 |
+|---|---|---|
+| 表格分页/每页条数 | `useTablePagination` | `/composables` |
+| 多选 + shift 连选 | `useTableSelection` | |
+| 确认 + 可选复选框 | `useConfirmDialog` + `ConfirmDialog` | |
+| Toast 队列 | `useToast` + `ToastContainer` | |
+| 顺序批量操作 | `useAdminBatchOperation` | |
+| 剪贴板 | `copyWithToast`（管理端主路径）/ `copyText`（按钮反馈）/ `writeClipboardText`（静默或降级） | |
+| 弹窗 / 分页外壳 | `AdminModal` / `AdminPagination` | |
+| 系统配置卡片 | `ConfigField` | 枚举 + 分单位金额的超集 |
+| 侧边栏外壳 | `AdminShell` + `useAdminSidebar` | 菜单数据留在产品中 |
+| Bearer token 会话 | `createAdminTokenSession` | 多 key / 伪装 = 产品侧 |
+| Cookie 本地守卫标志 | `createAdminFlagSession` | HTTP cookie 是产品侧；flag 属于套件 |
+| 管理端 `fetch` | `createAdminRequest` | `http-ok` \| `ok-envelope`；cookie：`credentials` + `onSuccess` |
+| **401 → 登录页** | `createAdminUnauthorizedHandler` | 只注入 `clearSession` |
+| **路由守卫** | `decideAdminRouteAccess` | 之后再加产品专属规则 |
+| **登录重定向** | `resolveAdminLoginRedirect` | 防开放重定向 |
+| **i18n 种子** | `mergeAdminKitMessages` | `/i18n` — 宿主覆盖优先 |
+| 日期 | `formatDate` 等 | `/utils` |
+| 异常转字符串 | `toErrorMessage` | toast / loader `onError` |
+| 批量 toast 色调 | `resolveBatchToastType` / `buildBatchToast` | 纯函数；产品保留 i18n 键 |
+| 批量数量上限守卫 | `checkAdminBatchLimit` | **默认 20 = auth 风格**；对接 `max(N)` 的 API 须传 `{ limit: N }`（如 shop 批量删 `200`） |
+| 列表 limit/offset（**字符串**） | `buildAdminOffsetParams` / `applyAdminOffsetParams` | **仅** URLSearchParams / query string；产出 `{ limit: string, offset: string }` |
+| CSV 导出 | `downloadCsv`, `safeCsvCell` | 防公式注入 |
+| 遮罩滚动锁 | `lockBodyScroll` / `unlockBodyScroll` | 引用计数 |
+| 分 ↔ 元 | `formatCents`, `parseYuanToCents` | 多币种仍属产品侧 |
+
+**分页形态（必读，防误用）：**
+
+| 后端契约 | 做法 | 参考 |
+|---|---|---|
+| Query：`limit`/`offset` **字符串**（`URLSearchParams`） | `buildAdminOffsetParams(page, limit)` 或 `applyAdminOffsetParams` | **cf-lottery** 平台审计 / 租户 / webhook / 兑换码 |
+| Body 或类型化 filter：`limit`/`offset` **数字** | 产品手写 `offset: (page - 1) * limit`（数字） | **cf-shop** Balance / Recharges / Vouchers 等 |
+| Cursor | 产品自管；勿套 offset helper | shop 部分订单/日志列表 |
+
+**不要**为了「用上 helper」把 number body 改成 string query。number 形态 helper 仅当 **≥2 产品** 同形复制时再提案（观察期，见 `docs/002` §5.8）。
 
-## Public surface
+优先使用 **子路径** 导入（`/composables`、`/utils`、`/components/*.vue`、`/i18n`），避免 Vitest 解析根 SFC 桶文件。
 
-### Composables (`@usethink/cf-admin-fe` or `/composables`)
+### 3. 最小产品胶水层（保持精简）
 
-- `useTablePagination` — page/limit/total/offset
-- `useTableSelection` — multi-select + shift range
-- `useConfirmDialog` — confirm + optional checkboxes
-- `useToast` / `MAX_TOASTS` — global toast queue
-- `useAdminBatchOperation` — sequential batch with progress
-- `writeClipboardText` / `copyText` — clipboard helpers
+```ts
+// useAdminAuth — shop 简化版（见 recipes/useAdminAuth.shop.ts）
+import { createAdminTokenSession } from '@usethink/cf-admin-fe/composables'
+const session = createAdminTokenSession({ storageKey: 'admin_token' })
+export const readAdminToken = () => session.readToken()
+export function useAdminAuth() {
+  return { token: session.token, isLoggedIn: session.isLoggedIn, setToken: session.setToken, clearToken: session.clearToken }
+}
+```
 
-### Components (`@usethink/cf-admin-fe/components`)
+```ts
+// useAdminRequest — 尽量复用套件工厂
+import { createAdminRequest } from '@usethink/cf-admin-fe/composables'
+import { createAdminUnauthorizedHandler } from '@usethink/cf-admin-fe/utils'
+import { readAdminToken, useAdminAuth } from './useAdminAuth'
 
-- `AdminPagination`, `AdminModal`, `ConfirmDialog`, `ToastContainer`
+const onUnauthorized = createAdminUnauthorizedHandler({
+  clearSession: () => useAdminAuth().clearToken(),
+})
 
-Components use `$t(...)` for labels when `vue-i18n` is present; provide the usual keys (`pagination.*`, `confirm.*`, `adminModal.*`) in the host app.
+export const adminRequest = createAdminRequest({
+  getToken: () => readAdminToken(),
+  resultMode: 'ok-envelope', // shop 风格 body 可用 'http-ok'
+  errorField: 'message',
+  onUnauthorized,
+})
+```
 
-### Styles
+```ts
+// i18n — 填补套件键；菜单/品牌文案留产品
+import { mergeAdminKitMessages } from '@usethink/cf-admin-fe/i18n'
+messages: {
+  'zh-CN': mergeAdminKitMessages(zhHost, 'zh-CN'),
+  en: mergeAdminKitMessages(enHost, 'en'),
+}
+```
+
+```ts
+// router — 先走共享门禁
+import { decideAdminRouteAccess } from '@usethink/cf-admin-fe/utils'
+const d = decideAdminRouteAccess({ hasToken: !!readAdminToken(), requiresAuth: to.meta.requiresAuth, requiresGuest: to.meta.requiresGuest, fullPath: to.fullPath })
+if (d.type === 'login') return { name: 'AdminLogin', query: { redirect: d.redirect }, replace: true }
+if (d.type === 'home') return { name: 'AdminDashboard', replace: true }
+// 产品专属：引导 / 平台角色 / …
+```
+
+产品可将路径别名（`@/composables/*`）保留为 **再导出**，这样视图无需大规模改写。
+
+### 4. 必须留在产品侧的内容（不要强行塞进套件）
+
+- 业务管理端**页面**（`views/admin/*`、抽奖 `views/platform/*` 页面主体）
+- 菜单项列表、页面标题、品牌名（传入 `AdminShell`）
+- 业务 API 模块（`api/admin.ts` 的**方法面** / 业务 DTO）— 只有传输层使用 `createAdminRequest`
+- 多租户伪装 / 平台角色键（抽奖 L3）；使用 `AdminShell` 上的 `#banner` / `#nav-extra` 插槽
+- Cookie-flag 管理端（cf-auth）— 认证模型不同；仍可使用分页/toast/弹窗/utils
+- 订单状态 / 多币种金额库（`@shared/money`、订单状态映射）
+- 抽奖列表 UX 启发式（`admin-list-ux`）
+- 产品错误类型（`AdminApiError`）与业务下载方法签名（围绕 `createAdminRequestRaw` 的 token 优先包装）
+- 套件原语之外的业务专属 CSS（伪装横幅、语言选择、平台导航强调色）
+
+### 5. i18n
+
+**推荐：** `mergeAdminKitMessages(host, locale)`，这样新产品永远不会遗漏套件键。
+
+宿主仍应提供产品菜单（`adminLayout.menu*`）与业务字符串。字段级配置文案：`adminConfig.fields.<key>.{label,description,effect}` — 缺失时 ConfigField 通过 `$te` 回退到后端文本。
+
+---
+
+## 公开 API 面
+
+### 根 / composables
+
+- `useTablePagination`、`useTableSelection`、`useConfirmDialog`、`useToast`、`MAX_TOASTS`
+- `useAdminBatchOperation`、`writeClipboardText`、`copyText`、`copyWithToast`（剪贴板 + 成功/失败 toast；与按钮内反馈的 `copyText` 互补）
+- `createAdminTokenSession`、`useAdminTokenSession`、`parseStoredAdminToken`、`readAdminTokenFromStorage`、`DEFAULT_ADMIN_TOKEN_TTL_MS`
+- `createAdminRequest`、`createAdminRequestRaw`、`AdminRequestError`
+- `useAdminSidebar`
+- `useAdminListLoader` — 列表页的竞态安全 `loading` / `loadError` / 序列
+
+### Utils（`@usethink/cf-admin-fe/utils`）
+
+- 日期时间：`formatDate`、`toDateTimeLocalValue`、`dateTimeLocalToIso`、`isoToDateTimeLocal`、`formatIpFingerprint`
+- CSV：`downloadCsv`、`safeCsvCell`
+- 滚动：`lockBodyScroll`、`unlockBodyScroll`、`isBodyScrollLocked`
+- 金额最小单位：`normalizeCents`、`formatCents`、`parseYuanToCents`
+- 导航：`createAdminUnauthorizedHandler`、`decideAdminRouteAccess`、`resolveAdminLoginRedirect`
+- 错误：`toErrorMessage`
+- 批量 UX 纯函数：`buildBatchToast`、`resolveBatchToastType`、`formatBatchCountsMessage`、`formatDefaultBatchMixedMessage`、`hasBatchFailures`、`checkAdminBatchLimit`、`DEFAULT_ADMIN_BATCH_LIMIT`（**默认 20**；产品 `max(N)` 须显式 `limit`）
+- 列表查询：`buildAdminOffsetParams`、`applyAdminOffsetParams`（1-based 页码 → **`limit`/`offset` 字符串**，面向 URLSearchParams；**不是** number body filter）
+- 日志元数据：`formatMetadata`（安全 `JSON.stringify`，抗循环引用；旧页可只用纯函数）
+- 系统配置引擎（纯函数）：`groupDefinitionsByName`、`countSectionItems`、`buildActiveGroupedDefinitions`、`countAdvancedItems`、`resolveSystemConfigSectionId`、`getSystemConfigSection`、`listedSystemConfigGroups`、`auditSystemConfigSectionCoverage` — 分节 id 联合、分组列表、危险区、API 由产品侧负责
+
+### i18n（`@usethink/cf-admin-fe/i18n`）
+
+- `adminKitMessages`、`adminKitMessagesZhCN`、`adminKitMessagesEn`、`mergeAdminKitMessages`
+
+### 组件（`@usethink/cf-admin-fe/components`）
+
+- `AdminPagination`、`AdminModal`、`ConfirmDialog`、`ToastContainer`
+- `ConfigField`（boolean / 枚举多选 / integer / cents / sensitive / textarea）
+- `AdminShell`（响应式侧边栏 + header / nav-extra / banner 插槽）
+- `AdminLoginShell`（展示型登录卡片外壳；认证表单由产品侧实现）
+- `AdminMetadataDetail`（审计日志详情弹层；依赖宿主 `adminLogs.*` i18n 键；**新页优先**；已有自研详情 markup 的旧页不必强迁）
+
+### 类型（`@usethink/cf-admin-fe/types`）
+
+- `AdminSystemConfigFieldDefinition` / 别名 `AdminSystemConfigDefinition`、`ConfigFieldStatus` 等
+
+### 样式
 
 ```ts
 import '@usethink/cf-admin-fe/styles'
-// or granular:
+// 或按需：
 import '@usethink/cf-admin-fe/styles/tokens.css'
-import '@usethink/cf-admin-fe/styles/admin-primitives.css'
+import '@usethink/cf-admin-fe/styles/admin-primitives.css' // 含 .lang-select
+import '@usethink/cf-admin-fe/styles/login-primitives.css'  // .admin-login / .login-card
 ```
 
-## What stays in the product
+### Recipes
 
-- Domain admin **pages** (`views/admin/*`)
-- Auth/session composables, API clients, ConfigField registries
-- Product-only CSS beyond the shared primitives
+参见 [`recipes/README.md`](./recipes/README.md)。列表骨架见 `recipes/list-page.snippet.ts`（含 **string vs number offset**、批量 `limit` 注释）。
 
-## Develop
+### 说明书与接线对照
+
+- **完整用法 / 注意事项：** [`docs/002_cf-admin-fe使用说明书与注意事项.md`](./docs/002_cf-admin-fe使用说明书与注意事项.md)
+- **cf-shop 已接线什么、故意不接什么：** 同文档 **§5.8**
+- **提取决策与结案残留：** [`docs/001_…差距分析`](./docs/001_cf-admin-fe提取差距分析报告_2026-08-05.md)（勿当待办路线图）
+
+## 开发与封包
 
 ```bash
 npm install
 npm test
 npm run type-check
+npm run clean    # 清空 dist/，避免过期声明混入
+npm run build    # clean + 仅生成 composables/utils/types 的 .d.ts
+npm pack         # 触发 prepack→build；入口仍以 src/ 为准
 ```
 
-## License
+**封包注意：**
+
+- `files` 含 `src`、`dist`、`recipes`、`README.md`、`LICENSE`
+- `dist/` 在 `.gitignore` 中，由 `prepack` 现场生成；**不要**手写或提交旧版根 `dist/index.d.ts`
+- 运行时 `exports` 指向 **`src/`**（Vue SFC + TS 源）；`dist` 仅为声明辅助
+
+## 版本记录
+
+- **0.1.x** — 表格/toast/弹窗/分页原语
+- **0.2.0** — 深度提取：ConfigField、AdminShell、token/request 工厂、日期时间/CSV/滚动/分位金额工具
+- **0.2.1** — 导航助手、i18n 合并种子、recipes
+- **0.2.2** — 系统配置纯函数引擎、`createAdminRequestRaw`、`AdminSystemConfigDefinition` 别名
+- **0.2.3** — `useAdminListLoader`、`AdminLoginShell` + login-primitives CSS、原语中的 `.lang-select`
+- **0.2.4** — OTP 助手、更深化的 recipes
+- **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 门禁）
+
+## 许可证
 
-MIT
+MIT（见仓库根目录 `LICENSE`）

package/dist/composables/createAdminFlagSession.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cookie 会话产品用的本地布尔管理端守卫 flag。
+ *
+ * 真正的会话在 HTTP cookie（Better Auth 等）；此处只存 localStorage 快路径标记，
+ * 供路由守卫使用——与 Bearer 产品的 {@link createAdminTokenSession} 对称。
+ *
+ * 产品负责：健康探测、登录/登出、OAuth/PKCE、ADMIN_* 白名单。
+ * 套件负责：单 key 读写 + 一个 Vue ref 句柄（在模块作用域创建一次）。
+ */
+import { type ComputedRef, type Ref } from 'vue';
+export declare const DEFAULT_ADMIN_FLAG_TRUTHY = "1";
+export type CreateAdminFlagSessionOptions = {
+    /** localStorage 键名（如 `cf_auth_admin_ok`） */
+    storageKey: string;
+    /** 已登录时写入的值；默认 `'1'` */
+    truthyValue?: string;
+    /** 覆盖存储实现（测试用）；默认在可用时用 `localStorage` */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+};
+export declare function readAdminFlagFromStorage(storageKey: string, storage?: CreateAdminFlagSessionOptions['storage'], truthyValue?: string): boolean;
+export declare function writeAdminFlagToStorage(storageKey: string, ok: boolean, options?: {
+    storage?: CreateAdminFlagSessionOptions['storage'];
+    truthyValue?: string;
+}): void;
+export type AdminFlagSession = {
+    /** 与 storage flag 同步的响应式镜像 */
+    loggedIn: Ref<boolean>;
+    isLoggedIn: ComputedRef<boolean>;
+    /** 读 storage（作为 session.readFlag 调用时也可刷新 ref） */
+    readFlag: () => boolean;
+    /** 唯一写入入口：true 写入 truthy，false 删除键 */
+    writeFlag: (ok: boolean) => void;
+    markLoggedIn: () => void;
+    clearSession: () => void;
+    storageKey: string;
+    truthyValue: string;
+};
+/**
+ * Cookie 管理端本地守卫 flag 的 Vue 会话句柄。
+ * 在产品模块作用域 **创建一次**（与 createAdminTokenSession 同模式）。
+ */
+export declare function createAdminFlagSession(options: CreateAdminFlagSessionOptions): AdminFlagSession;

package/dist/composables/createAdminRequest.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 产品管理端 HTTP 客户端工厂。
+ *
+ * CF 各产品差异点：
+ * - 认证：Bearer JWT（shop/lottery）vs cookie 会话（cf-auth）
+ * - 成功判定：仅 `res.ok` vs `res.ok && data.ok`
+ * - 错误字段：`error` vs `message`
+ * - 401 副作用：清 token / 整会话清空 / 跳转登录
+ * - Token 来源：闭包 `getToken` vs 每次调用传 `token`（shop 的 api/admin.ts）
+ *
+ * 业务 API 方法仍在产品侧；此处只统一 fetch、请求头与 401 处理。
+ */
+export type AdminRequestResultMode = 'http-ok' | 'ok-envelope';
+/** 结构化错误，便于产品映射到 AdminApiError，无需再解析 message 字符串。 */
+export declare class AdminRequestError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly data: Record<string, unknown>;
+    readonly response?: Response;
+    constructor(message: string, status: number, options?: {
+        code?: string;
+        data?: Record<string, unknown>;
+        response?: Response;
+    });
+}
+export type CreateAdminRequestOptions = {
+    /** 可选 API 前缀（如 `''` 或 origin）。path 仍可为绝对地址。 */
+    baseUrl?: string;
+    /** 返回当前 Bearer token；省略/空 → 不带 Authorization */
+    getToken?: () => string | null | undefined;
+    /** fetch credentials；cookie 管理端用 `include` */
+    credentials?: RequestCredentials;
+    /**
+     * - `http-ok`：`res.ok` 即成功（cf-shop admin.ts 风格；body 可无 `ok`）
+     * - `ok-envelope`：`res.ok && data.ok`（lottery / 多数列表接口）
+     */
+    resultMode?: AdminRequestResultMode;
+    /** 构造 Error 时优先取 `error`（shop）或 `message`（lottery） */
+    errorField?: 'error' | 'message' | 'auto';
+    /** HTTP 401 且抛错前调用；产品负责清会话并跳转登录 */
+    onUnauthorized?: (ctx: {
+        path: string;
+        data: Record<string, unknown>;
+        response: Response;
+    }) => void;
+    /**
+     * 成功响应被接受后调用（http-ok / ok-envelope）。
+     * Cookie 管理端用来「治愈」缺失的本地守卫 flag，无需每个调用点包一层（cf-auth 模式）。
+     * Bearer 产品通常省略。
+     */
+    onSuccess?: (ctx: {
+        path: string;
+        data: Record<string, unknown>;
+        response: Response;
+    }) => void;
+    /**
+     * 为 false 时：401 仍抛错，但跳过 onUnauthorized
+     * （登录探测 token 时不得清掉已有会话）。
+     */
+    redirectOnUnauthorized?: boolean;
+    /** 默认请求头，会被单次调用的 headers 覆盖合并 */
+    defaultHeaders?: HeadersInit;
+    /**
+     * 跳过跳转时（token 探测）401 文案覆盖。
+     * Shop 使用固定「管理令牌无效」与 code INVALID_ADMIN_TOKEN。
+     */
+    unauthorizedProbeMessage?: string;
+    unauthorizedProbeCode?: string;
+};
+export type AdminRequestCallOptions = RequestInit & {
+    /** 查询参数；undefined / '' 会跳过 */
+    params?: Record<string, string | number | boolean | Array<string | number> | undefined | null>;
+    /** 覆盖工厂对本调用的 redirectOnUnauthorized 默认 */
+    redirectOnUnauthorized?: boolean;
+    /**
+     * 单次调用的 Bearer token（shop 每个域 API 方法都会传入）。
+     * 已设置时（含空字符串）覆盖工厂 `getToken`。
+     */
+    token?: string | null;
+};
+export type AdminRequestFn = <T = unknown>(path: string, options?: AdminRequestCallOptions) => Promise<T>;
+/**
+ * 非 JSON 管理端请求（blob 模板 / 导出下载）。
+ * 不解析成功 body；只检查 `res.ok` 并处理 401。
+ */
+export type AdminRequestRawFn = (path: string, options?: AdminRequestCallOptions) => Promise<Response>;
+/**
+ * 构建可复用的 `adminRequest(path, init)`。
+ */
+export declare function createAdminRequest(factory?: CreateAdminRequestOptions): AdminRequestFn;
+/**
+ * 构建 raw `adminRequestRaw(path, init)`，用于二进制 / 非 JSON 响应。
+ * 与 {@link createAdminRequest} 共享 token、params、headers 与 401 行为。
+ */
+export declare function createAdminRequestRaw(factory?: CreateAdminRequestOptions): AdminRequestRawFn;

package/dist/composables/createAdminTokenSession.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 通用管理端 Bearer token 会话（localStorage + TTL）。
+ *
+ * 产品在其上叠加产品专属 key / 伪装 / 平台角色。
+ * Cookie 会话产品改用 {@link createAdminFlagSession}（无 Bearer）。
+ */
+import { type ComputedRef, type Ref } from 'vue';
+export type StoredAdminToken = {
+    token: string;
+    expiry: number;
+};
+export declare const DEFAULT_ADMIN_TOKEN_TTL_MS: number;
+export type CreateAdminTokenSessionOptions = {
+    /** localStorage 键名（如 `admin_token`） */
+    storageKey: string;
+    /** 会话有效期；默认 8 小时，对齐常见 verify-jwt 会话 JWT */
+    ttlMs?: number;
+    /** 覆盖存储实现（测试用）；默认在可用时用 `localStorage` */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+};
+/**
+ * 解析已存储的 token 记录。
+ * - 含 token+expiry 的对象：遵守 TTL；过期则清除键
+ * - 旧版裸字符串：保留一次迁移（不自动清除）
+ */
+export declare function parseStoredAdminToken(raw: string | null, options?: {
+    storageKey?: string;
+    storage?: CreateAdminTokenSessionOptions['storage'];
+}): string;
+export declare function readAdminTokenFromStorage(storageKey: string, storage?: CreateAdminTokenSessionOptions['storage']): string;
+export type AdminTokenSession = {
+    token: Ref<string>;
+    isLoggedIn: ComputedRef<boolean>;
+    setToken: (value: string) => void;
+    clearToken: () => void;
+    readToken: () => string;
+    storageKey: string;
+    ttlMs: number;
+};
+/**
+ * 单个管理端 token 键的 Vue 会话句柄。
+ * 在 setup 外的路由守卫中调用 `readToken`。
+ */
+export declare function createAdminTokenSession(options: CreateAdminTokenSessionOptions): AdminTokenSession;
+/**
+ * 便捷组合式：默认键 `admin_token`、8 小时 TTL（cf-shop 形态）。
+ * 多租户 / 伪装登录产品应直接调用 {@link createAdminTokenSession}。
+ */
+export declare function useAdminTokenSession(options?: Partial<CreateAdminTokenSessionOptions>): AdminTokenSession;

package/dist/composables/index.d.ts

@@ -3,4 +3,10 @@ export { useTableSelection, type UseTableSelectionOptions, } from './useTableSel
 export { useConfirmDialog, type ConfirmOptionDef, type ConfirmAskOptions, type ConfirmResult, } from './useConfirmDialog';
 export { useToast, MAX_TOASTS, type ToastType, type ToastItem, } from './useToast';
 export { useAdminBatchOperation, type AdminBatchOperationResult, } from './useAdminBatchOperation';
-export { writeClipboardText, copyText, } from './useClipboard';
+export { writeClipboardText, copyText, copyWithToast, type CopyWithToastOptions, } from './useClipboard';
+export { createAdminTokenSession, useAdminTokenSession, parseStoredAdminToken, readAdminTokenFromStorage, DEFAULT_ADMIN_TOKEN_TTL_MS, type StoredAdminToken, type CreateAdminTokenSessionOptions, type AdminTokenSession, } from './createAdminTokenSession';
+export { createAdminFlagSession, readAdminFlagFromStorage, writeAdminFlagToStorage, DEFAULT_ADMIN_FLAG_TRUTHY, type CreateAdminFlagSessionOptions, type AdminFlagSession, } from './createAdminFlagSession';
+export { createAdminRequest, createAdminRequestRaw, AdminRequestError, type CreateAdminRequestOptions, type AdminRequestCallOptions, type AdminRequestFn, type AdminRequestRawFn, type AdminRequestResultMode, } from './createAdminRequest';
+export { useAdminSidebar, type UseAdminSidebarOptions, type UseAdminSidebarReturn, } from './useAdminSidebar';
+export { useAdminListLoader, type UseAdminListLoaderOptions, type UseAdminListLoaderReturn, type AdminListLoadContext, type AdminListRunLoadOptions, } from './useAdminListLoader';
+export { useNow, } from './useNow';

package/dist/composables/useAdminListLoader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 后台列表通用的加载生命周期：loading / loadError / 竞态安全的序号。
+ * 业务请求、列定义、筛选逻辑保留在产品页面中。
+ */
+import { type Ref } from 'vue';
+export type UseAdminListLoaderOptions = {
+    /** 初始加载状态（默认 false）。 */
+    initialLoading?: boolean;
+};
+export type AdminListLoadContext = {
+    /** 本次尝试的单调递增序号。 */
+    sequence: number;
+    /** 若有更新的加载已开始（或调用了 invalidate），返回 true。 */
+    isStale: () => boolean;
+};
+export type AdminListRunLoadOptions = {
+    /**
+     * 将抛出的错误映射为面向用户的 loadError 字符串。
+     * 默认：Error.message 或 String(err)。
+     */
+    onError?: (err: unknown) => string;
+};
+export type UseAdminListLoaderReturn = {
+    loading: Ref<boolean>;
+    loadError: Ref<string>;
+    /** 递增序号、置 loading 为 true、清空 loadError；返回本次尝试的序号。 */
+    beginLoad: () => number;
+    isStale: (sequence: number) => boolean;
+    /** 仅当序号仍为最新时清除 loading。 */
+    finishLoad: (sequence: number) => void;
+    /**
+     * 若序号仍为最新则记录错误信息。
+     * @returns 错误是否已生效（未被判定为过期）
+     */
+    failLoad: (sequence: number, message: string) => boolean;
+    /**
+     * 完整且竞态安全的加载流程：begin → work → catch → finish。
+     * work 内部在 await 之后应通过 `ctx.isStale()` 提前返回。
+     * @returns 若尝试未抛错且 try 结束时未过期，返回 true
+     */
+    runLoad: (work: (ctx: AdminListLoadContext) => void | Promise<void>, options?: AdminListRunLoadOptions) => Promise<boolean>;
+    /** 使进行中的加载失效（例如组件卸载时）。 */
+    invalidate: () => void;
+};
+export declare function useAdminListLoader(options?: UseAdminListLoaderOptions): UseAdminListLoaderReturn;

package/dist/composables/useAdminSidebar.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 响应式后台侧边栏状态（1024px 以下显示汉堡菜单）。
+ * 布局骨架由产品方维护；这里只负责媒体查询与打开状态。
+ */
+import { type Ref } from 'vue';
+export type UseAdminSidebarOptions = {
+    /** matchMedia 查询条件；默认 `(max-width: 1023px)` */
+    query?: string;
+};
+export type UseAdminSidebarReturn = {
+    isMobile: Ref<boolean>;
+    sidebarOpen: Ref<boolean>;
+    toggleSidebar: () => void;
+    closeSidebar: () => void;
+    openSidebar: () => void;
+};
+export declare function useAdminSidebar(options?: UseAdminSidebarOptions): UseAdminSidebarReturn;