imean-service-engine-htmx-plugin 2.9.5 → 2.10.1

package/dist/index.js

@@ -2036,6 +2036,13 @@ function FilterForm(props) {
     }
     return String(value);
   }
+  function getCheckboxValue(field) {
+    const value = currentFilters[field.name];
+    if (value === "true" || value === true) {
+      return true;
+    }
+    return false;
+  }
   if (fields.length === 0) {
     return null;
   }
@@ -2048,7 +2055,29 @@ function FilterForm(props) {
       className: "space-y-4",
       "data-testid": "filter-form",
       children: [
-        fields.length > 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4", children: fields.map((field) => /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "space-y-2", "data-testid": `filter-field-${field.name}`, children: [
+        fields.length > 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4", children: fields.map((field) => /* @__PURE__ */ jsxRuntime.jsx("div", { className: "space-y-2", "data-testid": `filter-field-${field.name}`, children: field.type === "checkbox" ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-2 pt-7", children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "input",
+            {
+              id: `filter-${field.name}`,
+              name: field.name,
+              type: "checkbox",
+              value: "true",
+              checked: getCheckboxValue(field),
+              className: "w-4 h-4 text-blue-600 bg-white border-gray-300 rounded focus:ring-blue-500 focus:ring-2",
+              "data-testid": `filter-checkbox-${field.name}`
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "label",
+            {
+              htmlFor: `filter-${field.name}`,
+              className: "text-sm font-semibold text-gray-700 cursor-pointer",
+              "data-testid": `filter-label-${field.name}`,
+              children: field.label
+            }
+          )
+        ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
           /* @__PURE__ */ jsxRuntime.jsx(
             "label",
             {
@@ -2092,6 +2121,18 @@ function FilterForm(props) {
               type: "number",
               value: getFieldValue(field),
               placeholder: field.placeholder || `\u8BF7\u8F93\u5165${field.label}`,
+              step: field.step,
+              className: "w-full px-4 py-2.5 border border-gray-300 rounded-lg shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all duration-200 bg-white",
+              "data-testid": `filter-input-${field.name}`
+            }
+          ) : field.type === "email" ? /* @__PURE__ */ jsxRuntime.jsx(
+            "input",
+            {
+              id: `filter-${field.name}`,
+              name: field.name,
+              type: "email",
+              value: getFieldValue(field),
+              placeholder: field.placeholder || `\u8BF7\u8F93\u5165${field.label}`,
               className: "w-full px-4 py-2.5 border border-gray-300 rounded-lg shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all duration-200 bg-white",
               "data-testid": `filter-input-${field.name}`
             }
@@ -2107,7 +2148,7 @@ function FilterForm(props) {
               "data-testid": `filter-input-${field.name}`
             }
           )
-        ] }, field.name)) }),
+        ] }) }, field.name)) }),
         /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-3 pt-2", children: [
           /* @__PURE__ */ jsxRuntime.jsx(
             "button",
@@ -2536,10 +2577,20 @@ function ListPage(props) {
     ...params.filters
     // 包含所有筛选条件
   };
+  const refreshUrl = (() => {
+    const queryParams = new URLSearchParams();
+    Object.entries(currentParams).forEach(([key, value]) => {
+      if (value !== void 0 && value !== null && value !== "") {
+        queryParams.append(key, String(value));
+      }
+    });
+    const queryString = queryParams.toString();
+    return queryString ? `${listPath}?${queryString}` : listPath;
+  })();
   const tableActions = [
     {
       label: "\u5237\u65B0",
-      hxGet: listPath,
+      hxGet: refreshUrl,
       variant: "primary"
     }
   ];

package/dist/index.mjs

@@ -2034,6 +2034,13 @@ function FilterForm(props) {
     }
     return String(value);
   }
+  function getCheckboxValue(field) {
+    const value = currentFilters[field.name];
+    if (value === "true" || value === true) {
+      return true;
+    }
+    return false;
+  }
   if (fields.length === 0) {
     return null;
   }
