imean-service-engine-htmx-plugin 1.2.1 → 2.1.0

package/README.md

@@ -1,2407 +1,272 @@
-# HtmxAdminPlugin 完整文档
+# HtmxAdminPlugin v2
 
-基于 HTMX + Tailwind CSS + Hyperscript + JSX 的管理后台插件，采用后端驱动的统一响应架构，支持快速构建现代化的管理后台系统。
+基于 PageModel 和 Feature 的简化管理后台插件。
 
-## 目录
+## 设计理念
 
-- [概述](#概述)
-- [核心特性](#核心特性)
-- [架构设计](#架构设计)
-- [快速开始](#快速开始)
-- [模块类型](#模块类型)
-- [使用相同模块名完成 CRUD](#使用相同模块名完成-crud)
-- [数据源](#数据源)
-- [组件系统](#组件系统)
-- [路由系统](#路由系统)
-- [响应机制](#响应机制)
-- [错误处理](#错误处理)
-- [高级功能](#高级功能)
-- [API 参考](#api-参考)
-- [最佳实践](#最佳实践)
-- [示例项目](#示例项目)
+### 核心原则
 
-## 概述
-
-HtmxAdminPlugin 是一个功能完整的管理后台插件，通过简单的配置即可生成包含列表、详情、表单等页面的完整管理系统。插件采用后端驱动的统一响应架构，所有响应都通过 `HX-Retarget` 响应头明确指定目标容器，简化前端代码。
-
-### 技术栈
-
-- **HTMX**: 用于动态内容加载和部分页面更新
-- **Tailwind CSS**: 用于样式设计
-- **Hyperscript**: 用于客户端交互逻辑
-- **Hono/jsx**: 用于服务端 JSX 渲染
-- **TypeScript**: 完整的类型支持
-
-### 设计理念
-
-1. **后端驱动**: 所有响应都通过后端响应头控制，前端无需指定 `hx-target` 或 `hx-swap`
-2. **统一架构**: 使用 OOB (Out-of-Band) 交换机制统一处理页面更新
-3. **类型安全**: 完整的 TypeScript 类型定义
-4. **可扩展**: 通过继承基类和重写方法实现自定义
-5. **零配置**: 默认配置即可使用，支持深度定制
-
-## 核心特性
-
-### ✨ 主要功能
-
-- ✅ **自动路由生成**: 根据模块类型自动生成 RESTful 路由
-- ✅ **列表页面**: 自动生成列表页，支持分页、筛选、排序
-- ✅ **详情页面**: 支持字段分组、自定义渲染、完全自定义
-- ✅ **表单页面**: 支持新建/编辑，表单验证，多种字段类型
-- ✅ **自定义页面**: 完全自定义的页面渲染
-- ✅ **模态对话框**: 支持弹窗模式查看和编辑，不丢失列表状态
-- ✅ **错误处理**: 统一的错误处理机制，全局错误通知
-- ✅ **URL 状态管理**: 筛选和分页状态记录在 URL 中
-- ✅ **响应式设计**: 适配移动端和桌面端
-- ✅ **动画效果**: 对话框和错误通知的流畅动画
-
-### 🎨 UI 特性
-
-- 现代化的界面设计
-- 流畅的页面切换动画
-- 全局加载指示器
-- 响应式布局
-- 可折叠侧边栏
-- 面包屑导航
-
-## 架构设计
-
-### 统一响应架构
-
-插件采用后端驱动的统一响应架构，通过 `RouteHandler` 统一处理所有请求：
-
-1. **默认行为**: 所有响应默认交换到 `#main-content`
-2. **Dialog 模式**: 检测到 `dialog=true` 参数时，自动交换到 `#dialog-container`
-3. **错误响应**: 通过 `HtmxAdminContext.sendNotification()` 发送错误通知
-4. **响应头控制**: 所有响应都通过 `HX-Retarget` 响应头明确指定目标容器
-
-### 响应头控制
-
-所有响应都通过 `HX-Retarget` 响应头明确指定目标容器：
-
-- `#main-content`: 主内容区域（默认）
-- `#dialog-container`: 对话框容器（dialog 模式）
-- `#admin-layout`: 片段请求时的布局容器
-
-### 通知机制
-
-使用 `HtmxAdminContext` 的通知机制实现错误和成功消息：
-
-- **发送通知**: 通过 `context.sendNotification()` 或便捷方法（`sendError`, `sendSuccess` 等）
-- **通知显示**: 通知会在响应时通过 OOB 更新到错误容器
-- **多通知支持**: 支持多个通知同时显示
-
-### 模块系统
-
-插件支持四种模块类型，所有模块类型都继承自 `PageModule` 基类：
-
-1. **List**: 列表展示模块（`ListPageModule` 继承自 `PageModule`）
-2. **Detail**: 详情展示模块（`DetailPageModule` 继承自 `PageModule`）
-3. **Form**: 表单模块（`FormPageModule` 继承自 `PageModule`）
-4. **Custom**: 自定义页面模块（直接继承 `PageModule`）
-
-#### 架构优势
-
-- **统一基类**: 所有页面模块都继承自 `PageModule`，具有相同的处理过程和结构
-- **默认行为**: 每种类型提供默认的渲染逻辑，满足大部分场景
-- **灵活扩展**: 可以重写 `render()` 方法完全自定义渲染，即使使用 `list`、`detail`、`form` 类型
-- **代码复用**: 通用属性（`basePath`、`__moduleName`、`__moduleMetadata`、`getBreadcrumbs`）在基类中统一管理
+1. **围绕模型设计**：使用 `PageModel` 作为核心抽象，统一处理有数据模型和无数据模型的场景
+2. **权限与 Feature 绑定**：每个 Feature 声明自己的权限，支持灵活的权限控制
+3. **函数式数据操作**：移除数据源机制，直接使用函数处理数据操作
+4. **简洁统一**：单一类、统一模式，降低学习成本
 
 ## 快速开始
 
-### 1. 安装和导入
+### 安装
 
-```typescript
-import { 
-  Factory, 
-  HtmxAdminPlugin, 
-  ListPageModule, 
-  DetailPageModule, 
-  FormPageModule, 
-  PageModule, 
-  MemoryListDatasource,
-  Components  // 组件命名空间
-} from "imean-service-engine";
+```bash
+npm install imean-service-engine-htmx-plugin
 ```
 
-### 2. 创建插件实例
+### 基础使用
 
 ```typescript
+import { Factory } from "imean-service-engine";
+import { HtmxAdminPlugin, PageModel, CustomFeature } from "imean-service-engine-htmx-plugin";
+
+// 创建插件
 const adminPlugin = new HtmxAdminPlugin({
-  title: "用户管理系统",
+  title: "管理后台",
   prefix: "/admin",
-  logo: "/logo.png", // 可选
-  navigation: [  // 可选，自定义导航结构
-    {
-      label: "用户管理",
-      moduleName: "users",
-      icon: "👥"
-    }
-  ],
-  authProvider: {  // 可选，认证和权限提供者
-    cookieKey: "auth_token",  // Cookie 键名（默认 "auth_token"）
-    async tokenToUser(token: string, ctx: Context) {
-      // 从 token 获取用户信息
-      const user = await getUserByToken(token);
-      return {
-        name: user.name,
-        email: user.email,
-        avatar: user.avatar,
-        permissions: user.permissions,  // 用户权限列表
-      };
-    },
-    // checkPermission 可选，不提供则使用默认实现
-    async checkPermission(user, operation, context) {
-      // 自定义权限检查逻辑
-      return { allowed: true };
-    },
-  },
-});
-```
-
-### 3. 创建引擎
-
-```typescript
-const { Module, Microservice } = Factory.create(adminPlugin);
-```
-
-### 4. 定义数据模型
-
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  role: string;
-  createdAt: Date;
-}
-```
-
-### 5. 创建数据源
-
-```typescript
-const userDatasource = new MemoryListDatasource<User>([
-  { id: 1, name: "张三", email: "zhangsan@example.com", role: "管理员", createdAt: new Date() },
-  { id: 2, name: "李四", email: "lisi@example.com", role: "用户", createdAt: new Date() },
-]);
-```
-
-### 6. 定义模块
-
-```typescript
-@Module("users", {
-  type: "list",
-})
-class UserListModule extends ListPageModule<User> {
-  constructor() {
-    super(userDatasource);
-  }
-
-  // 自定义列渲染
-  renderColumn(field: string, value: any, item: User): any {
-    if (field === "role") {
-      const color = value === "管理员" 
-        ? "bg-blue-100 text-blue-800" 
-        : "bg-gray-100 text-gray-800";
-      return `<span class="px-2 py-1 rounded text-xs ${color}">${value}</span>`;
-    }
-    return value;
-  }
-
-  // 自定义操作按钮
-  getActions(item: User) {
-    return [
-      this.action.detail("查看"),
-      this.action.edit("编辑"),
-      this.action.delete("删除"),
-    ];
-  }
-}
-```
-
-### 7. 启动引擎
-
-```typescript
-const engine = new Microservice({
-  name: "admin-service",
-  version: "1.0.0",
 });
 
-const port = await engine.start(3000);
-console.log(`管理后台已启动: http://localhost:${port}/admin`);
-```
-
-## 模块类型
-
-### List 模块（列表页）
-
-用于列表展示，支持分页、筛选、排序和删除操作。继承自 `PageModule`。
-
-#### 基本用法
-
-```typescript
-@Module("products", {
-  type: "list",
-})
-class ProductListModule extends ListPageModule<Product> {
-  constructor() {
-    super(productDatasource);
-  }
-}
-```
-
-#### 自定义渲染
-
-可以重写 `render()` 方法来自定义列表页的渲染：
-
-```typescript
-@Module("products", {
-  type: "list",
-})
-class ProductListModule extends ListPageModule<Product> {
-  constructor() {
-    super(productDatasource);
-  }
-
-  // 完全自定义渲染
-  async render() {
-    const result = await this.getList(parseListParams(this.context.ctx));
-    return (
-      <div>
-        <h1>自定义产品列表</h1>
-        {/* 自定义布局和样式 */}
-      </div>
-    );
-  }
-}
-```
-
-#### 可选方法
-
-**`renderColumn(field: string, value: any, item: T): any`**
-- 自定义列的渲染方式
-- 返回 JSX 元素或 HTML 字符串
-
-**`getStats(params: ListParams): Promise<Array<StatCardProps>> | Array<StatCardProps>`**
-- 返回统计卡片数据
-- 用于在列表页顶部显示 KPI 统计
-
-**`getFilters(params: ListParams): Array<FilterField>`**
-- 返回筛选器配置
-- 用于在列表页显示筛选器
-
-**`getTableTitle(): string`**
-- 返回表格标题
-- 如果不定义，默认使用模块名
-
-**`getTableActions(params: ListParams, basePath: string): Array<ActionButtonProps>`**
-- 返回表格操作按钮配置
-- 如导出、清空、刷新等
-
-**`getDescription(): string`**
-- 返回页面描述文本
-- 显示在页面标题下方
-
-**`getActions(item: T): Array<ActionButtonProps>`**
-- 返回每行的操作按钮
-- 如果不定义，根据模块元数据智能生成
-
-#### 示例
-
-```typescript
-@Module("tasks", {
-  type: "list",
-})
-class TaskListModule extends ListPageModule<Task> {
-  constructor() {
-    super(taskDatasource);
-  }
-
-  // 自定义列渲染
-  renderColumn(field: string, value: any, item: Task): any {
-    if (field === "status") {
-      const statusMap = {
-        pending: { label: "待处理", color: "bg-yellow-100 text-yellow-800" },
-        "in-progress": { label: "进行中", color: "bg-blue-100 text-blue-800" },
-        completed: { label: "已完成", color: "bg-green-100 text-green-800" },
-      };
-      const status = statusMap[value as keyof typeof statusMap];
-      return (
-        <span className={`px-2 py-1 rounded text-xs ${status.color}`}>
-          {status.label}
-        </span>
-      );
-    }
-    if (field === "priority") {
-      const priorityMap = {
-        low: "🟢",
-        medium: "🟡",
-        high: "🔴",
-      };
-      return `${priorityMap[value as keyof typeof priorityMap]} ${value}`;
-    }
-    return value;
-  }
-
-  // 统计信息
-  async getStats(params: ListParams) {
-    const result = await this.getList({ ...params, pageSize: 1000 });
-    const total = result.total;
-    const completed = result.items.filter((item) => item.status === "completed").length;
-    const pending = result.items.filter((item) => item.status === "pending").length;
-
-    return [
-      {
-        title: "总任务数",
-        value: total,
-        iconColor: "blue" as const,
-      },
-      {
-        title: "已完成",
-        value: completed,
-        change: ((completed / total) * 100).toFixed(1),
-        changeLabel: "%",
-        iconColor: "green" as const,
-      },
-      {
-        title: "待处理",
-        value: pending,
-        iconColor: "yellow" as const,
-      },
-    ];
-  }
-
-  // 筛选器
-  getFilters(params: ListParams) {
-    return [
-      {
-        name: "status",
-        label: "状态",
-        options: [
-          { value: "pending", label: "待处理" },
-          { value: "in-progress", label: "进行中" },
-          { value: "completed", label: "已完成" },
-        ],
-        value: params.filters?.status,
-      },
-      {
-        name: "priority",
-        label: "优先级",
-        options: [
-          { value: "low", label: "低" },
-          { value: "medium", label: "中" },
-          { value: "high", label: "高" },
-        ],
-        value: params.filters?.priority,
-      },
-    ];
-  }
-}
-```
-
-### Detail 模块（详情页）
-
-用于详情展示，支持字段分组、自定义渲染和完全自定义。
-
-#### 基本用法
-
-```typescript
-@Module("users", {
-  type: "detail",
-})
-class UserDetailModule extends DetailPageModule<User> {
-  constructor() {
-    super(userDatasource);
-  }
-}
-```
-
-#### 可选方法
-
-**`getFieldLabel(field: string): string`**
-- 自定义字段的中文标签
-- 如果不定义，默认使用字段名
-
-**`renderField(field: string, value: any, item: T): any`**
-- 自定义字段的渲染方式
-- 返回 JSX 元素或 HTML 字符串
-
-**`getFieldGroups(item: T): Array<{ title: string; fields: string[] }> | null`**
-- 定义字段分组
-- 返回 `null` 或 `undefined` 表示不分组，平铺显示
-
-**`getVisibleFields(item: T): string[] | null`**
-- 控制字段的显示顺序和可见性
-- 返回 `null` 或 `undefined` 表示显示所有字段
-
-**`getDetailActions(item: T): Array<ActionButtonProps>`**
-- 返回详情页的操作按钮
-- 如果不定义，根据模块元数据智能生成
-
-#### 示例
-
-```typescript
-@Module("users", {
-  type: "detail",
-})
-class UserDetailModule extends DetailPageModule<User> {
+// 创建页面模型
+class LoginPageModel extends PageModel {
   constructor() {
-    super(userDatasource);
-  }
-
-  // 字段标签
-  getFieldLabel(field: string): string {
-    const labels: Record<string, string> = {
-      id: "ID",
-      name: "姓名",
-      email: "邮箱",
-      role: "角色",
-      createdAt: "创建时间",
-    };
-    return labels[field] || field;
-  }
-
-  // 字段渲染
-  renderField(field: string, value: any, item: User): any {
-    if (field === "role") {
-      const color = value === "管理员" 
-        ? "bg-blue-100 text-blue-800" 
-        : "bg-gray-100 text-gray-800";
-      return (
-        <span className={`px-2 py-1 rounded text-xs ${color}`}>
-          {value}
-        </span>
-      );
-    }
-    if (field === "createdAt") {
-      return new Date(value).toLocaleString("zh-CN");
-    }
-    return value;
-  }
-
-  // 字段分组
-  getFieldGroups(item: User) {
-    return [
-      {
-        title: "基本信息",
-        fields: ["id", "name", "email"],
-      },
-      {
-        title: "权限信息",
-        fields: ["role"],
-      },
-      {
-        title: "其他信息",
-        fields: ["createdAt"],
+    super("login", undefined, {
+      title: "登录",
+      useAdminLayout: false,
+    });
+
+    this.features.custom("login", new CustomFeature({
+      name: "login",
+      permission: null,
+      routes: [
+        { method: "get", path: "" },
+        { method: "post", path: "" },
+      ],
+      handler: async (context) => {
+        // 处理逻辑
       },
-    ];
+    }));
   }
 }
-```
-
-### Form 模块（表单页）
-
-用于表单（新建/编辑），支持表单字段定义、验证和表单回填。
-
-#### 基本用法
 
-```typescript
-@Module("articles", {
-  type: "form",
-})
-class ArticleFormModule extends FormPageModule<Article> {
-  constructor() {
-    super(articleDatasource);
-  }
+// 注册页面
+adminPlugin.registerPage(new LoginPageModel());
 
-  // 必须实现：定义表单字段（或提供 Zod Schema）
-  getFormFields(item: Article | null): Array<FormFieldType> {
-    return [
-      { name: "title", label: "标题", type: "text", required: true },
-      { name: "content", label: "内容", type: "textarea", required: true },
-      { name: "status", label: "状态", type: "select", required: true, options: [
-        { value: "draft", label: "草稿" },
-        { value: "published", label: "已发布" },
-      ]},
-    ];
-  }
-}
+// 创建引擎
+const { Microservice } = Factory.create(adminPlugin);
+const engine = new Microservice({ name: "admin-service" });
+await engine.start(3000);
 ```
 
-#### 使用 Zod Schema（推荐）
+## 使用模式
 
-如果提供了 Zod Schema，表单字段和验证会自动生成：
+### 有数据模型的页面
 
 ```typescript
+import { PageModel, type ModelSchema } from "imean-service-engine-htmx-plugin";
 import { z } from "zod";
 
+// 定义 Schema
 const ArticleSchema = z.object({
-  title: z.string().min(1, "标题不能为空").describe("标题"),
-  content: z.string().min(10, "内容至少10个字符").describe("内容"),
-  status: z.enum(["draft", "published"]).describe("状态"),
+  id: z.number().optional(),
+  title: z.string().min(1).describe("标题"),
+  content: z.string().min(10).describe("内容"),
 });
 
-@Module("articles", {
-  type: "form",
-})
-class ArticleFormModule extends FormPageModule<Article> {
-  constructor() {
-    super(articleDatasource, ArticleSchema);
-  }
+const articleModelSchema: ModelSchema<Article> = {
+  schema: ArticleSchema,
+};
 
-  // 不需要实现 getFormFields，会自动从 Schema 生成
-  // 不需要实现 validateFormData，会自动使用 Schema 验证
+// 数据操作函数
+async function getArticleList(params: ListParams): Promise<ListResult<Article>> {
+  // 从数据库或其他数据源获取列表
 }
-```
 
-#### 必需方法
-
-**`getFormFields(item: T | null): Array<FormFieldType>`**
-- 如果提供了 Zod Schema，则不需要实现（会自动生成）
-- 否则必须实现
-- 定义表单的字段配置
-- `item` 为 `null` 表示新建，否则表示编辑
-
-#### 可选方法
-
-**`getFieldLabel(field: string): string`**
-- 自定义字段的中文标签
-- 如果不定义，使用 `getFormFields` 中定义的 `label` 或 Schema 的 `description`
-
-**`validateFormData(data: Record<string, any>, item: T | null): string | null`**
-- 表单验证
-- 如果提供了 Zod Schema，会自动使用 Schema 验证
-- 返回 `null` 表示验证通过，返回字符串表示错误信息
-
-#### 表单回填
-
-表单验证失败时，用户提交的值会自动回填到表单中，避免用户重新填写：
-
-- 验证失败时，提交的数据会自动回填
-- 编辑模式下，验证失败时会合并原数据和提交数据
-- 表单使用 JSON 编码（`hx-encoding="json"`）提交数据
-
-#### 提交成功后的重定向
-
-表单提交成功后的重定向逻辑：
-
-- **创建操作**：优先跳转到详情页（如果存在），否则跳转到列表页
-- **更新操作**：跳转到详情页
-
-#### 表单字段类型
+async function getArticle(id: string | number): Promise<Article | null> {
+  // 获取单条数据
+}
 
-支持以下字段类型：
+async function createArticle(data: Partial<Article>): Promise<Article> {
+  // 创建数据
+}
 
-- `text`: 文本输入框
-- `email`: 邮箱输入框
-- `number`: 数字输入框
-- `textarea`: 文本域
-- `select`: 选择框
-- `date`: 日期选择器
-- `datetime-local`: 日期时间选择器
+async function updateArticle(id: string | number, data: Partial<Article>): Promise<Article | null> {
+  // 更新数据
+}
 
-#### 示例
+async function deleteArticle(id: string | number): Promise<boolean> {
+  // 删除数据
+}
 
-```typescript
-@Module("articles", {
-  type: "form",
-})
-class ArticleFormModule extends FormPageModule<Article> {
+// 定义 PageModel
+class ArticlePageModel extends PageModel<Article> {
   constructor() {
-    super(articleDatasource);
-  }
-
-  getFormFields(item: Article | null): Array<FormFieldType> {
-    return [
-      {
-        name: "title",
-        label: "标题",
-        type: "text",
-        required: true,
-        placeholder: "请输入文章标题",
+    super("articles", articleModelSchema, {
+      title: "文章管理",
+      description: "管理文章内容",
+    });
+
+    // 注册 CRUD Feature
+    this.features.crud({
+      permissionPrefix: "articles",
+      getList: getArticleList,
+      getItem: getArticle,
+      createItem: createArticle,
+      updateItem: updateArticle,
+      deleteItem: deleteArticle,
+      // 可选：弹窗大小配置（sm, md, lg, xl, full）
+      dialogSizes: {
+        detail: "xl",
+        edit: "xl",
+        create: "xl",
       },
-      {
-        name: "slug",
-        label: "URL 别名",
-        type: "text",
-        required: true,
-        placeholder: "article-title",
+      // 可选：遮罩关闭配置（编辑/创建时建议设为 false，防止误操作）
+      closeOnBackdropClick: {
+        edit: false,
+        create: false,
+        detail: true,
       },
-      {
-        name: "content",
-        label: "内容",
-        type: "textarea",
-        required: true,
-        placeholder: "请输入文章内容",
+      // 可选：动态标题和描述配置（使用实际数据的标题作为页面标题）
+      getTitles: {
+        detail: (item) => item.title,  // 详情页使用文章标题
+        edit: (item) => `编辑：${item.title}`,  // 编辑页使用 "编辑：{文章标题}"
       },
-      {
-        name: "category",
-        label: "分类",
-        type: "select",
-        required: true,
-        options: [
-          { value: "tech", label: "技术" },
-          { value: "life", label: "生活" },
-          { value: "news", label: "新闻" },
-        ],
+      getDescriptions: {
+        detail: (item) => item.excerpt || `作者：${item.author}`,  // 详情页使用文章摘要
       },
-      {
-        name: "publishedAt",
-        label: "发布时间",
-        type: "datetime-local",
-      },
-    ];
-  }
-
-  // 表单验证（如果提供了 Zod Schema，会自动使用 Schema 验证，此方法可选）
-  validateFormData(data: Record<string, any>, item: Article | null): string | null {
-    if (!data.title || data.title.trim().length === 0) {
-      return "标题不能为空";
-    }
-    if (data.slug && !/^[a-z0-9-]+$/.test(data.slug)) {
-      return "URL 别名只能包含小写字母、数字和连字符";
-    }
-    return null;
+    });
   }
 }
 ```
 
-#### 使用 Zod Schema 示例（推荐）
-
-使用 Zod Schema 可以自动生成表单字段和验证规则：
+### 无数据模型的页面
 
 ```typescript
-import { z } from "zod";
-
-const ArticleSchema = z.object({
-  title: z.string().min(1, "标题不能为空").describe("标题"),
-  slug: z.string().regex(/^[a-z0-9-]+$/, "URL 别名只能包含小写字母、数字和连字符").describe("URL 别名"),
-  content: z.string().min(10, "内容至少10个字符").describe("内容"),
-  category: z.enum(["tech", "life", "news"]).describe("分类"),
-  publishedAt: z.string().datetime().optional().describe("发布时间"),
-});
-
-@Module("articles", {
-  type: "form",
-})
-class ArticleFormModule extends FormPageModule<Article> {
+class LoginPageModel extends PageModel {
   constructor() {
-    // 传入 Schema，自动生成表单字段和验证
-    super(articleDatasource, ArticleSchema);
-  }
-
-  // 可选：自定义字段标签（覆盖 Schema 的 description）
-  getFieldLabels?(): Record<string, string> {
-    return {
-      publishedAt: "发布日期",
-    };
-  }
-
-  // 可选：自定义字段类型（覆盖自动推断的类型）
-  getFieldTypes?(): Record<string, "date" | "datetime-local"> {
-    return {
-      publishedAt: "datetime-local",
-    };
-  }
-
-  // 可选：排除某些字段（如 id、createdAt 等）
-  getExcludeFields?(): string[] {
-    return ["id", "createdAt", "updatedAt"];
-  }
-
-  // 不需要实现 getFormFields 和 validateFormData，会自动从 Schema 生成
-}
-```
-
-### Custom 模块（自定义页面）
-
-用于自定义页面渲染，如 dashboard、说明页等。
-
-#### 不使用管理后台布局
-
-如果页面需要完全自定义布局（不使用侧边栏和头部），可以设置 `useAdminLayout: false`：
-
-```typescript
-@Module("standalone-page", {
-  type: "custom",
-  useAdminLayout: false, // 不使用管理后台布局
-})
-class StandalonePageModule extends PageModule {
-  async render() {
-    return (
-      <div className="min-h-screen bg-gradient-to-br from-blue-500 to-purple-600">
-        <div className="container mx-auto px-4 py-16">
-          <h1 className="text-4xl font-bold text-white mb-8">独立页面</h1>
-          <p className="text-white text-lg">
-            这个页面不使用管理后台的侧边栏和头部布局
-          </p>
-          {/* 完全自定义的内容 */}
-        </div>
-      </div>
-    );
-  }
-}
-```
-
-**注意事项**：
-- 当 `useAdminLayout: false` 时，页面只使用 `BaseLayout`（包含 HTML 基础结构和脚本）
-- 不会显示侧边栏、头部、面包屑等管理后台元素
-- 适合开发登录页、独立功能页面、全屏应用等特殊场景
-- 片段请求时，内容会交换到 `#main-content` 容器（而不是 `#admin-layout`）
-
-## 使用相同模块名完成 CRUD
-
-插件支持使用相同的模块名、不同的页面类型来配合完成完整的 CRUD（创建、读取、更新、删除）操作。这是插件的核心设计理念之一。
-
-### 设计原理
-
-当多个模块使用相同的模块名时，插件会：
-
-1. **自动识别模块关系**：通过模块名将不同类型的模块关联在一起
-2. **共享基础路径**：所有模块共享相同的基础路径（`/{prefix}/{moduleName}`）
-3. **自动生成操作按钮**：根据存在的模块类型自动生成操作按钮（查看、编辑、删除等）
-4. **智能路由跳转**：表单提交后自动跳转到详情页或列表页
-
-### 完整示例
-
-以下是一个完整的任务管理 CRUD 示例，使用相同的模块名 `"tasks"` 但不同的类型：
-
-#### 1. 定义数据模型和数据源
-
-```typescript
-// models.ts
-export interface Task {
-  id: string;
-  title: string;
-  description: string;
-  status: "pending" | "in-progress" | "completed" | "cancelled";
-  priority: "low" | "medium" | "high" | "urgent";
-  assignee: string;
-  dueDate: string;
-  createdAt: string;
-  updatedAt: string;
-}
-
-// datasources.ts
-import { MemoryListDatasource } from "imean-service-engine";
-import type { Task } from "./models";
-
-const tasks: Task[] = [
-  {
-    id: "1",
-    title: "完成项目文档",
-    description: "编写项目使用文档",
-    status: "in-progress",
-    priority: "high",
-    assignee: "张三",
-    dueDate: "2024-01-15",
-    createdAt: "2024-01-01",
-    updatedAt: "2024-01-10",
-  },
-  // ... 更多数据
-];
-
-export const taskDatasource = new MemoryListDatasource<Task>(tasks);
-```
-
-#### 2. 创建列表页模块（List）
-
-```typescript
-import { ListPageModule, type HtmxAdminModuleOptions } from "imean-service-engine";
-import { Module } from "../config";
-import { taskDatasource } from "../datasources";
-import type { Task } from "../models";
-
-@Module("tasks", {
-  type: "list",
-  title: "任务管理",
-  description: "管理和跟踪所有任务",
-} as HtmxAdminModuleOptions)
-export class TaskListModule extends ListPageModule<Task> {
-  getDatasource() {
-    return taskDatasource;
-  }
-
-  // 自定义字段标签
-  getFieldLabel(field: string): string {
-    const labels: Record<string, string> = {
-      id: "任务ID",
-      title: "标题",
-      status: "状态",
-      priority: "优先级",
-      assignee: "负责人",
-      dueDate: "截止日期",
-    };
-    return labels[field] || field;
-  }
-
-  // 自定义列渲染
-  renderColumn(field: string, value: any, item: Task): any {
-    if (field === "status") {
-      const statusMap = {
-        pending: { label: "待处理", color: "bg-yellow-100 text-yellow-800" },
-        "in-progress": { label: "进行中", color: "bg-blue-100 text-blue-800" },
-        completed: { label: "已完成", color: "bg-green-100 text-green-800" },
-        cancelled: { label: "已取消", color: "bg-gray-100 text-gray-800" },
-      };
-      const status = statusMap[value as keyof typeof statusMap];
-      return (
-        <span className={`px-2 py-1 rounded text-xs ${status.color}`}>
-          {status.label}
-        </span>
-      );
-    }
-    return value;
-  }
-}
-```
-
-#### 3. 创建详情页模块（Detail）
-
-```typescript
-import { DetailPageModule, type HtmxAdminModuleOptions } from "imean-service-engine";
-import { Module } from "../config";
-import { taskDatasource } from "../datasources";
-import type { Task } from "../models";
-
-@Module("tasks", {
-  type: "detail",
-  title: "任务详情",
-  description: "查看任务详细信息",
-} as HtmxAdminModuleOptions)
-export class TaskDetailModule extends DetailPageModule<Task> {
-  getDatasource() {
-    return taskDatasource;
-  }
-
-  // 自定义字段标签
-  getFieldLabel(field: string): string {
-    const labels: Record<string, string> = {
-      id: "任务ID",
-      title: "标题",
-      description: "描述",
-      status: "状态",
-      priority: "优先级",
-      assignee: "负责人",
-      dueDate: "截止日期",
-      createdAt: "创建时间",
-      updatedAt: "更新时间",
-    };
-    return labels[field] || field;
-  }
-
-  // 自定义字段渲染
-  renderField(field: string, value: any, item: Task): any {
-    if (field === "status") {
-      const statusMap = {
-        pending: { label: "待处理", color: "bg-yellow-100 text-yellow-800" },
-        "in-progress": { label: "进行中", color: "bg-blue-100 text-blue-800" },
-        completed: { label: "已完成", color: "bg-green-100 text-green-800" },
-        cancelled: { label: "已取消", color: "bg-gray-100 text-gray-800" },
-      };
-      const status = statusMap[value as keyof typeof statusMap];
-      return (
-        <span className={`px-3 py-1 rounded text-sm font-medium ${status.color}`}>
-          {status.label}
-        </span>
-      );
-    }
-    return value;
+    super("login", undefined, {
+      title: "登录",
+      useAdminLayout: false,
+    });
+
+    this.features.custom("login", new CustomFeature({
+      name: "login",
+      permission: null,
+      routes: [
+        { method: "get", path: "" },
+        { method: "post", path: "" },
+      ],
+      handler: async (context) => {
+        // 处理逻辑
+      },
+    }));
   }
 }
 ```
 
-#### 4. 创建表单页模块（Form）
+### 只读场景
 
 ```typescript
-import { FormPageModule, type HtmxAdminModuleOptions } from "imean-service-engine";
-import { z } from "zod";
-import { Module } from "../config";
-import { taskDatasource } from "../datasources";
-import type { Task } from "../models";
-
-// 定义 Zod Schema（可选，用于自动生成表单字段和验证）
-const TaskSchema = z.object({
-  title: z.string().min(1, "标题不能为空").describe("任务标题"),
-  description: z.string().optional().describe("任务描述"),
-  status: z.enum(["pending", "in-progress", "completed", "cancelled"]).describe("任务状态"),
-  priority: z.enum(["low", "medium", "high", "urgent"]).describe("优先级"),
-  assignee: z.string().min(1, "负责人不能为空").describe("负责人"),
-  dueDate: z.string().describe("截止日期"),
-});
-
-@Module("tasks", {
-  type: "form",
-  title: "任务表单",
-  description: "创建或编辑任务",
-} as HtmxAdminModuleOptions)
-export class TaskFormModule extends FormPageModule<Task> {
-  // 在构造函数中传入 schema（可选）
+class ArticleReadonlyPageModel extends PageModel<Article> {
   constructor() {
-    super(TaskSchema);
-  }
-
-  getDatasource() {
-    return taskDatasource;
-  }
-
-  // 如果使用 Zod Schema，表单字段会自动生成，无需重写 getFormFields
-  // 如果需要自定义字段，可以重写 getFormFields 方法
-  getFormFields(item: Task | null): Array<{
-    name: string;
-    label: string;
-    type?: "text" | "email" | "number" | "textarea" | "select" | "date" | "datetime-local";
-    required?: boolean;
-    placeholder?: string;
-    options?: Array<{ value: string | number; label: string }>;
-  }> {
-    // 如果提供了 schema，会自动调用 generateFormFieldsFromSchema
-    // 这里可以添加自定义逻辑或直接返回父类实现
-    return super.getFormFields(item);
+    super("articles-readonly", articleModelSchema, {
+      title: "文章查看（只读）",
+    });
+
+    this.features.crud({
+      permissionPrefix: "articles",
+      getList: getArticleList,
+      getItem: getArticle,
+      createItem: createArticle,  // 必须提供，但不会注册
+      updateItem: updateArticle,
+      features: {
+        list: true,
+        detail: true,
+        create: false,  // 禁用创建
+        edit: false,    // 禁用编辑
+        delete: false,  // 禁用删除
+      },
+    });
   }
 }
 ```
 
-### 自动生成的路由
+## 权限系统
 
-当使用相同的模块名注册多个类型的模块后，插件会自动生成以下路由：
+### 权限格式
 
-```
-GET    /admin/tasks/list          → 列表页（TaskListModule）
-GET    /admin/tasks/detail/:id    → 详情页（TaskDetailModule）
-GET    /admin/tasks/new           → 新建表单（TaskFormModule）
-GET    /admin/tasks/edit/:id      → 编辑表单（TaskFormModule）
-POST   /admin/tasks               → 创建操作（TaskFormModule）
-PUT    /admin/tasks/:id           → 更新操作（TaskFormModule）
-DELETE /admin/tasks/:id           → 删除操作（TaskFormModule）
-```
+- 默认格式：`{modelName}.{featureName}`
+  - 例如：`articles.list`、`articles.create`、`articles.delete`
+- 自定义权限：可以在 Feature 配置中覆盖
 
-### 自动生成的操作按钮
+### 权限绑定
 
-插件会根据存在的模块类型自动生成操作按钮：
+- 每个 Feature 声明自己的 `permission`
+- 插件在路由注册时自动进行权限检查
+- 支持 `null` 表示开放访问
 
-#### 列表页操作按钮
+## API 参考
 
-在列表页中，如果存在详情页和表单页，会自动生成"查看"和"编辑"按钮：
+### PageModel
 
 ```typescript
-// 在 TaskListModule 中，无需手动定义，插件会自动生成：
-getActions(item: Task) {
-  // 自动生成：
-  // - 如果存在 detail 模块 → "查看" 按钮
-  // - 如果存在 form 模块 → "编辑" 按钮
-  // - 如果数据源支持删除 → "删除" 按钮
+class PageModel<T extends { id: string | number } = any> {
+  constructor(
+    modelName: string,
+    schema?: ModelSchema<T>,
+    metadata?: PageMetadata
+  );
+  
+  getMetadata(): PageMetadata;
+  hasModel(): boolean;
+  validate(data: unknown): ValidationResult;
+  getFormFields(): FormField[];
+  getListFields(): string[];
+  getDetailFields(): string[];
+  getFieldLabel(fieldName: string): string;
 }
 ```
 
-#### 详情页操作按钮
-
-在详情页中，如果存在列表页和表单页，会自动生成"返回列表"和"编辑"按钮：
+### FeatureRegistry
 
 ```typescript
-// 在 TaskDetailModule 中，无需手动定义，插件会自动生成：
-getDetailActions(item: Task) {
-  // 自动生成：
-  // - 如果存在 list 模块 → "返回列表" 按钮
-  // - 如果存在 form 模块 → "编辑" 按钮
-  // - 如果数据源支持删除 → "删除" 按钮
+class FeatureRegistry<T> {
+  crud(options: CRUDOptions): void;
+  list(feature: Feature<T>): void;
+  detail(feature: Feature<T>): void;
+  create(feature: Feature<T>): void;
+  edit(feature: Feature<T>): void;
+  delete(feature: Feature<T>): void;
+  custom(name: string, feature: Feature<T>): void;
 }
 ```
 
-### 智能跳转
-
-#### 表单提交后的跳转
-
-表单提交成功后，插件会根据存在的模块类型智能跳转。这个逻辑已经在 `FormPageModule` 的默认实现中处理，无需手动编写：
-
-```typescript
-// FormPageModule 内部已经实现了智能跳转逻辑：
-// - 创建成功后，如果存在详情页，优先跳转到详情页
-// - 否则跳转到列表页（如果存在）
-// - 更新成功后，跳转到详情页
-
-// 如果需要自定义跳转逻辑，可以重写 render 方法或使用 context.redirect()
-// 但通常不需要，因为默认行为已经足够智能
-```
-
-#### 面包屑自动生成
-
-面包屑会根据存在的模块类型自动生成：
-
-- **列表页**: `首页 => 任务管理`
-- **详情页**: `首页 => 任务管理 => 任务详情`
-- **表单页（新建）**: `首页 => 任务管理 => 新建任务`
-- **表单页（编辑）**: `首页 => 任务管理 => 编辑任务`
-
-### 模块元数据
-
-插件会自动为每个模块设置元数据，记录该模块名下的所有模块类型：
+### HtmxAdminPlugin
 
 ```typescript
-// 在 TaskListModule、TaskDetailModule、TaskFormModule 中都可以访问：
-this.context.moduleMetadata = {
-  title: "任务管理",
-  description: "管理和跟踪所有任务",
-  basePath: "/admin/tasks",
-  hasList: true,      // 因为存在 TaskListModule
-  hasDetail: true,    // 因为存在 TaskDetailModule
-  hasForm: true,      // 因为存在 TaskFormModule
-  hasCustom: false,   // 没有自定义页面
+class HtmxAdminPlugin {
+  registerPage<T>(page: PageModel<T>): this;
+  registerPages(...pages: PageModel<any>[]): this;
 }
 ```
 
-### 最佳实践
-
-1. **使用相同的模块名**：对于同一业务实体的不同页面，使用相同的模块名
-2. **共享数据源**：所有模块类型使用相同的数据源实例
-3. **统一字段标签**：在不同模块中使用相同的字段标签映射
-4. **利用自动生成**：让插件自动生成操作按钮和路由，减少重复代码
-5. **自定义渲染**：根据需要重写 `renderColumn`、`renderField` 等方法
-
-### 组合方式
-
-你可以根据需要组合不同的模块类型：
-
-- **完整 CRUD**: `list` + `detail` + `form`（推荐）
-- **只读列表**: `list` + `detail`（无表单）
-- **简单表单**: `form`（无列表和详情）
-- **自定义页面**: `custom`（完全自定义）
-
-### 注意事项
-
-1. **模块名必须一致**：所有相关模块必须使用完全相同的模块名（区分大小写）
-2. **数据源类型匹配**：List 模块使用 `ListDatasource`，Detail 和 Form 模块使用 `DetailDatasource` 或 `FormDatasource`
-3. **字段一致性**：不同模块中使用的字段名应该保持一致
-4. **路径生成**：使用 `this.paths` 生成路径，确保路径一致性
-
-#### 基本用法
-
-```typescript
-@Module("dashboard", {
-  type: "custom",
-})
-class DashboardModule extends PageModule {
-  async render() {
-    return (
-      <div>
-        <h1>仪表盘</h1>
-        <p>欢迎使用管理后台</p>
-        {/* 自定义内容 */}
-      </div>
-    );
-  }
-}
-```
-
-#### 必需方法
-
-**`render(): any | Promise<any>`**
-- 必须实现
-- 返回页面的 JSX 内容
-- 可以通过 `this.context.ctx` 访问 Hono Context
-- 可以通过 `this.context` 访问 HtmxAdminContext
-- 可以使用 `Components` 命名空间中的组件
-
-#### 示例
-
-```typescript
-import { Components } from "imean-service-engine";
-
-@Module("dashboard", {
-  type: "custom",
-})
-class DashboardModule extends PageModule {
-  async render() {
-    const { Card, Button, PageHeader, StatCard } = Components;
-
-    return (
-      <div>
-        <PageHeader title="仪表盘" description="系统概览和快速操作" />
-        
-        {/* 统计卡片 */}
-        <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-6">
-          <StatCard
-            title="总用户数"
-            value="1,234"
-            change={12.5}
-            changeLabel="%"
-            iconColor="blue"
-          />
-          <StatCard
-            title="今日订单"
-            value="56"
-            change={-5.2}
-            changeLabel="%"
-            iconColor="green"
-          />
-          <StatCard
-            title="待处理任务"
-            value="23"
-            iconColor="yellow"
-          />
-        </div>
-
-        {/* 快速操作 */}
-        <Card>
-          <h2 className="text-lg font-semibold mb-4">快速操作</h2>
-          <div className="space-y-2">
-            <Button variant="primary" href="/admin/users/new" hxGet="/admin/users/new">
-              新建用户
-            </Button>
-            <Button variant="secondary" href="/admin/products/list" hxGet="/admin/products/list">
-              查看产品
-            </Button>
-          </div>
-        </Card>
-      </div>
-    );
-  }
-}
-```
-
-## 数据源
-
-### 数据源接口
-
-插件定义了三种数据源接口：
-
-#### ListDatasource（列表数据源）
-
-```typescript
-interface ListDatasource<T = any> {
-  /** 获取列表数据 */
-  getList(params: ListParams): Promise<ListResult<T>>;
-  /** 删除数据（可选，如果不提供则列表页不显示删除操作） */
-  deleteItem?(id: string | number): Promise<boolean>;
-}
-```
-
-#### DetailDatasource（详情数据源）
-
-```typescript
-interface DetailDatasource<T = any> {
-  /** 获取单条数据 */
-  getItem(id: string | number): Promise<T | null>;
-  /** 删除数据（可选） */
-  deleteItem?(id: string | number): Promise<boolean>;
-}
-```
-
-#### FormDatasource（表单数据源）
-
-```typescript
-interface FormDatasource<T = any> {
-  /** 获取单条数据（编辑时使用） */
-  getItem?(id: string | number): Promise<T | null>;
-  /** 更新数据 */
-  updateItem?(id: string | number, data: Partial<T>): Promise<T | null>;
-  /** 创建数据 */
-  createItem?(data: Partial<T>): Promise<T>;
-}
-```
-
-### ListParams（列表查询参数）
-
-```typescript
-interface ListParams {
-  /** 页码（从1开始） */
-  page?: number;
-  /** 每页数量 */
-  pageSize?: number;
-  /** 排序字段 */
-  sortBy?: string;
-  /** 排序方向 */
-  sortOrder?: "asc" | "desc";
-  /** 筛选条件 */
-  filters?: Record<string, any>;
-}
-```
-
-### ListResult（列表查询结果）
-
-```typescript
-interface ListResult<T> {
-  /** 数据列表 */
-  items: T[];
-  /** 总数量 */
-  total: number;
-  /** 当前页码 */
-  page: number;
-  /** 每页数量 */
-  pageSize: number;
-  /** 总页数 */
-  totalPages: number;
-}
-```
-
-### MemoryListDatasource（内存数据源）
-
-插件提供了一个内存数据源实现，适合开发和测试：
-
-```typescript
-import { MemoryListDatasource } from "imean-service-engine";
-
-const userDatasource = new MemoryListDatasource<User>([
-  { id: 1, name: "张三", email: "zhangsan@example.com" },
-  { id: 2, name: "李四", email: "lisi@example.com" },
-]);
-```
-
-### 自定义数据源
-
-实现对应的数据源接口即可：
-
-```typescript
-class DatabaseListDatasource<T> implements ListDatasource<T> {
-  async getList(params: ListParams): Promise<ListResult<T>> {
-    // 从数据库查询数据
-    const offset = (params.page - 1) * params.pageSize;
-    const items = await db.query(
-      `SELECT * FROM users LIMIT ${params.pageSize} OFFSET ${offset}`
-    );
-    const total = await db.query(`SELECT COUNT(*) FROM users`);
-    
-    return {
-      items,
-      total,
-      page: params.page || 1,
-      pageSize: params.pageSize || 10,
-      totalPages: Math.ceil(total / params.pageSize),
-    };
-  }
-  
-  async deleteItem(id: string | number): Promise<boolean> {
-    // 从数据库删除数据
-    const result = await db.query(`DELETE FROM users WHERE id = ?`, [id]);
-    return result.affectedRows > 0;
-  }
-}
-```
-
-## 组件系统
-
-### 组件命名空间
-
-所有外部可用的组件都通过 `Components` 命名空间导出：
-
-```typescript
-import { Components } from "imean-service-engine";
-
-const { Detail, Form, Button, Card, PageHeader } = Components;
-```
-
-### 可用组件
-
-#### 页面组件
-
-- **`Detail`**: 详情页组件
-- **`Form`**: 表单组件
-- **`PageHeader`**: 页面头部组件
-- **`EmptyState`**: 空状态组件
-- **`Dialog`**: 对话框组件
-- **`ErrorAlert`**: 错误提示组件
-
-#### 布局组件
-
-- **`Card`**: 卡片组件
-- **`Button`**: 按钮组件
-- **`ActionButton`**: 操作按钮组件
-- **`Pagination`**: 分页组件
-- **`FilterCard`**: 筛选器组件
-
-#### 数据展示组件
-
-- **`StatCard`**: 统计卡片组件
-- **`ActivityCard`**: 活动卡片组件
-- **`SystemStatusCard`**: 系统状态卡片组件
-- **`Badge`**: 徽章组件
-
-#### 表单组件
-
-- **`FormField`**: 表单字段包装器（标签 + 输入框 + 错误提示）
-- **`Input`**: 输入框组件（支持 text, email, password, number 等类型）
-- **`Textarea`**: 文本域组件
-- **`Select`**: 选择框组件
-- **`DateInput`**: 日期输入组件（支持 date, datetime-local, time 等类型）
-
-### 组件使用示例
-
-#### Detail 组件
-
-```typescript
-import { Components } from "imean-service-engine";
-
-const { Detail } = Components;
-
-<Detail
-  item={user}
-  fieldLabels={{
-    name: "姓名",
-    email: "邮箱",
-    role: "角色",
-  }}
-  fieldRenderers={{
-    role: (value) => (
-      <span className="px-2 py-1 rounded bg-blue-100 text-blue-800">
-        {value}
-      </span>
-    ),
-  }}
-  fieldGroups={[
-    { title: "基本信息", fields: ["name", "email"] },
-    { title: "权限信息", fields: ["role"] },
-  ]}
-  actions={[
-    { label: "编辑", href: `/admin/users/${user.id}/edit` },
-    { label: "删除", href: `/admin/users/${user.id}`, method: "DELETE" },
-  ]}
-  title="用户详情"
-/>
-```
-
-#### Form 组件
-
-```typescript
-import { Components } from "imean-service-engine";
-
-const { Form } = Components;
-
-<Form
-  fields={[
-    { name: "name", label: "姓名", type: "text", required: true },
-    { name: "email", label: "邮箱", type: "email", required: true },
-  ]}
-  initialData={user}
-  submitUrl={`/admin/users/${user.id}`}
-  method="PUT"
-  cancelUrl="/admin/users/list"
-/>
-```
-
-#### Button 组件
-
-```typescript
-import { Components } from "imean-service-engine";
-
-const { Button } = Components;
-
-<Button
-  variant="primary"
-  size="md"
-  href="/admin/users/new"
-  hxGet="/admin/users/new"
->
-  新建用户
-</Button>
-```
-
-#### 表单组件
-
-```typescript
-import { Components } from "imean-service-engine";
-
-const { FormField, Input, Textarea, Select, DateInput } = Components;
-
-<FormField id="name" label="姓名" required>
-  <Input name="name" placeholder="请输入姓名" />
-</FormField>
-
-<FormField id="email" label="邮箱" required>
-  <Input type="email" name="email" placeholder="请输入邮箱" />
-</FormField>
-
-<FormField id="bio" label="简介">
-  <Textarea name="bio" rows={4} placeholder="请输入简介" />
-</FormField>
-
-<FormField id="status" label="状态" required>
-  <Select
-    name="status"
-    options={[
-      { value: "active", label: "活跃" },
-      { value: "inactive", label: "未激活" },
-    ]}
-    placeholder="请选择状态"
-  />
-</FormField>
-
-<FormField id="birthday" label="生日">
-  <DateInput type="date" name="birthday" />
-</FormField>
-```
-
-## 路由系统
-
-### 自动路由生成
-
-插件会根据模块类型自动生成 RESTful 路由：
-
-#### List 模块路由
-
-- `GET /{basePath}/list`: 列表页面
-- `DELETE /{basePath}/:id`: 删除操作（如果数据源支持）
-
-#### Detail 模块路由
-
-- `GET /{basePath}/detail/:id`: 详情页面
-- `DELETE /{basePath}/detail/:id`: 删除操作（如果数据源支持）
-
-#### Form 模块路由
-
-- `GET /{basePath}/new`: 新建表单页面
-- `POST /{basePath}`: 创建操作
-- `GET /{basePath}/edit/:id`: 编辑表单页面
-- `PUT /{basePath}/:id`: 更新操作
-- `DELETE /{basePath}/:id`: 删除操作（如果数据源支持）
-
-#### Custom 模块路由
-
-- `GET /{basePath}`: 自定义页面
-
-### Dialog 模式
-
-所有详情页和表单页都支持 dialog 模式，通过 URL 参数 `dialog=true` 启用：
-
-- `GET /{basePath}/detail/:id?dialog=true`: 在对话框中显示详情
-- `GET /{basePath}/new?dialog=true`: 在对话框中显示新建表单
-- `GET /{basePath}/edit/:id?dialog=true`: 在对话框中显示编辑表单
-
-Dialog 模式的特点：
-- 内容显示在模态对话框中
-- 不丢失列表页的状态
-- 适合快速查看和编辑
-- 关闭对话框后自动返回列表页
-
-### URL 状态管理
-
-列表页的筛选和分页状态会自动记录在 URL 中：
-
-- 筛选条件：`?status=pending&priority=high`
-- 分页：`?page=2&pageSize=20`
-- 排序：`?sortBy=createdAt&sortOrder=desc`
-
-刷新页面后状态会自动恢复。
-
-## 响应机制
-
-### 统一响应架构
-
-插件采用后端驱动的统一响应架构，通过 `RouteHandler` 统一处理所有请求：
-
-1. **RouteHandler**: 所有路由都通过 `RouteHandler.handle()` 处理
-2. **模块实例化**: 每次请求创建新的模块实例，通过 `__init(context)` 初始化
-3. **请求处理**: 调用模块的 `__handle()` 方法（默认调用 `render()`）
-4. **响应构建**: 根据请求类型（完整页面/片段）构建响应
-
-### 响应流程
-
-```
-请求 → RouteHandler.handle()
-  → 创建 HtmxAdminContext
-  → 创建模块实例
-  → 调用 moduleInstance.__init(context)
-  → 调用 moduleInstance.__handle()
-    → 默认调用 moduleInstance.render()
-  → 设置页面元数据（title, description, breadcrumbs）
-  → 构建响应（完整页面或片段）
-  → 返回响应
-```
-
-### 响应头控制
-
-所有响应都通过 `HX-Retarget` 响应头明确指定目标容器：
-
-- `#main-content`: 主内容区域（默认，完整页面）
-- `#dialog-container`: 对话框容器（dialog 模式）
-- `#admin-layout`: 片段请求时的布局容器
-
-### HX-Push-Url 控制
-
-URL 更新由后端通过 `HtmxAdminContext.redirect()` 控制：
-
-- 正常模式：调用 `context.redirect(url)` 更新 URL
-- Dialog 模式：不设置 redirectUrl，保持当前 URL
-
-## 错误处理
-
-### 统一错误处理
-
-插件提供了统一的错误处理机制，通过 `HtmxAdminContext` 发送通知：
-
-#### 发送错误通知
-
-```typescript
-// 在模块的 render 或 __handle 方法中
-if (!item) {
-  this.context.sendError("未找到数据", "数据不存在");
-  return <div>未找到数据</div>;
-}
-```
-
-#### 发送成功通知
-
-```typescript
-// 操作成功后
-this.context.sendSuccess("操作成功", "数据已成功保存");
-```
-
-#### 发送警告通知
-
-```typescript
-this.context.sendWarning("警告", "操作可能影响其他数据");
-```
-
-#### 发送信息通知
-
-```typescript
-this.context.sendInfo("提示", "操作成功完成");
-```
-
-### 错误响应机制
-
-错误通知会自动：
-
-1. 添加到 `context.notifications` 队列
-2. 在响应时通过 OOB 更新到错误容器
-3. 显示在页面右上角的全局错误通知区域
-4. 支持多个通知同时显示
-5. 每个通知可以单独关闭
-
-### RouteHandler 错误处理
-
-`RouteHandler` 会自动捕获模块处理过程中的异常：
-
-```typescript
-try {
-  adminContext.content = await moduleInstance.__handle();
-  // ...
-} catch (error) {
-  // 业务错误，自动处理
-  this.handleError(adminContext, error);
-}
-```
-
-## 高级功能
-
-### PathHelper（路径助手）
-
-`PathHelper` 用于简化路径生成，通过 `this.paths` 访问：
-
-```typescript
-// 在模块中使用
-getActions(item: User) {
-  return [
-    { label: "查看", href: this.paths.detail(item.id) },
-    { label: "编辑", href: this.paths.edit(item.id) },
-    { label: "删除", href: this.paths.delete(item.id), method: "DELETE" },
-    { label: "快速查看", href: this.paths.detail(item.id, true) }, // Dialog 模式
-  ];
-}
-```
-
-#### 可用方法
-
-- `detail(id: string | number, dialog?: boolean)`: 生成详情页路径
-- `edit(id: string | number, dialog?: boolean)`: 生成编辑页路径
-- `create(dialog?: boolean)`: 生成新建页路径
-- `delete(id: string | number)`: 生成删除操作路径
-- `list()`: 生成列表页路径
-- `base()`: 返回基础路径
-
-### 模块元数据
-
-插件会自动为每个模块设置元数据，通过 `this.context.moduleMetadata` 访问：
-
-```typescript
-interface ModuleTypeInfo {
-  title: string;           // 模块标题
-  description: string;     // 模块描述
-  basePath: string;       // 模块基础路径
-  hasList: boolean;        // 是否有列表页
-  hasDetail: boolean;      // 是否有详情页
-  hasForm: boolean;        // 是否有表单页
-  hasCustom: boolean;      // 是否有自定义页
-}
-```
-
-可以在模块方法中使用：
-
-```typescript
-getActions(item: T) {
-  const actions = [];
-  
-  if (this.context.moduleMetadata.hasDetail) {
-    actions.push({ label: "查看", href: this.paths.detail(item.id) });
-  }
-  
-  if (this.context.moduleMetadata.hasForm) {
-    actions.push({ label: "编辑", href: this.paths.edit(item.id) });
-  }
-  
-  return actions;
-}
-```
-
-### 自定义渲染
-
-#### 列表页自定义渲染
-
-```typescript
-renderColumn(field: string, value: any, item: T): any {
-  // 返回 JSX 或 HTML 字符串
-  if (field === "avatar") {
-    return <img src={value} className="w-10 h-10 rounded-full" />;
-  }
-  return value;
-}
-```
-
-#### 详情页自定义渲染
-
-```typescript
-renderField(field: string, value: any, item: T): any {
-  // 返回 JSX 或 HTML 字符串
-  if (field === "avatar") {
-    return <img src={value} className="w-20 h-20 rounded-full" />;
-  }
-  return value;
-}
-```
-
-#### 完全自定义详情页
-
-```typescript
-async render() {
-  const idParam = this.context.ctx.req.param("id");
-  const item = await this.getItem(idParam);
-  
-  if (!item) {
-    return <div>未找到数据</div>;
-  }
-  
-  return (
-    <div className="custom-detail-layout">
-      {/* 完全自定义的布局和样式 */}
-      <h1>{item.name}</h1>
-      {/* ... */}
-    </div>
-  );
-}
-```
-
-### 导航配置
-
-#### 集中式导航配置
-
-```typescript
-const adminPlugin = new HtmxAdminPlugin({
-  navigation: [
-    {
-      label: "用户管理",
-      moduleName: "users",
-      icon: "👥",
-    },
-    {
-      label: "产品管理",
-      moduleName: "products",
-      icon: "📦",
-    },
-    {
-      label: "系统设置",
-      icon: "⚙️",
-      children: [
-        {
-          label: "用户设置",
-          moduleName: "settings",
-          icon: "👤",
-        },
-        {
-          label: "系统配置",
-          href: "/admin/config",
-          icon: "🔧",
-        },
-      ],
-    },
-  ],
-});
-```
-
-#### 导航配置
-
-导航必须通过 `navigation` 配置手动定义。如果不提供 `navigation` 配置，导航将为空。
-
-**注意**: 导航配置是必需的，插件不会自动从模块生成导航。
-
-### 面包屑
-
-面包屑是页面模块的一部分，每个模块都可以定义自己的面包屑。
-
-#### 默认实现
-
-每个基类都提供了默认的 `getBreadcrumbs()` 方法：
-
-- **ListPageModule**: 首页 => 列表页
-- **DetailPageModule**: 首页 => 列表页（如果存在）=> 详情
-- **FormPageModule**: 首页 => 列表页（如果存在）=> 新建/编辑
-- **PageModule**: 首页 => 自定义页面
-
-#### 自定义面包屑
-
-可以在模块中重写 `getBreadcrumbs()` 方法来自定义面包屑：
-
-```typescript
-@Module("users", {
-  type: "detail",
-})
-class UserDetailModule extends DetailPageModule<User> {
-  constructor() {
-    super(userDatasource);
-  }
-
-  // 自定义面包屑
-  getBreadcrumbs(): BreadcrumbItem[] {
-    const item = await this.getItem(this.context.ctx.req.param("id"));
-    return [
-      { label: "首页", href: this.context.pluginOptions.prefix },
-      { label: "用户管理", href: this.paths.list() },
-      { label: item ? `${item.name} 的详情` : "用户详情" },
-    ];
-  }
-}
-```
-
-
-### 侧边栏折叠
-
-侧边栏支持折叠功能：
-
-- 点击切换按钮可以折叠/展开侧边栏
-- 折叠状态保存在 Cookie 中
-- 刷新页面后状态会恢复
-
-## API 参考
-
-### HtmxAdminPluginOptions
-
-```typescript
-interface HtmxAdminPluginOptions {
-  /** 站点标题 */
-  title?: string;
-  /** 站点 Logo URL（可选） */
-  logo?: string;
-  /** 管理后台路径前缀（默认 /admin） */
-  prefix?: string;
-  /** 首页路径（访问插件默认路径时重定向到此路径，如果未配置则使用第一个模块的路径） */
-  homePath?: string;
-  /** 导航配置（集中式声明导航结构，支持嵌套） */
-  navigation?: NavItemConfig[];
-  /** 认证提供者（用于鉴权和权限控制） */
-  authProvider?: AuthProvider;
-}
-```
-
-### AuthProvider
-
-```typescript
-interface AuthProvider {
-  /** Cookie 键名（默认 "auth_token"） */
-  cookieKey?: string;
-  /** 从 token 获取用户信息（必需） */
-  tokenToUser: (token: string, ctx: Context) => Promise<UserInfo | null>;
-  /** 自定义权限检查（可选，不提供则使用默认实现） */
-  checkPermission?: (
-    user: UserInfo | null,
-    operation: string,
-    context: HtmxAdminContext
-  ) => PermissionResult | Promise<PermissionResult>;
-}
-```
-
-### UserInfo
-
-```typescript
-interface UserInfo {
-  name?: string;
-  avatar?: string;
-  email?: string;
-  /** 用户权限列表（支持通配符和禁止权限） */
-  permissions?: string[];
-  [key: string]: any;
-}
-```
-
-### PermissionResult
-
-```typescript
-interface PermissionResult {
-  allowed: boolean;
-  message?: string;
-  operationId?: string;
-  redirectUrl?: string;
-}
-```
-
-### HtmxAdminModuleOptions
-
-```typescript
-interface HtmxAdminModuleOptions {
-  /** 模块类型 */
-  type: "list" | "detail" | "form" | "custom";
-  /** 模块标题（可选，默认使用模块名） */
-  title?: string;
-  /** 模块描述（可选） */
-  description?: string;
-  /** 是否使用管理后台布局（默认 true，设置为 false 时不使用侧边栏和头部，只使用 BaseLayout） */
-  useAdminLayout?: boolean;
-}
-```
-
-### PageModule（基类）
-
-```typescript
-abstract class PageModule {
-  /** HtmxAdmin 上下文对象 */
-  public context!: HtmxAdminContext;
-  
-  /** PathHelper 实例（用于生成路径） */
-  public paths!: PathHelper;
-  
-  /** 初始化模块实例（由 RouteHandler 调用） */
-  __init(context: HtmxAdminContext): void;
-  
-  /** 获取页面标题 */
-  getTitle(): string;
-  
-  /** 获取页面描述 */
-  getDescription(): string;
-  
-  /** 获取面包屑 */
-  getBreadcrumbs(): BreadcrumbItem[];
-  
-  /** 处理请求的统一入口（由 RouteHandler 调用） */
-  async __handle(): Promise<any>;
-  
-  /** 渲染页面内容（必须实现） */
-  abstract render(): any | Promise<any>;
-}
-```
-
-### ListPageModule
-
-```typescript
-abstract class ListPageModule<T extends { id: string | number } = { id: string | number }> extends PageModule {
-  /** ID 字段名（默认 "id"） */
-  protected readonly idField: string = "id";
-  
-  /** 获取数据源（抽象方法，必须实现） */
-  abstract getDatasource(): ListDatasource<T>;
-  
-  /** 获取列表数据 */
-  async getList(params: ListParams): Promise<ListResult<T>>;
-  
-  /** 删除数据（可选，如果数据源支持删除） */
-  async deleteItem(id: string | number): Promise<boolean>;
-  
-  /** 自定义列渲染（可选） */
-  renderColumn?(field: string, value: any, item: T): any;
-  
-  /** 获取统计信息（可选） */
-  getStats?(params: ListParams): Promise<Array<StatCardProps>> | Array<StatCardProps>;
-  
-  /** 获取筛选器（可选） */
-  getFilters?(params: ListParams): Array<FilterField>;
-  
-  /** 获取表格标题（可选） */
-  getTableTitle?(): string;
-  
-  /** 获取表格操作按钮（可选） */
-  getTableActions?(params: ListParams, basePath: string): Array<ActionButtonProps>;
-  
-  /** 获取操作按钮（可选） */
-  getActions?(item: T): Array<ActionButtonProps>;
-  
-  /** 渲染页面内容（可重写：自定义渲染） */
-  async render(): Promise<any>;
-}
-```
-
-### DetailPageModule
-
-```typescript
-abstract class DetailPageModule<T = any> extends PageModule {
-  /** ID 字段名（默认 "id"） */
-  protected readonly idField: string = "id";
-  
-  /** 获取数据源（抽象方法，必须实现） */
-  abstract getDatasource(): DetailDatasource<T>;
-  
-  /** 获取单条数据 */
-  async getItem(id: string | number): Promise<T | null>;
-  
-  /** 删除数据（可选，如果数据源支持删除） */
-  async deleteItem(id: string | number): Promise<boolean>;
-  
-  /** 获取字段标签（可选） */
-  getFieldLabel?(field: string): string;
-  
-  /** 渲染字段值（可选） */
-  renderField?(field: string, value: any, item: T): any;
-  
-  /** 获取字段分组（可选） */
-  getFieldGroups?(item: T): Array<{ title: string; fields: string[] }> | null;
-  
-  /** 获取可见字段（可选） */
-  getVisibleFields?(item: T): string[] | null;
-  
-  /** 获取详情页操作按钮（可选） */
-  getDetailActions?(item: T): Array<ActionButtonProps>;
-  
-  /** 渲染页面内容（可重写：自定义渲染） */
-  async render(): Promise<any>;
-}
-```
-
-### FormPageModule
-
-```typescript
-abstract class FormPageModule<T = any> extends PageModule {
-  /** 数据源 */
-  protected datasource: FormDatasource<T>;
-  
-  /** ID 字段名（默认 "id"） */
-  protected idField: string = "id";
-  
-  /** Zod Schema（可选，如果提供则自动生成表单字段和校验） */
-  protected schema?: z.ZodObject<any>;
-  
-  constructor(datasource: FormDatasource<T>, schema?: z.ZodObject<any>);
-  
-  /** 获取数据源（抽象方法，必须实现） */
-  abstract getDatasource(): FormDatasource<T>;
-  
-  /** 获取单条数据（编辑时使用） */
-  async getItem(id: string | number): Promise<T | null>;
-  
-  /** 获取表单字段定义（如果提供了 schema，则自动生成） */
-  getFormFields(item: T | null): Array<FormFieldType>;
-  
-  /** 验证表单数据（如果提供了 schema，则自动校验） */
-  validateFormData(data: Record<string, any>, item: T | null): string | null;
-  
-  /** 处理请求的统一入口（重写以处理不同 HTTP method） */
-  async __handle(): Promise<any>;
-  
-  /** 渲染页面内容（可重写：自定义渲染） */
-  async render(formData?: Record<string, any>): Promise<any>;
-}
-```
-
-### PageModule（自定义页面）
-
-```typescript
-abstract class PageModule {
-  /** HtmxAdmin 上下文对象 */
-  public context!: HtmxAdminContext;
-  
-  /** PathHelper 实例 */
-  public paths!: PathHelper;
-  
-  /** 渲染页面内容（Custom 类型必须实现） */
-  abstract render(): any | Promise<any>;
-}
-```
-
-### HtmxAdminContext（上下文对象）
-
-`HtmxAdminContext` 是插件核心的上下文对象，封装了请求处理过程中的所有状态和操作。每个模块实例都可以通过 `this.context` 访问。
-
-#### 属性
-
-```typescript
-class HtmxAdminContext {
-  /** 模块元数据 */
-  public readonly moduleMetadata: ModuleTypeInfo;
-  
-  /** 插件选项 */
-  public readonly pluginOptions: Required<HtmxAdminPluginOptions>;
-  
-  /** Hono Context（用于访问请求信息） */
-  public readonly ctx: Context;
-  
-  /** 之前的模块名（从 Referer 中提取） */
-  public readonly previousModuleName?: string;
-  
-  /** 是否是片段请求（HTMX 请求） */
-  public readonly isFragment: boolean;
-  
-  /** 是否是对话框请求 */
-  public readonly isDialog: boolean;
-  
-  /** 响应目标容器 */
-  public readonly target: string;
-  
-  /** 交换方式 */
-  public readonly swap: string;
-  
-  /** 用户信息 */
-  public readonly userInfo: UserInfo | null;
-  
-  /** 通知队列 */
-  public readonly notifications: Notification[];
-  
-  /** 页面标题（用于 HX-Title 和页面展示） */
-  public title: string;
-  
-  /** 页面描述（用于SEO和页面展示） */
-  public description: string;
-  
-  /** 面包屑项 */
-  public breadcrumbs: BreadcrumbItem[];
-  
-  /** 主要内容 */
-  public content: any;
-  
-  /** 需要重定向的 URL */
-  public redirectUrl?: string;
-  
-  /** 是否需要刷新页面（用于 HX-Refresh） */
-  public refresh: boolean;
-}
-```
-
-#### 方法
-
-##### 通知方法
-
-```typescript
-// 发送通知
-sendNotification(type: NotificationType, title: string, message: string): void;
-
-// 便捷方法
-sendError(title: string, message: string): void;
-sendWarning(title: string, message: string): void;
-sendInfo(title: string, message: string): void;
-sendSuccess(title: string, message: string): void;
-```
-
-**示例**：
-
-```typescript
-// 在模块中使用（通常在 validateFormData 或自定义逻辑中）
-validateFormData(data: Record<string, any>, item: T | null): string | null {
-  // 业务逻辑验证
-  if (!data.title || data.title.trim() === "") {
-    this.context.sendError("验证失败", "标题不能为空");
-    return "标题不能为空";
-  }
-  return null;
-}
-
-// 或者在重写的 render 方法中使用
-async render() {
-  // 自定义逻辑
-  if (someCondition) {
-    this.context.sendSuccess("操作成功", "数据已保存");
-  }
-}
-```
-
-##### URL 控制方法
-
-```typescript
-// 设置重定向 URL（用于 HX-Push-Url）
-redirect(url: string): void;
-
-// 设置是否需要刷新页面（用于 HX-Refresh）
-setRefresh(refresh: boolean = true): void;
-```
-
-**示例**：
-
-```typescript
-// 表单提交后的重定向逻辑已经在 FormPageModule 中自动处理
-// 如果需要自定义，可以在 validateFormData 或重写 render 方法中使用
-validateFormData(data: Record<string, any>, item: T | null): string | null {
-  // 验证逻辑
-  if (validationPassed) {
-    // 注意：重定向通常在 FormPageModule 的 handleCreate/handleUpdate 中处理
-    // 这里只是示例，实际使用中不需要手动调用
-    this.context.redirect(`${this.context.moduleMetadata.basePath}/list`);
-  }
-  return null;
-}
-```
-
-##### 模块元数据检查方法
-
-```typescript
-// 检查是否有列表页面
-hasList(): boolean;
-
-// 检查是否有详情页面
-hasDetail(): boolean;
-
-// 检查是否有表单页面
-hasForm(): boolean;
-
-// 检查是否有自定义页面
-hasCustom(): boolean;
-```
-
-**示例**：
-
-```typescript
-// 根据模块配置动态生成操作按钮
-getActions(item: T) {
-  const actions = [];
-  
-  if (this.context.hasDetail()) {
-    actions.push({ label: "查看", href: this.paths.detail(item.id) });
-  }
-  
-  if (this.context.hasForm()) {
-    actions.push({ label: "编辑", href: this.paths.edit(item.id) });
-  }
-  
-  return actions;
-}
-```
-
-#### 使用场景
-
-1. **访问请求信息**：通过 `this.context.ctx` 访问 Hono Context
-2. **发送通知**：使用 `sendNotification` 或便捷方法发送错误/成功消息
-3. **控制重定向**：使用 `redirect()` 设置 URL 更新
-4. **检查请求类型**：通过 `isFragment`、`isDialog` 判断请求类型
-5. **访问模块元数据**：通过 `moduleMetadata` 获取模块信息
-
-### PathHelper（路径助手）
-
-`PathHelper` 用于简化路径生成，避免手动拼接路径字符串。每个模块实例都可以通过 `this.paths` 访问。
-
-#### 方法
-
-```typescript
-class PathHelper {
-  /** 生成详情页路径 */
-  detail(id: string | number, dialog?: boolean): string;
-  
-  /** 生成编辑页路径 */
-  edit(id: string | number, dialog?: boolean): string;
-  
-  /** 生成新建页路径 */
-  create(dialog?: boolean): string;
-  
-  /** 生成删除操作路径 */
-  delete(id: string | number): string;
-  
-  /** 生成列表页路径 */
-  list(): string;
-  
-  /** 返回基础路径 */
-  base(): string;
-}
-```
-
-#### 使用示例
-
-```typescript
-// 在模块中使用
-class UserListModule extends ListPageModule<User> {
-  getActions(item: User) {
-    return [
-      // 普通模式
-      { label: "查看", href: this.paths.detail(item.id) },
-      { label: "编辑", href: this.paths.edit(item.id) },
-      { label: "删除", href: this.paths.delete(item.id), method: "DELETE" },
-      
-      // Dialog 模式
-      { label: "快速查看", href: this.paths.detail(item.id, true) },
-      { label: "快速编辑", href: this.paths.edit(item.id, true) },
-    ];
-  }
-  
-  getTableActions(params: ListParams, basePath: string) {
-    return [
-      { label: "新建", hxGet: this.paths.create() },
-      { label: "刷新", hxGet: this.paths.list() },
-    ];
-  }
-}
-```
-
-#### 路径生成规则
-
-- **详情页**: `{basePath}/detail/{id}` 或 `{basePath}/detail/{id}?dialog=true`
-- **编辑页**: `{basePath}/edit/{id}` 或 `{basePath}/edit/{id}?dialog=true`
-- **新建页**: `{basePath}/new` 或 `{basePath}/new?dialog=true`
-- **删除操作**: `{basePath}/detail/{id}`（使用 DELETE 方法）
-- **列表页**: `{basePath}/list`
-- **基础路径**: `{basePath}`
-
-#### 优势
-
-1. **类型安全**：避免手动拼接路径时的拼写错误
-2. **统一管理**：路径规则集中管理，修改时只需更新一处
-3. **Dialog 支持**：自动处理 dialog 模式的参数
-4. **代码简洁**：减少重复的路径拼接代码
-
-## 最佳实践
-
-### 1. 模块命名
-
-- 使用复数形式：`users`, `products`, `tasks`
-- 使用小写字母和连字符：`user-profiles`, `product-categories`
-- 避免使用保留字：`admin`, `api`, `static`
-
-### 2. 数据源设计
-
-- 将数据源封装为独立的类或函数
-- 实现完整的数据源接口
-- 处理错误情况（如数据不存在）
-
-### 3. 字段渲染
-
-- 使用 `renderColumn` 和 `renderField` 自定义字段显示
-- 返回 JSX 元素以获得更好的类型支持
-- 保持渲染逻辑简洁
-
-### 4. 表单验证
-
-- **推荐使用 Zod Schema**：自动生成表单字段和验证规则，减少重复代码
-- 在 `validateFormData` 中进行业务逻辑验证（如果使用 Schema，会自动验证）
-- 返回清晰的错误信息
-- 前端也会进行基本的 HTML5 验证
-- **表单回填**：验证失败时，用户提交的值会自动回填到表单中，避免用户重新填写
-- **JSON 编码**：表单使用 `hx-encoding="json"` 提交数据，后端自动解析
-
-### 5. 错误处理
-
-- 使用 `context.sendNotification()` 或便捷方法发送通知
-- 提供有意义的错误消息
-- 区分用户错误和系统错误
-
-### 6. 性能优化
-
-- 使用分页避免加载过多数据
-- 在数据源层面实现筛选和排序
-- 使用缓存减少数据库查询
-
-### 7. 安全性
-
-- **认证和权限**: 通过 `AuthProvider` 实现认证和权限控制
-- **权限声明**: 模块通过 `getRequiredPermission()` 声明所需权限
-- **权限匹配**: 支持通配符和禁止权限，提供灵活的权限管理
-- **输入验证**: 在数据源层面验证输入
-- **SQL 注入防护**: 使用参数化查询防止 SQL 注入
-
-## 示例项目
-
-插件提供了一个完整的示例项目，展示所有功能特性：
-
-### 运行示例
-
-```bash
-# 启动示例项目
-npm run dev
-
-# 或直接运行
-node dist/examples/index.js
-```
-
-访问 `http://localhost:3000/admin` 即可查看示例。
-
-### 示例模块
-
-- **Dashboard**: 自定义页面示例
-- **TaskManagement**: CRUD 完整示例
-- **ProductCatalog**: 列表页示例
-- **UserProfile**: 详情页示例
-- **ArticleManagement**: 表单页示例
-
-### 示例数据
-
-- 45 条任务数据
-- 40+ 条产品数据
-- 32 条用户数据
-- 30 条文章数据
-
-更多示例请参考 `examples/` 目录。
-
-## 常见问题
-
-### Q: 如何自定义页面布局？
-
-A: 可以通过重写 `render` 方法完全自定义详情页，或使用 `Custom` 类型模块创建自定义页面。
-
-### Q: 如何添加自定义路由？
-
-A: 可以在模块的 `render` 方法中处理不同的路径，或使用 Hono 的路由系统添加额外的路由。
-
-### Q: 如何实现权限控制？
-
-A: 可以在数据源层面实现权限检查，或在路由处理函数中添加中间件。
-
-### Q: 如何自定义样式？
-
-A: 所有组件都使用 Tailwind CSS，可以通过添加自定义类名或修改 Tailwind 配置来自定义样式。
-
-### Q: 如何集成数据库？
-
-A: 实现对应的数据源接口，在接口方法中调用数据库查询。
-
-### Q: Dialog 模式如何工作？
-
-A: 通过 URL 参数 `dialog=true` 启用，内容会显示在模态对话框中，响应会自动交换到 `#dialog-container`。
-
-### Q: 错误消息如何显示？
-
-A: 通过 `context.sendNotification()` 或便捷方法发送通知，通知会显示在页面右上角的全局错误通知区域，支持多个通知同时显示。
-
-### Q: 表单验证失败后如何回填数据？
-
-A: 表单验证失败时，用户提交的值会自动回填到表单中。表单使用 JSON 编码（`hx-encoding="json"`）提交数据，后端会自动解析并回填。
-
-### Q: 表单提交成功后如何控制重定向？
-
-A: 使用 `context.redirect(url)` 方法设置重定向 URL。创建操作优先跳转到详情页（如果存在），否则跳转到列表页；更新操作跳转到详情页。
-
-### Q: 如何在模块中访问 Hono Context？
-
-A: 通过 `this.context.ctx` 访问 Hono Context，通过 `this.context` 访问 HtmxAdminContext。
-
-### Q: 如何生成操作按钮的路径？
-
-A: 使用 `this.paths`（PathHelper 实例）生成路径，例如 `this.paths.detail(id)`、`this.paths.edit(id)` 等。
-
-## 更新日志
-
-### v2.0.0
-
-- ✨ 统一响应架构：后端驱动的响应机制
-- ✨ Dialog 模式：支持弹窗查看和编辑
-- ✨ 错误处理：统一的错误处理机制
-- ✨ URL 状态管理：筛选和分页状态记录在 URL
-- ✨ 动画效果：对话框和错误通知的流畅动画
-- ✨ 表单回填：验证失败时自动回填用户提交的值
-- ✨ Zod Schema 支持：自动生成表单字段和验证规则
-- ✨ 表单 JSON 编码：使用 `hx-encoding="json"` 提交数据
-- ✨ 智能重定向：创建操作优先跳转到详情页
-- 🔧 代码优化：移除重复代码，统一响应处理
-- 🔧 API 更新：`setPushUrl()` 改为 `redirect()`
+## 迁移指南
 
-### v1.0.0
+从 v1 迁移到 v2：
 
-- 🎉 初始版本发布
-- ✨ 支持 List、Detail、Form、Custom 四种模块类型
-- ✨ 自动路由生成
-- ✨ 组件系统
-- ✨ 数据源抽象
+1. **移除数据源**：将数据源方法改为函数
+2. **移除装饰器**：使用构造函数注册
+3. **合并元数据**：将 `getTitle`、`getDescription` 等合并为构造函数参数
+4. **权限迁移**：将页面级权限改为 Feature 级权限
 
-## 许可证
+## 设计文档
 
-MIT License
+详细设计文档请参考 [DESIGN.md](./DESIGN.md)。
 
-## 贡献
+## 旧版本
 
-欢迎提交 Issue 和 Pull Request！
+旧版本代码已移至 `src-old` 目录，文档移至 `README-old.md`。