c-admin-kit 1.0.0 → 1.0.2

package/LLMS.md

@@ -0,0 +1,257 @@
+# C-Admin-Kit: AI Assistant Context & Guidelines
+
+> This document is designed for AI Coding Assistants (Cursor, GitHub Copilot, Claude Code, Antigravity, Windsurf, etc.) to understand the architectural rules, coding standards, and golden patterns of `c-admin-kit`.  
+> 🌐 **Live Demo & Playground**: [https://admin-kit.cheatppf.xyz](https://admin-kit.cheatppf.xyz)
+
+---
+
+## 🤖 Role & Instruction for AI
+
+When generating or refactoring Vue 3 + Element Plus admin pages using `c-admin-kit`:
+1. **Mandatory Prefix**: All components **MUST ALWAYS** use the `c-` prefix in template (e.g., `<c-simple-table>`, `<c-search-box>`, `<c-async-button>`). Never use `<simple-table>` or `<search-box>`.
+2. **Never Handwrite CRUD Glue Code**:
+   - Always use `useListPage` to manage search, reset, pagination, batch delete, state toggling, and routing.
+   - Always use `SearchFieldFactory` to declare search form fields. Do NOT manually construct verbose search option objects.
+3. **Async Action Safety**: Always use `<c-async-button :on-click="fn">` or `useConfirmSubmit` for asynchronous operations to automatically handle loading states and prevent double-clicks.
+4. **Style Import**: Ensure `import 'c-admin-kit/dist/c-admin-kit.css'` is present in `main.ts` or component.
+
+---
+
+## 📦 Import Signatures
+
+```typescript
+import {
+  // Components
+  CSimpleTable,
+  CSearchBox,
+  CAsyncButton,
+  CCollapsibleContainer,
+  CCustomDrawer,
+  CImagePreview,
+  CDiff,
+  CSelectWithAll,
+  CSelectWithPage,
+
+  // Composables / Hooks
+  useListPage,
+  useForm,
+  useDownload,
+  useConfirmAction,
+  useConfirmSubmit,
+  useDialog,
+
+  // Utilities & Factories
+  SearchFieldFactory,
+  CommonSearchFields,
+  listToTree,
+  treeToList,
+  findTreeNode,
+  findParentNodes,
+  filterTree,
+  mapTree,
+
+  // Types
+  type TableColumn,
+  type SearchField
+} from 'c-admin-kit'
+```
+
+---
+
+## Standard CRUD Page Pattern
+
+AI should use this template as the standard blueprint for any admin list view:
+
+```vue
+<template>
+  <div class="page-container">
+    <!-- 1. Search Box -->
+    <c-search-box
+      :fields="searchFields"
+      @search="handleSearch"
+      @reset="handleReset"
+    />
+
+    <!-- 2. Dynamic Adaptive Table -->
+    <c-simple-table
+      ref="tableRef"
+      :api="getUserListApi"
+      :columns="columns"
+      table-key="user_management_table"
+      auto-height
+    >
+      <!-- Header Action Bar -->
+      <template #headerLeft>
+        <c-async-button type="primary" :on-click="handleAdd">
+          新增用户
+        </c-async-button>
+        <el-button 
+          type="danger" 
+          :disabled="selectedRows.length === 0"
+          @click="handleBatchDelete(selectedRows)"
+        >
+          批量删除
+        </el-button>
+      </template>
+
+      <!-- Custom Actions Column Slot -->
+      <template #actions="{ row }">
+        <el-button link type="primary" @click="handleEdit(row)">编辑</el-button>
+        <el-button link type="warning" @click="changeState(row)">
+          {{ row.status === 1 ? '停用' : '启用' }}
+        </el-button>
+        <el-button link type="danger" @click="handleDelete(row)">删除</el-button>
+      </template>
+    </c-simple-table>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import {
+  CSimpleTable,
+  CSearchBox,
+  CAsyncButton,
+  SearchFieldFactory,
+  useListPage,
+  type TableColumn
+} from 'c-admin-kit'
+import {
+  getUserListApi,
+  deleteUserApi,
+  batchDeleteUserApi,
+  changeUserStatusApi
+} from '@/api/user'
+
+const selectedRows = ref<any[]>([])
+
+// 1. Standard CRUD Workflow Hook
+const {
+  tableRef,
+  handleSearch,
+  handleReset,
+  handleDelete,
+  handleBatchDelete,
+  changeState,
+  handleAdd,
+  handleEdit
+} = useListPage({
+  apiList: getUserListApi,
+  apiDelete: deleteUserApi,
+  apiBatchDelete: batchDeleteUserApi,
+  apiChangeState: changeUserStatusApi,
+  addPath: '/user/add',
+  editPath: '/user/edit'
+})
+
+// 2. Search Fields Declaration via Factory
+const searchFields = computed(() => [
+  SearchFieldFactory.input({ prop: 'keyword', label: '关键词' }),
+  SearchFieldFactory.select({
+    prop: 'status',
+    label: '状态',
+    options: [
+      { label: '启用', value: 1 },
+      { label: '停用', value: 0 }
+    ]
+  }),
+  SearchFieldFactory.dateRange({ prop: 'createTime', label: '创建时间' })
+])
+
+// 3. Columns Declaration (Supports dot-path nested properties like 'dept.name')
+const columns: TableColumn[] = [
+  { type: 'selection' },
+  { type: 'index', label: '序号' },
+  { prop: 'username', label: '用户名' },
+  { prop: 'department.name', label: '所属部门' },
+  { prop: 'status', label: '状态', type: 'status' },
+  { prop: 'createTime', label: '创建时间' },
+  { label: '操作', slot: 'actions', width: 180, fixed: 'right' }
+]
+</script>
+```
+
+---
+
+## 🧩 Component API & Contracts
+
+### 1. `CSimpleTable` (`<c-simple-table>`)
+- **Props**:
+  - `api`: `(params: Record<string, any>) => Promise<any>` - The API function to load page data.
+  - `columns`: `TableColumn[]` - Column definitions.
+  - `tableKey`: `string` - Unique identifier for column settings persistence.
+  - `autoHeight`: `boolean` - Automatically stretch to fill the viewport without page scrollbars (default `false`).
+  - `emptyCellText`: `string` - Placeholder for empty cell values (default `"-"`).
+  - `dragSort`: `boolean` - Enable drag-and-drop row sorting.
+  - `showPagination`: `boolean` - (default `true`).
+  - `params`: `Record<string, any>` - Static query parameters merged into fetch requests.
+- **Column Properties (`TableColumn`)**:
+  - `prop`: string (supports dot path like `"user.profile.name"`).
+  - `label`: string.
+  - `type`: `'selection' | 'index' | 'status' | 'drag'`.
+  - `slot`: string (custom cell slot name).
+  - `formatter`: `(row, col, value, index) => string`.
+  - `render`: `(row, col, index) => VNode`.
+- **Slots**:
+  - `#headerLeft`: Content on top-left (e.g. Add, Batch Delete).
+  - `#headerRight`: Content on top-right (e.g. Export, Custom Buttons).
+  - `#[column.slot]`: Custom column body cell slot with `{ row, column, $index }`.
+
+### 2. `CSearchBox` (`<c-search-box>`)
+- **Props**:
+  - `fields`: `SearchField[]` generated by `SearchFieldFactory`.
+  - `fieldsPerRow`: `number` (default `4`).
+  - `defaultExpanded`: `boolean` (default `false`).
+- **Events**:
+  - `@search`: `(params: Record<string, any>) => void`
+  - `@reset`: `(params: Record<string, any>) => void`
+  - `@field-change`: `({ prop, value, form }) => void`
+
+### 3. `CAsyncButton` (`<c-async-button>`)
+- **Props**:
+  - `:on-click`: `(e: MouseEvent) => Promise<any> | any` - When it returns a Promise or Thenable, the button automatically activates `loading` and disables itself until completion.
+
+### 4. `CCollapsibleContainer` (`<c-collapsible-container>`)
+- **Slots**: `#left`, `#right`.
+- **Props**: `defaultWidth: number` (default 240), `minWidth: number`, `maxWidth: number`.
+
+### 5. `CCustomDrawer` (`<c-custom-drawer>`)
+- **Props**: `v-model: boolean`, `title: string`, `size: string`, `confirmLoading: boolean`, `showFooter: boolean`.
+- **Events**: `@confirm`, `@cancel`, `@close`.
+
+---
+
+## 🛠️ Composables Cheat Sheet
+
+### `useListPage(options)`
+- Automatically coordinates `CSearchBox` and `CSimpleTable`.
+- Call `tableRef.value.refresh()` or `handleSearch()` to trigger reloads.
+- Call `handleDelete(row)` to trigger a standard danger confirmation modal before calling `apiDelete`.
+- Call `handleBatchDelete(rows)` with `apiBatchDelete` or `apiDelete.batch`.
+
+### `useForm(options)`
+- `submit(apiCall, successMsg, customTransform)`:
+  1. Validates form with `formRef.value.validate()`.
+  2. Blocks if validation fails.
+  3. Turns `loading.value = true`.
+  4. Calls `apiCall(formData)` and notifies success with `ElMessage.success`.
+- `reset()`: Resets fields and validation states safely.
+
+### `useDownload(apiFn, options)`
+- `const { download, downloading } = useDownload(exportApi, { filename: 'Report' })`
+- Automatically reads `content-disposition` from headers to name the download file.
+- Exposes `downloading: Ref<boolean>` for button loading status.
+
+### `treeManager`
+- `listToTree(flatArray, { id: 'id', pid: 'parentId', children: 'children' })`: O(n) Hash Map converter.
+- `treeToList(tree)`: Flattens hierarchical tree back to array.
+- `findParentNodes(tree, targetId)`: Returns array of ancestor nodes from root down to matched item.
+
+---
+
+## 🚫 Anti-Patterns (What AI Should NEVER Do)
+
+- ❌ **DO NOT** use native `<el-table>` for standard CRUD pages when `c-simple-table` is available.
+- ❌ **DO NOT** handwrite repetitive `pageSize`, `pageNum`, `currentPage` reactive variables; let `useListPage` and `c-simple-table` manage them.
+- ❌ **DO NOT** bind plain `@click` with manual `loading = true / false` on buttons when `<c-async-button :on-click="...">` can handle it declaratively.
+- ❌ **DO NOT** use un-prefixed tags like `<simple-table>`. Always prefix with `<c-simple-table>`.

package/README.md

@@ -1,110 +1,116 @@
-# C-Admin-Kit (企业级中后台组件与通用工具套件)
+# C-Admin-Kit
 
-`c-admin-kit` 是一套基于 **Vue 3 + Element Plus** 深度解耦的中后台高阶通用组件、配置工厂与 Hooks 工具套件。
+<p align="center">
+  <img src="https://img.shields.io/npm/v/c-admin-kit?color=409EFF&label=npm" alt="npm version" />
+  <img src="https://img.shields.io/npm/dm/c-admin-kit?color=67C23A&label=downloads" alt="downloads" />
+  <img src="https://img.shields.io/badge/Vue-3.3+-42b883?logo=vue.js" alt="vue" />
+  <img src="https://img.shields.io/badge/Element--Plus-2.3+-409EFF?logo=element" alt="element-plus" />
+  <img src="https://img.shields.io/badge/TypeScript-100%25-3178c6?logo=typescript" alt="typescript" />
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" />
+</p>
 
-> 📌 **团队命名规范**：为了彻底杜绝多项目复用时的全局组件同名冲突，所有组件**统一且固定强制使用 `c-` / `C` 前缀**（例如 `<c-simple-table>`, `<c-search-box>`），不支持自定义配置，保持团队代码规范高度统一。
+`c-admin-kit` 是一套专为企业级中后台打造的高阶通用组件与 Hooks 套件。基于 **Vue 3 + Element Plus + TypeScript** 构建，提供成熟的标准 CRUD 流程封装、配置化高级表格、多条件搜索工厂、异步防重按钮、平滑拖拽分栏及常用树形数据工具函数。
+
+> 🌐 **在线预览与交互演练场**：[https://admin-kit.cheatppf.xyz](https://admin-kit.cheatppf.xyz)  
+> 📌 **团队规范约束**：为彻底避免多工程复用时的组件同名冲突，所有组件**统一且固定强制使用 `c-` / `C` 前缀**（如 `<c-simple-table>`、`<c-search-box>`），开箱即用，代码风格统一。
+
+---
+
+## ✨ 核心特性
+
+- 🛡️ **100% TypeScript**：源码全量 TS 编写，严格类型定义，类型提示精确到组件 Props、Emits、Slots 及 Hook 泛型。
+- ⚡ **轻量纯净**：以 `peerDependencies` 消费宿主环境的 `vue`、`element-plus`，打包体积仅几十 KB，无多余冗余包，完美继承宿主主题变量。
+- 🎯 **开箱即用**：自带企业级增删改查最佳实践，配合 `useListPage` 与 `SearchFieldFactory`，10 余行代码即可完成完整页面。
+- 🌲 **Tree-Shaking**：支持全量安装与细粒度子路径按需导入，生产构建零多余冗余代码。
 
 ---
 
-## 📦 目录结构
-
-```text
-packages/admin-kit/
-├── src/
-│   ├── components/            # UI 通用组件 (CSimpleTable, CSearchBox 等)
-│   ├── composables/           # 通用 Hooks (useListPage, useForm 等)
-│   ├── utils/                 # 工具函数 (SearchFieldFactory, treeManager 等)
-│   └── index.js               # 统一主入口
-├── package.json
-├── vite.config.js
-└── README.md
+## 📥 安装
+
+在您的 Vue 3 + Element Plus 工程中执行：
+
+```bash
+# 推荐使用 pnpm
+pnpm add c-admin-kit
+
+# 或者 npm / yarn
+npm install c-admin-kit
+yarn add c-admin-kit
 ```
 
+> ⚠️ **前置依赖**：请确保项目已安装 `vue (>= 3.3.0)` 与 `element-plus (>= 2.3.0)`。
+
 ---
 
 ## 🚀 快速上手
 
-### 1. 全局完整引入 (main.js)
+### 1. 全局完整引入 (`main.ts` / `main.js`)
 
-```javascript
+```typescript
 import { createApp } from 'vue'
 import ElementPlus from 'element-plus'
 import 'element-plus/dist/index.css'
-import App from './App.vue'
 
-// 引入 c-admin-kit
 import CAdminKit from 'c-admin-kit'
-// 如已打包，可引入样式
-// import 'c-admin-kit/dist/style.css'
+import 'c-admin-kit/dist/c-admin-kit.css'
+
+import App from './App.vue'
 
 const app = createApp(App)
 app.use(ElementPlus)
-app.use(CAdminKit) // 自动注册所有 c- 开头组件
+app.use(CAdminKit) // 自动全局注册所有 c- 开头组件
 app.mount('#app')
 ```
 
-### 2. 局部按需引入 (推荐)
+### 2. 按需局部引入 (推荐)
+
+组件与 Hooks 均支持解构引入或子路径导入：
 
 ```vue
 <template>
-  <c-search-box :fields="searchFields" @search="handleSearch" />
-  <c-simple-table ref="tableRef" :api="apiList" :columns="columns" />
+  <c-search-box :fields="searchFields" @search="handleSearch" @reset="handleReset" />
+  <c-simple-table ref="tableRef" :api="getUserListApi" :columns="columns" auto-height />
 </template>
 
-<script setup>
-import { CSearchBox, CSimpleTable } from 'c-admin-kit'
-import { SearchFieldFactory } from 'c-admin-kit'
-import { useListPage } from 'c-admin-kit'
+<script setup lang="ts">
+import { CSearchBox, CSimpleTable, SearchFieldFactory, useListPage } from 'c-admin-kit'
+import 'c-admin-kit/dist/c-admin-kit.css'
 
-// 或细粒度引入:
+// 亦支持按子路径引用：
 // import { CSimpleTable } from 'c-admin-kit/components'
-// import { useListPage } from 'c-admin-kit/hooks'
+// import { useListPage } from 'c-admin-kit/composables'
 // import { SearchFieldFactory } from 'c-admin-kit/utils'
 </script>
 ```
 
 ---
 
-## 🧩 组件清单与模板标签规范
+## 典型用法：标准 CRUD 页面
 
-| 组件名 (PascalCase) | 模板标签 (kebab-case) | 功能描述 |
-| :--- | :--- | :--- |
-| **`CSimpleTable`** | `<c-simple-table>` | 800+ 行高级配置化表格：支持拖拽排序、列自定义显隐（本地缓存/API持久化）、动态自适应全屏高度、分页联动。 |
-| **`CSearchBox`** | `<c-search-box>` | 高阶配置化多条件表单搜索栏：支持响应式栅格、展开/收起两行、级联依赖、回车搜索。 |
-| **`CAsyncButton`** | `<c-async-button>` | 异步按钮：自动识别 Promise 并开启 loading，防止重复点击。 |
-| **`CSelectWithAll`** | `<c-select-with-all>` | 支持全选/半选/反选与防抖远程搜索的增强下拉框。 |
-| **`CSelectWithPage`**| `<c-select-with-page>`| 支持分页数据源、参数化键值对（`labelKey`/`valueKey`）与远程搜索的下拉框。 |
-| **`CCollapsibleContainer`** | `<c-collapsible-container>` | 左右双栏布局容器：支持鼠标按住分隔线拖拽缩放宽度、一键收起折叠。 |
-| **`CCustomDrawer`** | `<c-custom-drawer>` | 二次封装 el-drawer，标准化底部取消/确定按钮与事件流。 |
-| **`CDiff`** | `<c-diff>` | 纯前端字符级与行级文本/代码 Diff 对比可视化组件。 |
-| **`CImagePreview`** | `<c-image-preview>` | 缩略图展示与大图预览包装组件。 |
-
----
-
-## 🌟 黄金组合：10行代码搞定企业级增删改查页
-
-结合 `SearchFieldFactory`、`useListPage` 与 `CSearchBox`、`CSimpleTable`：
+结合 `SearchFieldFactory`、`useListPage`、`CSearchBox` 与 `CSimpleTable` 快速构建后台列表页：
 
 ```vue
 <template>
   <div class="page-container">
-    <!-- 1. 搜索表单 -->
+    <!-- 1. 结构化搜索栏 -->
     <c-search-box
       :fields="searchFields"
       @search="handleSearch"
       @reset="handleReset"
     />
 
-    <!-- 2. 数据表格 -->
+    <!-- 2. 高阶自适应表格 -->
     <c-simple-table
       ref="tableRef"
       :api="getUserListApi"
       :columns="columns"
-      table-key="user_list_table"
+      table-key="user_management_table"
       auto-height
     >
+      <!-- 头部操作区 -->
       <template #headerLeft>
         <el-button type="primary" @click="handleAdd">新增用户</el-button>
+        <el-button type="danger" @click="handleBatchDelete">批量删除</el-button>
       </template>
 
       <!-- 操作列插槽 -->
@@ -116,117 +122,217 @@ import { useListPage } from 'c-admin-kit'
   </div>
 </template>
 
-<script setup>
+<script setup lang="ts">
 import { computed } from 'vue'
-import { 
-  CSearchBox, 
-  CSimpleTable, 
-  SearchFieldFactory, 
-  useListPage 
+import {
+  CSearchBox,
+  CSimpleTable,
+  SearchFieldFactory,
+  useListPage,
+  type TableColumn
 } from 'c-admin-kit'
-import { getUserListApi, deleteUserApi, changeUserStatusApi } from '@/api/user'
-
-// 标准 CRUD 流控制
+import {
+  getUserListApi,
+  deleteUserApi,
+  batchDeleteUserApi,
+  changeUserStatusApi
+} from '@/api/user'
+
+// 1. 标准流程控制 Hook (集成搜索联动、分页维护、单条/批量删除、状态切换、详情/新增路由)
 const {
   tableRef,
   handleSearch,
   handleReset,
   handleDelete,
+  handleBatchDelete,
   handleAdd,
   handleEdit
 } = useListPage({
   apiList: getUserListApi,
   apiDelete: deleteUserApi,
+  apiBatchDelete: batchDeleteUserApi,
   apiChangeState: changeUserStatusApi,
   addPath: '/user/add',
   editPath: '/user/edit'
 })
 
-// 搜索字段快速定义 (SearchFieldFactory)
+// 2. 搜索字段快速配置工厂 (支持 input、select、dateRange、cascader、级联联动等)
 const searchFields = computed(() => [
-  SearchFieldFactory.input({ prop: 'username', label: '用户名' }),
+  SearchFieldFactory.input({ prop: 'keyword', label: '关键词' }),
   SearchFieldFactory.select({
     prop: 'status',
     label: '状态',
     options: [
-      { label: '正常', value: 1 },
+      { label: '启用', value: 1 },
       { label: '停用', value: 0 }
     ]
   }),
   SearchFieldFactory.dateRange({ prop: 'createTime', label: '创建时间' })
 ])
 
-// 列配置
-const columns = [
+// 3. 表格列配置 (原生支持 user.name 深度路径取值、空值 '-' 占位、拖拽排序、自定义列持久化)
+const columns: TableColumn[] = [
   { type: 'selection' },
   { type: 'index', label: '序号' },
   { prop: 'username', label: '用户名' },
+  { prop: 'department.name', label: '所属部门' }, // 支持嵌套深度字段
   { prop: 'status', label: '状态', type: 'status' },
   { prop: 'createTime', label: '创建时间' },
-  { label: '操作', slot: 'actions', width: 160, fixed: 'right' }
+  { label: '操作', slot: 'actions', width: 150, fixed: 'right' }
 ]
 </script>
 ```
 
 ---
 
-## 🛠️ 组合式函数 (Hooks) 说明
+## 🧩 组件清单 (Components)
+
+| 组件名 | 标签名称 | 功能特性 |
+| :--- | :--- | :--- |
+| **`CSimpleTable`** | `<c-simple-table>` | **高阶企业级表格**：集成拖拽排序、列自定义显隐（本地缓存/API持久化）、动态视口全屏自适应高度、嵌套属性链式取值（`dept.name`）、空单元格占位、分页联动。 |
+| **`CSearchBox`** | `<c-search-box>` | **配置化多条件搜索栏**：响应式栅格自适应、一键展开/收起、级联下拉异步联动、回车快捷搜索、自定义插槽扩展。 |
+| **`CAsyncButton`** | `<c-async-button>` | **异步防重按钮**：自动感知 Promise / Thenable 异步任务并开启 loading，阻断连续点击，结束自动恢复。 |
+| **`CCollapsibleContainer`** | `<c-collapsible-container>` | **左右双栏拖拽折叠布局**：支持鼠标拖拽分隔线缩放面板宽度（消除了微动效冲突，拖拽丝滑），支持一键折叠收起。 |
+| **`CCustomDrawer`** | `<c-custom-drawer>` | **标准化企业级抽屉**：统一底部确定/取消操作栏，内置确定按钮 `confirmLoading` 状态与 `computed` 双向绑定。 |
+| **`CImagePreview`** | `<c-image-preview>` | **缩略图与大图预览**：支持单图 URL、逗号分隔多图字符串及数组入参，内置安全容错清洗与缩略图悬浮动效。 |
+| **`CDiff`** | `<c-diff>` | **文本代码 Diff 视图**：纯前端实现基于编辑距离与相似度的字符级与行级差异可视化高亮。 |
+| **`CSelectWithAll`** | `<c-select-with-all>` | **全选下拉选择器**：支持一键全选/全不选、半选状态判断及防抖远程搜索。 |
+| **`CSelectWithPage`**| `<c-select-with-page>`| **大数据分页下拉**：支持自定义键值字段、关键词远程搜索与海量选项分页加载。 |
+
+---
+
+## 🛠️ 组合式函数 (Composables / Hooks)
 
-### 1. `useForm`
-管理表单数据与验证提交：
-```javascript
-const { formRef, formData, loading, submit, reset } = useForm({
-  initFormData: { name: '', email: '' }
+### 1. `useListPage` (标准列表页流程控制)
+管理列表搜索、刷新、分页、状态切换、单条/批量删除及路由跳转：
+```typescript
+const {
+  tableRef,
+  searchParams,
+  handleSearch,
+  handleReset,
+  handleDelete,
+  handleBatchDelete,
+  changeState,
+  exportExcel
+} = useListPage({
+  apiList: getListApi,
+  apiDelete: deleteApi,
+  apiBatchDelete: batchDeleteApi, // 可选独立批量删除接口
+  apiChangeState: updateStatusApi,
+  apiExport: exportApi
 })
+```
 
-// 提交自动开启 loading 并执行表单校验
+### 2. `useForm` (表单状态与提交流程)
+封装表单数据响应式模型、自动校验拦截与提交状态：
+```typescript
+const { formRef, formData, loading, submit, reset, setFormData } = useForm({
+  initFormData: { name: '', roleId: null }
+})
+
+// 提交时自动触发 form.validate()，校验失败自动提示并阻断，成功触发 loading 并调用 API
 await submit(async (data) => await saveApi(data), '保存成功')
 ```
 
-### 2. `useConfirmSubmit` & `useConfirmAction`
-操作二次确认弹窗：
-```javascript
-const handleDelete = useConfirmSubmit(
+### 3. `useDownload` (安全文件导出与下载)
+安全导出二进制文件，导出 `downloading` 响应式状态，自动从响应头提取文件名：
+```typescript
+const { download, downloading } = useDownload(exportApi, {
+  filename: '用户报表'
+})
+
+// 外部按钮可直接绑定 loading
+// <el-button :loading="downloading" @click="download({ deptId: 1 })">导出</el-button>
+```
+
+### 4. `useConfirmAction` & `useConfirmSubmit` (操作二次确认)
+消除重复的 `ElMessageBox.confirm` 模板代码：
+```typescript
+const handleRemove = useConfirmSubmit(
   async (id) => await deleteApi(id),
   () => tableRef.value.refresh(),
-  { message: '确定要永久删除该项吗？' }
+  { message: '确定要永久删除该记录吗？' }
 )
 ```
 
-### 3. `useDownload`
-安全下载导出文件（支持 Blob 异常解析）：
-```javascript
-const { download } = useDownload(exportApi, { filename: '用户数据导出' })
-await download({ keyword: 'test' })
+### 5. `useDialog` (弹窗显隐与上下文传递)
+优雅管理模态弹窗的开启、关闭与行数据传递：
+```typescript
+const { visible, dialogData, openDialog, closeDialog } = useDialog()
 ```
 
 ---
 
-## 🚀 独立成 Git 仓库指南
+## 🧰 实用工具库 (Utils)
+
+### 1. `SearchFieldFactory` (搜索字段工厂)
+规范化、声明式生成搜索栏配置：
+```typescript
+import { SearchFieldFactory, CommonSearchFields } from 'c-admin-kit'
+
+const fields = [
+  SearchFieldFactory.input({ prop: 'title', label: '标题' }),
+  SearchFieldFactory.select({ prop: 'status', label: '状态', options: [...] }),
+  SearchFieldFactory.dateRange({ prop: 'createTime', label: '创建时间' }),
+  SearchFieldFactory.cascader({ prop: 'deptId', label: '部门', options: [...] }),
+  // 常用预设快捷字段
+  CommonSearchFields.keyword(),
+  CommonSearchFields.status([...])
+]
+```
 
-若需要将 `packages/admin-kit` 作为一个独立的 Git 仓库推送到公司代码托管平台（如 GitLab/Gitee/GitHub）：
+### 2. `treeManager` (高性能树结构处理)
+```typescript
+import {
+  listToTree,
+  treeToList,
+  findTreeNode,
+  findParentNodes,
+  filterTree,
+  mapTree
+} from 'c-admin-kit'
 
-```bash
-# 1. 进入包目录
-cd packages/admin-kit
-
-# 2. 初始化独立 git 仓库
-git init
-git add .
-git commit -m "feat: init c-admin-kit package"
-
-# 3. 关联远程仓库并推送
-git remote add origin https://your-git-server.com/frontend/c-admin-kit.git
-git branch -M main
-git push -u origin main
+// 1. 扁平数组一键转树 (时间复杂度 O(n) Hash Map 算法)
+const tree = listToTree(flatList, { id: 'id', pid: 'parentId', children: 'children' })
+
+// 2. 根据节点 ID 查找包含自身和所有上级父节点的完整链条
+const parentNodes = findParentNodes(tree, targetId)
+
+// 3. 树结构过滤（保留命中节点及其祖先链路）
+const filteredTree = filterTree(tree, (node) => node.name.includes('技术部'))
 ```
 
-其他项目可通过 Git 依赖直接安装使用：
-```json
-{
-  "dependencies": {
-    "c-admin-kit": "git+https://your-git-server.com/frontend/c-admin-kit.git"
-  }
-}
+---
+
+## 🎮 Playground 交互演练台
+
+> 🔗 **线上演示地址**：[https://admin-kit.cheatppf.xyz](https://admin-kit.cheatppf.xyz)
+
+本项目包含同仓物理隔离的独立演练工程 `playground/`，**100% 消费并运行 NPM 官方已发布的真实 `c-admin-kit` 远端包与产物**，包含 6 大核心场景 Demo（CRUD 页面、左右拖拽容器、文本代码比对、抽屉组件、增强选择器、树算法测试台）：
+
+```bash
+# 启动本地演练场（真实加载 npm 已发布的 c-admin-kit）
+pnpm run dev:playground
+
+# 打包纯静态 SPA 站点（输出至 playground/dist/）
+pnpm run build:playground
+
+# 本地快速预览打包产物
+pnpm run preview:playground
 ```
-或在公司内部私有 NPM 源执行 `npm publish` 即可！
+
+### 🚀 部署至 Cloudflare Pages 步骤：
+1. 登录 Cloudflare 控制台，进入 **Workers & Pages** -> **Create application** -> **Pages** -> **Connect to Git**；
+2. 选择本仓库，配置构建设置：
+   - **Root directory**: `playground`
+   - **Framework preset**: `Vite`
+   - **Build command**: `pnpm run build`
+   - **Build output directory**: `dist`
+3. 点击 **Save and Deploy**，即可自动从 NPM 官方拉取最新发布的 `c-admin-kit` 并部署为全球 CDN 静态网页。
+
+---
+
+## 📄 授权协议
+
+[MIT License](file:///e:/售后项目/admin-kit/LICENSE) © 2026 [wllcyg](https://github.com/wllcyg)

package/llms.txt

@@ -0,0 +1,19 @@
+# c-admin-kit
+> High-level enterprise admin UI suite & composables built on Vue 3 + Element Plus + TypeScript.
+
+## Rules
+- All components MUST be prefixed with `c-` in template (e.g. `<c-simple-table>`, `<c-search-box>`, `<c-async-button>`).
+- Always prioritize `SearchFieldFactory` and `useListPage` to implement standard admin CRUD list pages.
+- Use `<c-async-button :on-click="fn">` for declarative async actions with automatic loading states.
+
+## Key Modules
+- `CSimpleTable`: Advanced table with column settings, auto-height, and pagination.
+- `CSearchBox`: Structured search form with responsive grid and cascade options.
+- `SearchFieldFactory`: Declarative factory for search fields (`input`, `select`, `dateRange`).
+- `useListPage`: Composable for search, pagination, delete, and route coordination.
+- `useForm`: Composable for form submission, validation, and reset.
+- `useDownload`: Composable for file export with `downloading` status and filename auto-detect.
+- `treeManager`: Utilities for `listToTree` (O(n)), `treeToList`, and `findParentNodes`.
+
+## Detailed Guidelines & Standard Patterns
+See [LLMS.md](./LLMS.md) for full contracts, component API, and standard CRUD blueprints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c-admin-kit",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "基于 Vue 3 + Element Plus 的中后台企业级高阶通用组件与 Hooks 套件（强制使用 c- 前缀）",
   "type": "module",
   "main": "./dist/c-admin-kit.umd.cjs",
@@ -37,7 +37,9 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "LLMS.md",
+    "llms.txt"
   ],
   "keywords": [
     "vue3",
@@ -81,6 +83,9 @@
   },
   "scripts": {
     "build": "vue-tsc --noEmit && vite build",
+    "dev:playground": "npm --prefix playground run dev",
+    "build:playground": "npm --prefix playground run build",
+    "preview:playground": "npm --prefix playground run preview",
     "typecheck": "vue-tsc --noEmit"
   }
 }