@@ -2046,7 +2053,29 @@ function FilterForm(props) {
       className: "space-y-4",
       "data-testid": "filter-form",
       children: [
-        fields.length > 0 && /* @__PURE__ */ jsx("div", { className: "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4", children: fields.map((field) => /* @__PURE__ */ jsxs("div", { className: "space-y-2", "data-testid": `filter-field-${field.name}`, children: [
+        fields.length > 0 && /* @__PURE__ */ jsx("div", { className: "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4", children: fields.map((field) => /* @__PURE__ */ jsx("div", { className: "space-y-2", "data-testid": `filter-field-${field.name}`, children: field.type === "checkbox" ? /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 pt-7", children: [
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              id: `filter-${field.name}`,
+              name: field.name,
+              type: "checkbox",
+              value: "true",
+              checked: getCheckboxValue(field),
+              className: "w-4 h-4 text-blue-600 bg-white border-gray-300 rounded focus:ring-blue-500 focus:ring-2",
+              "data-testid": `filter-checkbox-${field.name}`
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "label",
+            {
+              htmlFor: `filter-${field.name}`,
+              className: "text-sm font-semibold text-gray-700 cursor-pointer",
+              "data-testid": `filter-label-${field.name}`,
+              children: field.label
+            }
+          )
+        ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
           /* @__PURE__ */ jsx(
             "label",
             {
@@ -2090,6 +2119,18 @@ function FilterForm(props) {
               type: "number",
               value: getFieldValue(field),
               placeholder: field.placeholder || `\u8BF7\u8F93\u5165${field.label}`,
+              step: field.step,
+              className: "w-full px-4 py-2.5 border border-gray-300 rounded-lg shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all duration-200 bg-white",
+              "data-testid": `filter-input-${field.name}`
+            }
+          ) : field.type === "email" ? /* @__PURE__ */ jsx(
+            "input",
+            {
+              id: `filter-${field.name}`,
+              name: field.name,
+              type: "email",
+              value: getFieldValue(field),
+              placeholder: field.placeholder || `\u8BF7\u8F93\u5165${field.label}`,
               className: "w-full px-4 py-2.5 border border-gray-300 rounded-lg shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-all duration-200 bg-white",
               "data-testid": `filter-input-${field.name}`
             }
@@ -2105,7 +2146,7 @@ function FilterForm(props) {
               "data-testid": `filter-input-${field.name}`
             }
           )
-        ] }, field.name)) }),
+        ] }) }, field.name)) }),
         /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-3 pt-2", children: [
           /* @__PURE__ */ jsx(
             "button",
@@ -2534,10 +2575,20 @@ function ListPage(props) {
     ...params.filters
     // 包含所有筛选条件
   };
+  const refreshUrl = (() => {
+    const queryParams = new URLSearchParams();
+    Object.entries(currentParams).forEach(([key, value]) => {
+      if (value !== void 0 && value !== null && value !== "") {
+        queryParams.append(key, String(value));
+      }
+    });
+    const queryString = queryParams.toString();
+    return queryString ? `${listPath}?${queryString}` : listPath;
+  })();
   const tableActions = [
     {
       label: "\u5237\u65B0",
-      hxGet: listPath,
+      hxGet: refreshUrl,
       variant: "primary"
     }
   ];

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "imean-service-engine-htmx-plugin",
-  "version": "2.9.5",
+  "version": "2.10.1",
   "description": "HtmxAdminPlugin for IMean Service Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsup",
-    "dev": "tsx examples-v2/index.ts",
+    "dev": "tsx watch examples-v2/index.ts",
     "test": "vitest --run",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --run --coverage",

package/docs/README.md

@@ -1,88 +0,0 @@
-# HtmxAdminPlugin 文档索引
-
-## 文档列表
-
-### 📖 [完整文档](../README.md)
-
-完整的使用文档，包含：
-- 概述和核心特性
-- 快速开始指南
-- 模块类型详解
-- 数据源说明
-- 组件系统
-- 路由系统
-- 响应机制
-- 错误处理
-- 高级功能
-- API 参考
-- 最佳实践
-- 示例项目
-
-**适合**: 初次使用或需要全面了解插件的开发者
-
-### 🏗️ [架构设计文档](./architecture.md)
-
-详细的架构设计文档，包含：
-- 架构概述
-- 核心设计原则
-- 统一响应架构
-- 模块系统
-- 路由系统
-- 组件系统
-- 数据流
-- 响应处理流程
-- 关键实现细节
-- 扩展点
-- 性能考虑
-- 安全性考虑
-
-**适合**: 需要深入理解插件架构或进行二次开发的开发者
-
-### ⚡ [快速参考指南](./quick-reference.md)
-
-快速参考指南，包含：
-- 插件配置速查
-- 模块定义模板
-- 数据源示例
-- 常用方法速查
-- 组件速查表
-- 响应头速查
-- 常见场景示例
-- 类型定义速查
-- 路由速查
-- 调试技巧
-- 常见问题
-
-**适合**: 已经熟悉插件，需要快速查找信息的开发者
-
-
-## 文档使用建议
-
-### 新手入门
-
-1. 阅读 [完整文档](../README.md) 的"快速开始"部分
-2. 查看示例项目了解实际用法
-3. 参考 [快速参考指南](./quick-reference.md) 的常见场景
-
-### 深入理解
-
-1. 阅读 [架构设计文档](./architecture.md) 了解设计理念
-2. 阅读 [完整文档](../README.md) 的"高级功能"部分
-3. 查看源代码了解实现细节
-
-### 日常开发
-
-1. 使用 [快速参考指南](./quick-reference.md) 查找常用功能
-2. 参考 [完整文档](../README.md) 的 API 参考
-3. 查看示例项目了解最佳实践
-
-## 相关资源
-
-- **示例项目**: `examples/` 目录
-- **源代码**: `src/plugins/htmx-admin/` 目录
-- **类型定义**: `src/plugins/htmx-admin/types.ts`
-
-## 反馈和建议
-
-如有问题或建议，欢迎提交 Issue 或 Pull Request。
-

package/docs/architecture.md

@@ -1,594 +0,0 @@
-# HtmxAdminPlugin 架构设计文档
-
-## 目录
-
-- [架构概述](#架构概述)
-- [核心设计原则](#核心设计原则)
-- [统一响应架构](#统一响应架构)
-- [模块系统](#模块系统)
-- [路由系统](#路由系统)
-- [权限系统](#权限系统)
-- [组件系统](#组件系统)
-- [数据流](#数据流)
-- [响应处理流程](#响应处理流程)
-
-## 架构概述
-
-HtmxAdminPlugin 采用后端驱动的统一响应架构，通过 `RouteHandler` 统一处理所有请求。所有模块都通过 `__handle()` 方法作为统一入口，简化了请求处理流程。所有响应都通过后端响应头明确指定目标容器，前端无需指定 `hx-target` 或 `hx-swap`。
-
-### 架构层次
-
-```
-┌─────────────────────────────────────────┐
-│          HtmxAdminPlugin                │
-│  (插件入口，模块注册和路由管理)          │
-└─────────────────────────────────────────┘
-                    │
-        ┌───────────┼───────────┐
-        │           │           │
-┌───────▼──────┐ ┌─▼──────┐ ┌─▼──────────┐
-│  模块系统     │ │ 路由系统│ │ 组件系统   │
-│ (Base Classes)│ │(Routes) │ │(Components)│
-└───────┬──────┘ └─┬──────┘ └─┬──────────┘
-        │           │           │
-        └───────────┼───────────┘
-                    │
-        ┌───────────┼───────────┐
-        │           │           │
-┌───────▼──────┐ ┌─▼───────────▼──────────┐
-│  权限系统     │ │    响应处理系统        │
-│ (Auth & Perm)│ │ (OOB Response Builder) │
-└───────┬──────┘ └────────────────────────┘
-        │
-┌───────▼─────────────────────────────────┐
-│  utils/                                   │
-│  - auth.ts (认证和权限校验)               │
-│  - operation.ts (操作ID生成)             │
-│  - permission-handler.tsx (权限拒绝处理)  │
-│  - permissions.ts (权限匹配)             │
-└──────────────────────────────────────────┘
-```
-
-## 核心设计原则
-
-### 1. 后端驱动
-
-**原则**: 所有响应行为由后端控制，前端只负责触发请求。
-
-**实现**:
-- 所有响应都通过 `HX-Retarget` 响应头明确指定目标容器
-- `HX-Push-Url` 由后端控制，决定是否更新 URL
-- 前端请求不指定 `hx-target` 或 `hx-swap`
-
-**优势**:
-- 简化前端代码
-- 统一响应处理逻辑
-- 易于维护和调试
-
-### 2. 统一响应架构
-
-**原则**: 所有响应使用统一的 OOB 交换机制。
-
-**实现**:
-- 主要内容作为非 OOB 内容返回
-- 导航更新等通过 OOB 元素更新
-- 使用 `OOBResponseBuilder` 统一构建响应
-
-**优势**:
-- 一致的响应格式
-- 易于扩展
-- 减少代码重复
-
-### 3. 类型安全
-
-**原则**: 完整的 TypeScript 类型定义。
-
-**实现**:
-- 所有接口和类型都有明确的定义
-- 数据源接口类型化
-- 组件 Props 类型化
-
-**优势**:
-- 编译时错误检查
-- 更好的 IDE 支持
-- 减少运行时错误
-
-### 4. 可扩展性
-
-**原则**: 通过继承和重写实现扩展。
-
-**实现**:
-- 基类提供默认实现
-- 子类可以重写任何方法
-- 支持完全自定义渲染
-
-**优势**:
-- 灵活的定制能力
-- 保持代码简洁
-- 易于理解和使用
-
-## 统一响应架构
-
-### 响应目标检测
-
-响应目标检测在 `HtmxAdminContext` 构造函数中实现：
-
-```typescript
-// 在 HtmxAdminContext 构造函数中
-const url = new URL(ctx.req.url);
-this.isFragment = ctx.req.header("HX-Request") === "true";
-this.isDialog =
-  url.searchParams.get("dialog") === "true" ||
-  ctx.req.header("HX-Target") === "#dialog-container" ||
-  (ctx.req.header("Referer") || "").includes("dialog=true");
-
-// 确定响应目标
-this.target = this.isDialog ? "#dialog-container" : "#main-content";
-this.swap = this.isDialog ? "innerHTML" : "innerHTML";
-```
-
-### 响应头设置
-
-所有响应都会自动添加 `HX-Retarget` 响应头（在 `RouteHandler.renderFragment()` 中）：
-
-```typescript
-const target = adminContext.isDialog
-  ? "#dialog-container"
-  : "#admin-layout";
-const swap = adminContext.isDialog ? "innerHTML" : "outerHTML";
-
-const headers = {
-  "HX-Retarget": target,
-  "HX-Reswap": swap,
-};
-```
-
-### 响应构建
-
-响应构建在 `RouteHandler` 中实现：
-
-**完整页面响应**:
-```typescript
-return ctx.html(
-  <BaseLayout title={adminContext.title} description={adminContext.description}>
-    <AdminLayout adminContext={adminContext}>
-      {adminContext.content}
-    </AdminLayout>
-  </BaseLayout>
-);
-```
-
-**片段响应**:
-```typescript
-const fragments = [
-  // 通知（通过 OOB 更新）
-  adminContext.notifications.map((notification) => (
-    <ErrorAlert type={notification.type} title={notification.title} message={notification.message} />
-  )),
-  <title>{adminContext.title}</title>,
-];
-
-return ctx.html(
-  <>
-    <AdminLayout adminContext={adminContext}>
-      {adminContext.content}
-    </AdminLayout>
-    {fragments}
-  </>,
-  200,
-  { "HX-Retarget": target, "HX-Reswap": swap }
-);
-```
-
-## 模块系统
-
-### 模块类型
-
-插件支持四种模块类型，所有模块类型都继承自 `PageModule` 基类：
-
-```
-PageModule (基类)
-├── ListPageModule (列表页)
-├── DetailPageModule (详情页)
-├── FormPageModule (表单页)
-└── PageModule (自定义页面，直接继承)
-```
-
-#### 架构优势
-
-- **统一基类**: 所有页面模块都继承自 `PageModule`，具有相同的处理过程和结构
-- **默认行为**: 每种类型提供默认的渲染逻辑，满足大部分场景
-- **灵活扩展**: 可以重写 `render()` 方法完全自定义渲染，即使使用 `list`、`detail`、`form` 类型
-- **代码复用**: 通用属性（`basePath`、`__moduleName`、`__moduleMetadata`、`getBreadcrumbs`）在基类中统一管理
-
-### 模块注册流程
-
-```
-1. 插件初始化 (onInit)
-   └─> 存储插件配置
-   └─> 获取 Hono 实例
-
-2. 模块加载 (onModuleLoad)
-   └─> 检查模块类型约束（继承关系）
-   └─> 构建模块类型映射（moduleTypeMap）
-   └─> 为每个模块类型创建 RouteHandler 实例
-   └─> 注册路由（list, detail, form, custom）
-   └─> 注册首页重定向
-```
-
-### 模块元数据
-
-每个模块都有元数据，记录该模块的完整信息：
-
-```typescript
-interface ModuleTypeInfo {
-  title: string;           // 模块标题
-  description: string;     // 模块描述
-  basePath: string;       // 模块基础路径
-  hasList: boolean;        // 是否有列表页
-  hasDetail: boolean;      // 是否有详情页
-  hasForm: boolean;        // 是否有表单页
-  hasCustom: boolean;      // 是否有自定义页
-}
-```
-
-模块可以通过 `this.context.moduleMetadata` 访问元数据：
-
-## 路由系统
-
-### 路由注册
-
-插件根据模块类型自动注册路由：
-
-```
-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           → 更新操作
-
-Custom 模块:
-  GET    /{basePath}               → 自定义页面
-```
-
-### 路由处理流程
-
-```
-1. RouteHandler.handle(ctx)
-   └─> 获取用户信息（通过 AuthProvider.tokenToUser）
-   └─> 创建 HtmxAdminContext
-   └─> 创建模块实例（new moduleClass()）
-   └─> 初始化模块实例（moduleInstance.__init(context)）
-   └─> 权限校验（如果提供了 AuthProvider）
-
-2. 处理请求
-   └─> 调用 moduleInstance.__handle()
-       └─> 默认调用 moduleInstance.render()
-       └─> FormPageModule 重写此方法处理不同 HTTP method
-
-3. 设置页面元数据
-   └─> adminContext.title = moduleInstance.getTitle()
-   └─> adminContext.description = moduleInstance.getDescription()
-   └─> adminContext.breadcrumbs = moduleInstance.getBreadcrumbs()
-
-4. 构建响应
-   └─> 如果是完整页面请求 → renderFullPage()
-   └─> 如果是片段请求 → renderFragment()
-   └─> 自动添加 HX-Retarget 响应头
-   └─> 设置 HX-Push-Url（如果 context.pushUrl 存在）
-
-5. 返回响应
-   └─> ctx.html(responseContent, status, headers)
-```
-
-## 组件系统
-
-### 组件分类
-
-#### 内部组件（不导出）
-
-- `Layout`: 主布局组件
-- `NavItem`: 导航项组件
-- `Header`: 页面头部组件
-- `Breadcrumb`: 面包屑组件
-- `LoadingBar`: 加载指示器
-- `Table`: 表格组件
-
-#### 外部组件（通过 Components 命名空间导出）
-
-- **页面组件**: `Detail`, `Form`, `PageHeader`, `EmptyState`, `Dialog`, `ErrorAlert`
-- **布局组件**: `Card`, `Button`, `ActionButton`, `Pagination`, `FilterCard`
-- **数据展示**: `StatCard`, `ActivityCard`, `SystemStatusCard`, `Badge`
-- **表单组件**: `FormField`, `Input`, `Textarea`, `Select`, `DateInput`
-
-### 组件设计原则
-
-1. **单一职责**: 每个组件只负责一个功能
-2. **可组合**: 组件可以组合使用
-3. **类型安全**: 所有组件都有完整的类型定义
-4. **样式统一**: 使用 Tailwind CSS 统一样式
-
-## 数据流
-
-### 列表页数据流
-
-```
-用户请求 → 路由处理 → 解析参数 → 调用模块方法 → 数据源查询 → 渲染组件 → 返回响应
-```
-
-### 表单提交数据流
-
-```
-用户提交 → 路由处理 → 解析表单数据 → 验证数据 → 调用模块方法 → 数据源操作 → 返回响应
-```
-
-### 错误处理数据流
-
-```
-异常发生 → 捕获异常 → createErrorResponse → 构建错误响应 → 设置 HX-Retarget → 返回错误响应
-```
-
-## 响应处理流程
-
-### 正常响应流程
-
-```
-1. RouteHandler.handle(ctx)
-   └─> 创建 HtmxAdminContext
-   └─> 创建并初始化模块实例
-   └─> 调用 moduleInstance.__handle()
-       └─> 默认调用 moduleInstance.render()
-
-2. 设置页面元数据
-   └─> adminContext.title = moduleInstance.getTitle()
-   └─> adminContext.description = moduleInstance.getDescription()
-   └─> adminContext.breadcrumbs = moduleInstance.getBreadcrumbs()
-
-3. 构建响应
-   └─> 如果是完整页面 → renderFullPage()
-   └─> 如果是片段请求 → renderFragment()
-   └─> 自动设置 HX-Retarget 响应头
-
-4. 返回响应
-   └─> ctx.html(responseContent, status, headers)
-```
-
-### Dialog 模式响应流程
-
-```
-1. 检测 Dialog 模式（在 HtmxAdminContext 构造函数中）
-   └─> URL 参数 dialog=true
-   └─> 或 HX-Target = #dialog-container
-   └─> adminContext.isDialog = true
-   └─> adminContext.target = "#dialog-container"
-
-2. 处理请求（与正常流程相同）
-   └─> 调用 moduleInstance.__handle()
-
-3. 构建响应
-   └─> renderFragment() 检测到 isDialog
-   └─> HX-Retarget: #dialog-container
-   └─> 不设置 HX-Push-Url（保持当前 URL）
-
-4. 返回响应
-   └─> ctx.html(responseContent, 200, headers)
-```
-
-### 错误响应流程
-
-```
-1. 捕获异常（在 RouteHandler.handle() 中）
-   └─> try-catch 捕获业务错误
-   └─> handleError(adminContext, error)
-
-2. 处理错误
-   └─> adminContext.content = 错误内容
-   └─> adminContext.sendNotification("error", "错误", errorMessage)
-
-3. 构建响应
-   └─> 正常构建响应（错误内容 + 通知）
-   └─> 通知通过 OOB 更新到错误容器
-
-4. 返回响应
-   └─> ctx.html(responseContent, status, headers)
-```
-
-## 关键实现细节
-
-### 1. 响应目标检测
-
-响应目标检测逻辑考虑了多种情况：
-
-- URL 参数 `dialog=true`
-- 请求头 `HX-Target`
-- Referer 中的 `dialog=true`
-
-这样可以确保 Dialog 模式在各种场景下都能正确工作。
-
-### 2. OOB 交换策略
-
-OOB 交换策略：
-
-- **主要内容**: 作为非 OOB 内容返回，通过 `HX-Retarget` 指定目标
-- **导航更新**: 通过 OOB 元素更新，只更新状态改变的导航项
-- **错误清空**: 成功响应时通过 OOB 清空错误容器
-
-这样可以实现多区域同时更新，而不需要多个请求。
-
-### 3. URL 状态管理
-
-URL 状态管理策略：
-
-- 筛选条件记录在 URL 查询参数中
-- 分页信息记录在 URL 查询参数中
-- 排序信息记录在 URL 查询参数中
-- 刷新页面后状态自动恢复
-
-这样可以实现书签和分享功能。
-
-### 4. 错误处理机制
-
-错误处理机制：
-
-- 统一的错误响应格式
-- 全局错误通知区域
-- 支持多个错误消息同时显示
-- 每个错误消息可以单独关闭
-
-这样可以提供良好的用户体验。
-
-## 扩展点
-
-### 1. 自定义数据源
-
-实现对应的数据源接口即可：
-
-```typescript
-class CustomDatasource<T> implements ListDatasource<T> {
-  async getList(params: ListParams): Promise<ListResult<T>> {
-    // 自定义实现
-  }
-}
-```
-
-### 2. 自定义组件
-
-可以在自定义页面中使用任何组件：
-
-```typescript
-async render() {
-  return (
-    <div>
-      {/* 使用任何组件 */}
-    </div>
-  );
-}
-```
-
-### 3. 自定义请求处理
-
-可以重写 `__handle()` 方法处理不同的请求逻辑：
-
-```typescript
-async __handle() {
-  const method = this.context.ctx.req.method;
-  if (method === "POST") {
-    // 处理 POST 请求
-  }
-  return await this.render();
-}
-```
-
-### 4. 自定义响应处理
-
-可以通过 `HtmxAdminContext` 控制响应行为：
-
-```typescript
-// 设置推送 URL
-this.context.setPushUrl("/custom/path");
-
-// 发送通知
-this.context.sendSuccess("操作成功", "数据已保存");
-```
-
-## 性能考虑
-
-### 1. 分页
-
-- 列表页默认使用分页
-- 数据源应该实现分页逻辑
-- 避免加载过多数据
-
-### 2. 缓存
-
-- 可以在数据源层面实现缓存
-- 使用适当的缓存策略
-- 注意缓存失效
-
-### 3. 异步处理
-
-- 所有数据操作都是异步的
-- 使用 Promise 处理异步操作
-- 避免阻塞主线程
-
-## 安全性考虑
-
-### 1. 输入验证
-
-- 在数据源层面验证输入
-- 使用参数化查询
-- 防止 SQL 注入
-
-### 2. 认证和权限控制
-
-- **认证**: 通过 `AuthProvider.tokenToUser` 从 Cookie 中获取用户信息
-- **权限检查**: 基于操作ID进行细粒度权限控制
-- **默认权限**: 模块可以声明所需权限，未声明则开放访问
-- **权限匹配**: 支持通配符和禁止权限，提供灵活的权限管理
-- **权限拒绝**: 局部请求使用弹框，整页请求重定向，避免干扰用户体验
-
-### 3. 错误处理
-
-- 不暴露敏感信息
-- 提供有意义的错误消息
-- 记录错误日志
-
-## 总结
-
-HtmxAdminPlugin 采用后端驱动的统一响应架构，通过 `RouteHandler` 统一处理所有请求。所有模块都通过 `__handle()` 方法作为统一入口，简化了请求处理流程。
-
-### 核心设计原则
-
-- **后端驱动**: 所有响应行为由后端控制，前端只负责触发请求
-- **统一处理**: 通过 `RouteHandler` 统一处理所有页面类型的请求
-- **上下文封装**: 通过 `HtmxAdminContext` 封装请求状态和操作
-- **类型安全**: 完整的 TypeScript 类型定义
-- **可扩展性**: 通过继承和重写实现扩展
-- **权限控制**: 基于操作ID的细粒度权限管理，支持通配符和禁止权限
-
-### 核心架构特点
-
-- **模块初始化**: 通过 `__init(context)` 注入上下文，而不是选项对象
-- **统一入口**: `__handle()` 方法作为统一入口，`render()` 专注于渲染
-- **路径助手**: `PathHelper` 简化路径生成
-- **通知机制**: 统一的通知管理机制
-- **权限系统**: 
-  - 基于操作ID的权限检查
-  - 模块级别的权限声明
-  - 内置权限提示页面
-  - 支持局部请求弹框和整页重定向
-
-### 代码组织
-
-插件采用模块化的代码组织方式：
-
-```
-src/
-  plugin.tsx              # 插件主逻辑
-  handler.tsx             # 请求处理流水线
-  base/                   # 模块基类
-    base-page.ts          # PageModule 基类
-    base-list.tsx         # ListPageModule
-    base-detail.tsx       # DetailPageModule
-    base-form.tsx         # FormPageModule
-  components/             # UI 组件
-  utils/                  # 工具函数
-    auth.ts               # 认证和权限校验
-    operation.ts          # 操作ID生成
-    permission-handler.tsx # 权限拒绝处理
-    permissions.ts        # 权限匹配
-    context.tsx           # 上下文对象
-    ...
-  types.ts                # 类型定义
-```
-
-通过这些原则和架构，插件提供了一个灵活、易用、可扩展的管理后台解决方案。
-

package/docs/design-principles.md

@@ -1,102 +0,0 @@
-# 设计原则
-
-## 后端控制交换目标
-
-### 核心原则
-
-**交换目标的控制应该完全交由后端控制，前端不应该设置 `hx-target` 和 `hx-swap` 属性。**
-
-### 为什么？
-
-1. **简洁性**：提供一个简单易用的后台管理框架，代码应该简洁
-2. **灵活性**：后端可以根据请求参数（如 `?dialog=true`）动态决定交换目标
-3. **错误处理**：如果请求失败，后端可以返回错误通知而不替换任何内容，不影响用户的现有工作状态
-
-### 示例场景
-
-#### 场景 1：弹框模式
-
-用户点击一个链接，链接是 `?dialog=true`，后端应该：
-- 检测到 `dialog=true` 参数
-- 设置 `HX-Retarget: #dialog-container` 和 `HX-Reswap: innerHTML`
-- 返回 Dialog 组件包装的内容
-
-**前端代码**：
-```tsx
-// ✅ 正确：使用 hx-get 触发 HTMX 请求，保留 href 用于普通跳转或新窗口打开
-<a 
-  href="/admin/articles/detail/1?dialog=true"
-  hx-get="/admin/articles/detail/1?dialog=true"
->
-  在弹框中打开文章详情
-</a>
-
-// ❌ 错误：不应该在前端设置 hx-target，后端会根据 ?dialog=true 自动设置
-<a 
-  href="/admin/articles/detail/1?dialog=true"
-  hx-get="/admin/articles/detail/1?dialog=true"
-  hx-target="#dialog-container"
-  hx-swap="innerHTML"
->
-  在弹框中打开文章详情
-</a>
-
-// ✅ 正确：只使用 href，用于普通跳转或新窗口打开（右键菜单）
-<a href="/admin/articles/detail/1">
-  在新窗口打开文章详情
-</a>
-```
-
-#### 场景 2：错误处理
-
-如果请求失败（例如权限不足、服务器错误等），后端应该：
-- 返回错误通知（OOB swap）
-- 设置 `HX-Reswap: none` 阻止替换任何内容
-- 不影响用户的现有工作状态
-
-**后端代码**：
-```typescript
-// HTMX 请求失败时
-if (isHtmxRequest) {
-  return ctx.html(
-    <>
-      <div id="error-container" hx-swap-oob="beforeend">
-        <ErrorAlert
-          type="error"
-          title="请求失败"
-          message={errorMessage}
-        />
-      </div>
-      <title>错误</title>
-    </>,
-    500,
-    {
-      "HX-Reswap": "none", // 关键：不替换任何内容
-    }
-  );
-}
-```
-
-### 实现细节
-
-1. **检测弹框模式**：
-   - 通过 `?dialog=true` 查询参数
-   - 通过 `HX-Target: #dialog-container` 请求头
-   - 通过 `Referer` 头中的 `dialog=true`
-
-2. **设置响应头**：
-   - 弹框模式：`HX-Retarget: #dialog-container`, `HX-Reswap: innerHTML`
-   - 普通模式：`HX-Retarget: #main-content`, `HX-Reswap: outerHTML`
-   - 错误/通知：`HX-Reswap: none`（不替换任何内容）
-
-3. **错误处理**：
-   - 所有错误都应该返回通知而不是替换内容
-   - 使用 OOB swap 将通知插入到 `#error-container`
-   - 设置 `HX-Reswap: none` 阻止内容替换
-
-### 优势
-
-1. **代码简洁**：前端代码不需要关心交换目标，只需要提供链接
-2. **灵活控制**：后端可以根据业务逻辑动态决定交换目标
-3. **错误友好**：错误不会破坏用户的当前工作状态
-4. **易于维护**：交换逻辑集中在一个地方，易于修改和测试