imean-service-engine-htmx-plugin 1.0.0

package/README.md

@@ -0,0 +1,2373 @@
+# HtmxAdminPlugin 完整文档
+
+基于 HTMX + Tailwind CSS + Hyperscript + JSX 的管理后台插件，采用后端驱动的统一响应架构，支持快速构建现代化的管理后台系统。
+
+## 目录
+
+- [概述](#概述)
+- [核心特性](#核心特性)
+- [架构设计](#架构设计)
+- [快速开始](#快速开始)
+- [模块类型](#模块类型)
+- [使用相同模块名完成 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. 安装和导入
+
+```typescript
+import { 
+  Factory, 
+  HtmxAdminPlugin, 
+  ListPageModule, 
+  DetailPageModule, 
+  FormPageModule, 
+  PageModule, 
+  MemoryListDatasource,
+  Components  // 组件命名空间
+} from "imean-service-engine";
+```
+
+### 2. 创建插件实例
+
+```typescript
+const adminPlugin = new HtmxAdminPlugin({
+  title: "用户管理系统",
+  prefix: "/admin",
+  logo: "/logo.png", // 可选
+  navigation: [  // 可选，自定义导航结构
+    {
+      label: "用户管理",
+      moduleName: "users",
+      icon: "👥"
+    }
+  ],
+  getUserInfo: async (ctx) => {  // 可选，获取用户信息
+    return {
+      name: "管理员",
+      email: "admin@example.com"
+    };
+  }
+});
+```
+
+### 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> {
+  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"],
+      },
+    ];
+  }
+}
+```
+
+### Form 模块（表单页）
+
+用于表单（新建/编辑），支持表单字段定义、验证和表单回填。
+
+#### 基本用法
+
+```typescript
+@Module("articles", {
+  type: "form",
+})
+class ArticleFormModule extends FormPageModule<Article> {
+  constructor() {
+    super(articleDatasource);
+  }
+
+  // 必须实现：定义表单字段（或提供 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: "已发布" },
+      ]},
+    ];
+  }
+}
+```
+
+#### 使用 Zod Schema（推荐）
+
+如果提供了 Zod Schema，表单字段和验证会自动生成：
+
+```typescript
+import { z } from "zod";
+
+const ArticleSchema = z.object({
+  title: z.string().min(1, "标题不能为空").describe("标题"),
+  content: z.string().min(10, "内容至少10个字符").describe("内容"),
+  status: z.enum(["draft", "published"]).describe("状态"),
+});
+
+@Module("articles", {
+  type: "form",
+})
+class ArticleFormModule extends FormPageModule<Article> {
+  constructor() {
+    super(articleDatasource, ArticleSchema);
+  }
+
+  // 不需要实现 getFormFields，会自动从 Schema 生成
+  // 不需要实现 validateFormData，会自动使用 Schema 验证
+}
+```
+
+#### 必需方法
+
+**`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"`）提交数据
+
+#### 提交成功后的重定向
+
+表单提交成功后的重定向逻辑：
+
+- **创建操作**：优先跳转到详情页（如果存在），否则跳转到列表页
+- **更新操作**：跳转到详情页
+
+#### 表单字段类型
+
+支持以下字段类型：
+
+- `text`: 文本输入框
+- `email`: 邮箱输入框
+- `number`: 数字输入框
+- `textarea`: 文本域
+- `select`: 选择框
+- `date`: 日期选择器
+- `datetime-local`: 日期时间选择器
+
+#### 示例
+
+```typescript
+@Module("articles", {
+  type: "form",
+})
+class ArticleFormModule extends FormPageModule<Article> {
+  constructor() {
+    super(articleDatasource);
+  }
+
+  getFormFields(item: Article | null): Array<FormFieldType> {
+    return [
+      {
+        name: "title",
+        label: "标题",
+        type: "text",
+        required: true,
+        placeholder: "请输入文章标题",
+      },
+      {
+        name: "slug",
+        label: "URL 别名",
+        type: "text",
+        required: true,
+        placeholder: "article-title",
+      },
+      {
+        name: "content",
+        label: "内容",
+        type: "textarea",
+        required: true,
+        placeholder: "请输入文章内容",
+      },
+      {
+        name: "category",
+        label: "分类",
+        type: "select",
+        required: true,
+        options: [
+          { value: "tech", label: "技术" },
+          { value: "life", label: "生活" },
+          { value: "news", label: "新闻" },
+        ],
+      },
+      {
+        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> {
+  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;
+  }
+}
+```
+
+#### 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（可选）
+  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);
+  }
+}
+```
+
+### 自动生成的路由
+
+当使用相同的模块名注册多个类型的模块后，插件会自动生成以下路由：
+
+```
+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）
+```
+
+### 自动生成的操作按钮
+
+插件会根据存在的模块类型自动生成操作按钮：
+
+#### 列表页操作按钮
+
+在列表页中，如果存在详情页和表单页，会自动生成"查看"和"编辑"按钮：
+
+```typescript
+// 在 TaskListModule 中，无需手动定义，插件会自动生成：
+getActions(item: Task) {
+  // 自动生成：
+  // - 如果存在 detail 模块 → "查看" 按钮
+  // - 如果存在 form 模块 → "编辑" 按钮
+  // - 如果数据源支持删除 → "删除" 按钮
+}
+```
+
+#### 详情页操作按钮
+
+在详情页中，如果存在列表页和表单页，会自动生成"返回列表"和"编辑"按钮：
+
+```typescript
+// 在 TaskDetailModule 中，无需手动定义，插件会自动生成：
+getDetailActions(item: Task) {
+  // 自动生成：
+  // - 如果存在 list 模块 → "返回列表" 按钮
+  // - 如果存在 form 模块 → "编辑" 按钮
+  // - 如果数据源支持删除 → "删除" 按钮
+}
+```
+
+### 智能跳转
+
+#### 表单提交后的跳转
+
+表单提交成功后，插件会根据存在的模块类型智能跳转。这个逻辑已经在 `FormPageModule` 的默认实现中处理，无需手动编写：
+
+```typescript
+// FormPageModule 内部已经实现了智能跳转逻辑：
+// - 创建成功后，如果存在详情页，优先跳转到详情页
+// - 否则跳转到列表页（如果存在）
+// - 更新成功后，跳转到详情页
+
+// 如果需要自定义跳转逻辑，可以重写 render 方法或使用 context.redirect()
+// 但通常不需要，因为默认行为已经足够智能
+```
+
+#### 面包屑自动生成
+
+面包屑会根据存在的模块类型自动生成：
+
+- **列表页**: `首页 => 任务管理`
+- **详情页**: `首页 => 任务管理 => 任务详情`
+- **表单页（新建）**: `首页 => 任务管理 => 新建任务`
+- **表单页（编辑）**: `首页 => 任务管理 => 编辑任务`
+
+### 模块元数据
+
+插件会自动为每个模块设置元数据，记录该模块名下的所有模块类型：
+
+```typescript
+// 在 TaskListModule、TaskDetailModule、TaskFormModule 中都可以访问：
+this.context.moduleMetadata = {
+  title: "任务管理",
+  description: "管理和跟踪所有任务",
+  basePath: "/admin/tasks",
+  hasList: true,      // 因为存在 TaskListModule
+  hasDetail: true,    // 因为存在 TaskDetailModule
+  hasForm: true,      // 因为存在 TaskFormModule
+  hasCustom: false,   // 没有自定义页面
+}
+```
+
+### 最佳实践
+
+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} 的详情` : "用户详情" },
+    ];
+  }
+}
+```
+
+### 用户信息
+
+#### 获取用户信息
+
+```typescript
+const adminPlugin = new HtmxAdminPlugin({
+  getUserInfo: async (ctx: Context) => {
+    // 从 session 或 token 中获取用户信息
+    const userId = ctx.req.header("X-User-Id");
+    const user = await getUserById(userId);
+    
+    return {
+      name: user.name,
+      email: user.email,
+      avatar: user.avatar,
+    };
+  },
+});
+```
+
+用户信息会显示在页面右上角。
+
+### 侧边栏折叠
+
+侧边栏支持折叠功能：
+
+- 点击切换按钮可以折叠/展开侧边栏
+- 折叠状态保存在 Cookie 中
+- 刷新页面后状态会恢复
+
+## API 参考
+
+### HtmxAdminPluginOptions
+
+```typescript
+interface HtmxAdminPluginOptions {
+  /** 站点标题 */
+  title?: string;
+  /** 站点 Logo URL（可选） */
+  logo?: string;
+  /** 管理后台路径前缀（默认 /admin） */
+  prefix?: string;
+  /** 首页路径（访问插件默认路径时重定向到此路径，如果未配置则使用第一个模块的路径） */
+  homePath?: string;
+  /** 导航配置（集中式声明导航结构，支持嵌套） */
+  navigation?: NavItemConfig[];
+  /** 获取用户信息的函数（用于显示用户信息） */
+  getUserInfo?: (ctx: Context) => UserInfo | null | Promise<UserInfo | null>;
+}
+```
+
+### 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. 安全性
+
+- 在数据源层面实现权限检查
+- 验证用户输入
+- 使用参数化查询防止 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
+
+- 🎉 初始版本发布
+- ✨ 支持 List、Detail、Form、Custom 四种模块类型
+- ✨ 自动路由生成
+- ✨ 组件系统
+- ✨ 数据源抽象
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！