imean-service-engine-htmx-plugin 1.0.1 → 1.2.0

package/docs/architecture.md

@@ -7,6 +7,7 @@
 - [统一响应架构](#统一响应架构)
 - [模块系统](#模块系统)
 - [路由系统](#路由系统)
+- [权限系统](#权限系统)
 - [组件系统](#组件系统)
 - [数据流](#数据流)
 - [响应处理流程](#响应处理流程)
@@ -32,10 +33,20 @@ HtmxAdminPlugin 采用后端驱动的统一响应架构，通过 `RouteHandler`
         │           │           │
         └───────────┼───────────┘
                     │
-        ┌───────────▼───────────┐
-        │    响应处理系统        │
-        │ (OOB Response Builder) │
-        └───────────────────────┘
+        ┌───────────┼───────────┐
+        │           │           │
+┌───────▼──────┐ ┌─▼───────────▼──────────┐
+│  权限系统     │ │    响应处理系统        │
+│ (Auth & Perm)│ │ (OOB Response Builder) │
+└───────┬──────┘ └────────────────────────┘
+        │
+┌───────▼─────────────────────────────────┐
+│  utils/                                   │
+│  - auth.ts (认证和权限校验)               │
+│  - operation.ts (操作ID生成)             │
+│  - permission-handler.tsx (权限拒绝处理)  │
+│  - permissions.ts (权限匹配)             │
+└──────────────────────────────────────────┘
 ```
 
 ## 核心设计原则
@@ -268,10 +279,11 @@ Custom 模块:
 
 ```
 1. RouteHandler.handle(ctx)
-   └─> 获取用户信息（getUserInfo）
+   └─> 获取用户信息（通过 AuthProvider.tokenToUser）
    └─> 创建 HtmxAdminContext
    └─> 创建模块实例（new moduleClass()）
    └─> 初始化模块实例（moduleInstance.__init(context)）
+   └─> 权限校验（如果提供了 AuthProvider）
 
 2. 处理请求
    └─> 调用 moduleInstance.__handle()
@@ -531,11 +543,13 @@ this.context.sendSuccess("操作成功", "数据已保存");
 - 使用参数化查询
 - 防止 SQL 注入
 
-### 2. 权限控制
+### 2. 认证和权限控制
 
-- 在数据源层面实现权限检查
-- 验证用户身份
-- 控制数据访问
+- **认证**: 通过 `AuthProvider.tokenToUser` 从 Cookie 中获取用户信息
+- **权限检查**: 基于操作ID进行细粒度权限控制
+- **默认权限**: 模块可以声明所需权限，未声明则开放访问
+- **权限匹配**: 支持通配符和禁止权限，提供灵活的权限管理
+- **权限拒绝**: 局部请求使用弹框，整页请求重定向，避免干扰用户体验
 
 ### 3. 错误处理
 
@@ -547,18 +561,50 @@ this.context.sendSuccess("操作成功", "数据已保存");
 
 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/quick-reference.md

@@ -3,6 +3,7 @@
 ## 目录
 
 - [插件配置](#插件配置)
+- [认证和权限](#认证和权限)
 - [模块定义](#模块定义)
 - [数据源](#数据源)
 - [常用方法](#常用方法)
@@ -37,14 +38,17 @@ const adminPlugin = new HtmxAdminPlugin({
       icon: "👥",
     },
   ],
-  getUserInfo: async (ctx) => ({
-    name: "管理员",
-    email: "admin@example.com",
-  }),
-  generateBreadcrumb: (currentPath, navItems) => [
-    { label: "首页", href: "/admin" },
-    { label: "当前页" },
-  ],
+  authProvider: {
+    cookieKey: "auth_token",
+    async tokenToUser(token, ctx) {
+      const user = await getUserByToken(token);
+      return user ? {
+        name: user.name,
+        email: user.email,
+        permissions: user.permissions,
+      } : null;
+    },
+  },
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imean-service-engine-htmx-plugin",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "HtmxAdminPlugin for IMean Service Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",