imean-service-engine-htmx-plugin 1.0.0

package/docs/README.md

@@ -0,0 +1,87 @@
+# 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

@@ -0,0 +1,564 @@
+# HtmxAdminPlugin 架构设计文档
+
+## 目录
+
+- [架构概述](#架构概述)
+- [核心设计原则](#核心设计原则)
+- [统一响应架构](#统一响应架构)
+- [模块系统](#模块系统)
+- [路由系统](#路由系统)
+- [组件系统](#组件系统)
+- [数据流](#数据流)
+- [响应处理流程](#响应处理流程)
+
+## 架构概述
+
+HtmxAdminPlugin 采用后端驱动的统一响应架构，通过 `RouteHandler` 统一处理所有请求。所有模块都通过 `__handle()` 方法作为统一入口，简化了请求处理流程。所有响应都通过后端响应头明确指定目标容器，前端无需指定 `hx-target` 或 `hx-swap`。
+
+### 架构层次
+
+```
+┌─────────────────────────────────────────┐
+│          HtmxAdminPlugin                │
+│  (插件入口，模块注册和路由管理)          │
+└─────────────────────────────────────────┘
+                    │
+        ┌───────────┼───────────┐
+        │           │           │
+┌───────▼──────┐ ┌─▼──────┐ ┌─▼──────────┐
+│  模块系统     │ │ 路由系统│ │ 组件系统   │
+│ (Base Classes)│ │(Routes) │ │(Components)│
+└───────┬──────┘ └─┬──────┘ └─┬──────────┘
+        │           │           │
+        └───────────┼───────────┘
+                    │
+        ┌───────────▼───────────┐
+        │    响应处理系统        │
+        │ (OOB Response Builder) │
+        └───────────────────────┘
+```
+
+## 核心设计原则
+
+### 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` 访问元数据：
+
+```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;
+}
+```
+
+## 路由系统
+
+### 路由注册
+
+插件根据模块类型自动注册路由：
+
+```
+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)
+   └─> 获取用户信息（getUserInfo）
+   └─> 创建 HtmxAdminContext
+   └─> 创建模块实例（new moduleClass()）
+   └─> 初始化模块实例（moduleInstance.__init(context)）
+
+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. 权限控制
+
+- 在数据源层面实现权限检查
+- 验证用户身份
+- 控制数据访问
+
+### 3. 错误处理
+
+- 不暴露敏感信息
+- 提供有意义的错误消息
+- 记录错误日志
+
+## 总结
+
+HtmxAdminPlugin 采用后端驱动的统一响应架构，通过 `RouteHandler` 统一处理所有请求。所有模块都通过 `__handle()` 方法作为统一入口，简化了请求处理流程。
+
+核心设计原则：
+- **后端驱动**: 所有响应行为由后端控制，前端只负责触发请求
+- **统一处理**: 通过 `RouteHandler` 统一处理所有页面类型的请求
+- **上下文封装**: 通过 `HtmxAdminContext` 封装请求状态和操作
+- **类型安全**: 完整的 TypeScript 类型定义
+- **可扩展性**: 通过继承和重写实现扩展
+
+核心架构特点：
+- **模块初始化**: 通过 `__init(context)` 注入上下文，而不是选项对象
+- **统一入口**: `__handle()` 方法作为统一入口，`render()` 专注于渲染
+- **路径助手**: `PathHelper` 简化路径生成
+- **通知机制**: 统一的通知管理机制
+
+通过这些原则和架构，插件提供了一个灵活、易用、可扩展的管理后台解决方案。
+