imean-service-engine-htmx-plugin 1.0.0

package/docs/quick-reference.md

@@ -0,0 +1,559 @@
+# HtmxAdminPlugin 快速参考指南
+
+## 目录
+
+- [插件配置](#插件配置)
+- [模块定义](#模块定义)
+- [数据源](#数据源)
+- [常用方法](#常用方法)
+- [组件速查](#组件速查)
+- [响应头速查](#响应头速查)
+- [常见场景](#常见场景)
+
+## 插件配置
+
+### 基本配置
+
+```typescript
+const adminPlugin = new HtmxAdminPlugin({
+  title: "管理后台",
+  prefix: "/admin",
+  logo: "/logo.png",  // 可选
+});
+```
+
+### 完整配置
+
+```typescript
+const adminPlugin = new HtmxAdminPlugin({
+  title: "管理后台",
+  prefix: "/admin",
+  logo: "/logo.png",
+  homePath: "/admin/dashboard", // 首页路径，访问 /admin 时重定向到此路径
+  navigation: [
+    {
+      label: "用户管理",
+      moduleName: "users",
+      icon: "👥",
+    },
+  ],
+  getUserInfo: async (ctx) => ({
+    name: "管理员",
+    email: "admin@example.com",
+  }),
+  generateBreadcrumb: (currentPath, navItems) => [
+    { label: "首页", href: "/admin" },
+    { label: "当前页" },
+  ],
+});
+```
+
+## 模块定义
+
+### List 模块
+
+```typescript
+@Module("products", {
+  type: "list",
+})
+class ProductListModule extends ListPageModule<Product> {
+  constructor() {
+    super(productDatasource);
+  }
+  
+  renderColumn(field: string, value: any, item: Product): any {
+    // 自定义列渲染
+  }
+  
+  getActions(item: Product) {
+    return [
+      this.action.detail("查看"),
+      this.action.delete("删除"),
+    ];
+  }
+}
+```
+
+### Detail 模块
+
+```typescript
+@Module("users", {
+  type: "detail",
+})
+class UserDetailModule extends DetailPageModule<User> {
+  constructor() {
+    super(userDatasource);
+  }
+  
+  getFieldLabel(field: string): string {
+    // 自定义字段标签
+  }
+  
+  renderField(field: string, value: any, item: User): any {
+    // 自定义字段渲染
+  }
+  
+  getFieldGroups(item: User) {
+    // 字段分组
+  }
+}
+```
+
+### Form 模块
+
+```typescript
+@Module("articles", {
+  type: "form",
+})
+class ArticleFormModule extends FormPageModule<Article> {
+  constructor() {
+    super(articleDatasource);
+  }
+  
+  getFormFields(item: Article | null) {
+    return [
+      { name: "title", label: "标题", type: "text", required: true },
+      { name: "content", label: "内容", type: "textarea", required: true },
+    ];
+  }
+  
+  validateFormData(data: Record<string, any>, item: Article | null): string | null {
+    // 表单验证
+  }
+}
+```
+
+### Custom 模块
+
+```typescript
+@Module("dashboard", {
+  type: "custom",
+})
+class DashboardModule extends PageModule {
+  async render() {
+    return <div>自定义内容</div>;
+  }
+}
+```
+
+## 数据源
+
+### 内存数据源
+
+```typescript
+const datasource = new MemoryListDatasource<User>([
+  { id: 1, name: "张三", email: "zhangsan@example.com" },
+  { id: 2, name: "李四", email: "lisi@example.com" },
+]);
+```
+
+### 自定义数据源
+
+```typescript
+class DatabaseDatasource<T> implements ListDatasource<T> {
+  async getList(params: ListParams): Promise<ListResult<T>> {
+    // 数据库查询
+  }
+  
+  async deleteItem(id: string | number): Promise<boolean> {
+    // 数据库删除
+  }
+}
+```
+
+## 常用方法
+
+### PathHelper
+
+```typescript
+// 在模块中使用（通过 this.paths 访问）
+this.paths.detail(id)                    // 生成详情页路径
+this.paths.edit(id)                      // 生成编辑页路径
+this.paths.create()                      // 生成新建页路径
+this.paths.delete(id)                    // 生成删除操作路径
+this.paths.list()                        // 生成列表页路径
+this.paths.detail(id, true)              // Dialog 模式
+```
+
+### 错误处理
+
+```typescript
+// 在模块的 render 或 __handle 方法中
+this.context.sendError("错误标题", "错误消息");
+this.context.sendWarning("警告标题", "警告消息");
+this.context.sendInfo("信息标题", "信息消息");
+this.context.sendSuccess("成功标题", "成功消息");
+
+// 或使用通用方法
+this.context.sendNotification("error", "错误标题", "错误消息");
+```
+
+### URL 控制
+
+```typescript
+// 设置推送 URL
+this.context.setPushUrl("/admin/users/list");
+
+// 设置页面刷新
+this.context.setRefresh(true);
+```
+
+## 组件速查
+
+### 页面组件
+
+```typescript
+import { Components } from "imean-service-engine";
+const { Detail, Form, PageHeader, EmptyState, Dialog, ErrorAlert } = Components;
+
+<Detail item={item} fieldLabels={{...}} actions={[...]} />
+<Form fields={[...]} submitUrl="..." method="POST" />
+<PageHeader title="标题" description="描述" />
+<EmptyState message="暂无数据" />
+<Dialog title="标题">{content}</Dialog>
+<ErrorAlert message="错误消息" type="error" />
+```
+
+### 布局组件
+
+```typescript
+const { Card, Button, ActionButton, Pagination, FilterCard } = Components;
+
+<Card>{content}</Card>
+<Button variant="primary" href="..." hxGet="...">按钮</Button>
+<ActionButton label="操作" href="..." method="DELETE" />
+<Pagination page={1} totalPages={10} basePath="/admin/users/list" />
+<FilterCard fields={[...]} />
+```
+
+### 表单组件
+
+```typescript
+const { FormField, Input, Textarea, Select, DateInput } = Components;
+
+<FormField id="name" label="姓名" required>
+  <Input name="name" placeholder="请输入姓名" />
+</FormField>
+
+<FormField id="bio" label="简介">
+  <Textarea name="bio" rows={4} />
+</FormField>
+
+<FormField id="status" label="状态">
+  <Select name="status" options={[...]} />
+</FormField>
+
+<FormField id="date" label="日期">
+  <DateInput type="date" name="date" />
+</FormField>
+```
+
+## 响应头速查
+
+### HX-Retarget
+
+指定响应内容的目标容器：
+
+- `#main-content`: 主内容区域（默认）
+- `#dialog-container`: 对话框容器（dialog 模式）
+- `#error-container`: 错误通知容器（错误响应）
+- `#sidebar`: 侧边栏（侧边栏切换）
+
+### HX-Push-Url
+
+控制是否更新 URL：
+
+- 正常模式：设置 `HX-Push-Url` 更新 URL
+- Dialog 模式：不设置 `HX-Push-Url`，保持当前 URL
+
+### HX-Reswap
+
+控制交换方式：
+
+- `innerHTML`: 替换内容（默认）
+- `beforeend`: 追加内容（错误消息）
+
+## 常见场景
+
+### 场景 1: 列表页自定义列渲染
+
+```typescript
+renderColumn(field: string, value: any, item: T): any {
+  if (field === "status") {
+    return (
+      <span className={`px-2 py-1 rounded ${getStatusColor(value)}`}>
+        {getStatusLabel(value)}
+      </span>
+    );
+  }
+  return value;
+}
+```
+
+### 场景 2: 详情页字段分组
+
+```typescript
+getFieldGroups(item: T) {
+  return [
+    { title: "基本信息", fields: ["id", "name", "email"] },
+    { title: "其他信息", fields: ["createdAt", "updatedAt"] },
+  ];
+}
+```
+
+### 场景 3: 表单验证
+
+```typescript
+validateFormData(data: Record<string, any>, item: T | null): string | null {
+  if (!data.name || data.name.trim().length === 0) {
+    return "名称不能为空";
+  }
+  if (data.email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
+    return "邮箱格式不正确";
+  }
+  return null;
+}
+```
+
+### 场景 4: Dialog 模式
+
+```typescript
+// 在操作按钮中使用
+getActions(item: T) {
+  return [
+    { label: "查看", href: this.paths.detail(item.id) },  // 正常模式
+    { label: "快速查看", href: this.paths.detail(item.id, true) },  // Dialog 模式
+  ];
+}
+```
+
+### 场景 5: 自定义页面
+
+```typescript
+async render() {
+  const { Card, Button, PageHeader, StatCard } = Components;
+  
+  return (
+    <div>
+      <PageHeader title="仪表盘" />
+      <div className="grid grid-cols-3 gap-4">
+        <StatCard title="总数" value="100" />
+        <StatCard title="今日" value="10" />
+        <StatCard title="待处理" value="5" />
+      </div>
+    </div>
+  );
+}
+```
+
+### 场景 6: 错误处理
+
+```typescript
+async render() {
+  try {
+    const result = await processData();
+    this.context.sendSuccess("操作成功", "数据已处理");
+    return <div>{result}</div>;
+  } catch (error) {
+    this.context.sendError("操作失败", error.message);
+    return <div>处理失败</div>;
+  }
+}
+```
+
+### 场景 7: 统计信息
+
+```typescript
+async getStats(params: ListParams) {
+  const result = await this.getList({ ...params, pageSize: 1000 });
+  
+  return [
+    {
+      title: "总数",
+      value: result.total,
+      iconColor: "blue" as const,
+    },
+    {
+      title: "已完成",
+      value: result.items.filter(item => item.status === "completed").length,
+      change: 12.5,
+      changeLabel: "%",
+      iconColor: "green" as const,
+    },
+  ];
+}
+```
+
+### 场景 8: 筛选器
+
+```typescript
+getFilters(params: ListParams) {
+  return [
+    {
+      name: "status",
+      label: "状态",
+      options: [
+        { value: "pending", label: "待处理" },
+        { value: "completed", label: "已完成" },
+      ],
+      value: params.filters?.status,
+    },
+  ];
+}
+```
+
+## 类型定义速查
+
+### 模块选项
+
+```typescript
+interface HtmxAdminModuleOptions {
+  type: "list" | "detail" | "form" | "custom";
+  title?: string;        // 模块标题（可选，默认使用模块名）
+  description?: string;  // 模块描述（可选）
+}
+```
+
+### 列表参数
+
+```typescript
+interface ListParams {
+  page?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortOrder?: "asc" | "desc";
+  filters?: Record<string, any>;
+}
+```
+
+### 列表结果
+
+```typescript
+interface ListResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+```
+
+### 表单字段
+
+```typescript
+interface FormField {
+  name: string;
+  label: string;
+  type?: "text" | "email" | "number" | "textarea" | "select" | "date" | "datetime-local";
+  required?: boolean;
+  placeholder?: string;
+  options?: Array<{ value: string | number; label: string }>;
+}
+```
+
+## 路由速查
+
+### 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`: 删除操作（如果数据源支持）
+
+### Dialog 模式
+
+- `GET /{basePath}/detail/:id?dialog=true`: 对话框详情
+- `GET /{basePath}/new?dialog=true`: 对话框新建
+- `GET /{basePath}/edit/:id?dialog=true`: 对话框编辑
+
+## 调试技巧
+
+### 1. 查看响应头
+
+在浏览器开发者工具的 Network 标签中查看响应头：
+
+- `HX-Retarget`: 响应目标
+- `HX-Push-Url`: URL 更新
+- `HX-Reswap`: 交换方式
+
+### 2. 查看 HTMX 请求
+
+HTMX 请求会包含以下请求头：
+
+- `HX-Request: true`: 标识 HTMX 请求
+- `HX-Target`: 请求目标（如果指定）
+- `Referer`: 来源页面
+
+### 3. 查看 OOB 元素
+
+在响应 HTML 中查找 `hx-swap-oob` 属性：
+
+```html
+<div id="nav-item-xxx" hx-swap-oob="true">...</div>
+<div id="error-container" hx-swap-oob="innerHTML"></div>
+```
+
+### 4. 调试 Dialog
+
+- 检查 URL 是否包含 `dialog=true`
+- 检查 `#dialog-container` 是否存在
+- 检查响应头 `HX-Retarget` 是否为 `#dialog-container`
+
+### 5. 调试错误
+
+- 检查错误响应状态码
+- 检查 `#error-container` 是否显示错误
+- 检查错误消息格式是否正确
+
+## 常见问题
+
+### Q: Dialog 模式不工作？
+
+A: 检查：
+1. URL 是否包含 `dialog=true`
+2. 响应头 `HX-Retarget` 是否为 `#dialog-container`
+3. `#dialog-container` 是否存在于 DOM 中
+
+### Q: 错误消息不显示？
+
+A: 检查：
+1. 是否使用 `createErrorResponse`
+2. 响应头 `HX-Retarget` 是否为 `#error-container`
+3. `#error-container` 是否存在于 DOM 中
+
+### Q: 导航不更新？
+
+A: 检查：
+1. OOB 响应是否包含导航更新元素
+2. 导航项的 `id` 是否正确
+3. `hx-swap-oob` 属性是否正确
+
+### Q: URL 状态不保存？
+
+A: 检查：
+1. 是否设置了 `HX-Push-Url` 响应头
+2. URL 查询参数是否正确构建
+3. 筛选器和分页是否使用正确的参数名
+
+## 最佳实践
+
+1. **使用 PathHelper**: 通过 `this.paths` 简化路径生成
+2. **统一错误处理**: 使用 `context.sendNotification()` 发送通知
+3. **类型安全**: 充分利用 TypeScript 类型
+4. **组件复用**: 使用 `Components` 命名空间中的组件
+5. **响应式设计**: 使用 Tailwind CSS 响应式类
+6. **性能优化**: 使用分页和筛选减少数据量
+7. **安全性**: 在数据源层面实现权限检查
+8. **上下文访问**: 通过 `this.context` 访问请求状态和 helper 方法
+

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "imean-service-engine-htmx-plugin",
+  "version": "1.0.0",
+  "description": "HtmxAdminPlugin for IMean Service Engine",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx examples/index.ts",
+    "test": "vitest --run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --run --coverage",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "microservice",
+    "hono",
+    "framework",
+    "typescript"
+  ],
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@hono/node-server": "^1.19.7",
+    "hono": "^4.10.8",
+    "imean-service-engine": "^2.3.0",
+    "prettier": "^3.7.4",
+    "winston": "^3.19.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.1",
+    "@vitest/coverage-v8": "4.0.15",
+    "@vitest/ui": "^4.0.15",
+    "imean-service-client": "^1.6.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}