imean-service-engine-htmx-plugin 1.0.0 → 1.1.0

package/README.md

@@ -138,12 +138,24 @@ const adminPlugin = new HtmxAdminPlugin({
       icon: "👥"
     }
   ],
-  getUserInfo: async (ctx) => {  // 可选，获取用户信息
-    return {
-      name: "管理员",
-      email: "admin@example.com"
-    };
-  }
+  authProvider: {  // 可选，认证和权限提供者
+    cookieKey: "auth_token",  // Cookie 键名（默认 "auth_token"）
+    async tokenToUser(token: string, ctx: Context) {
+      // 从 token 获取用户信息
+      const user = await getUserByToken(token);
+      return {
+        name: user.name,
+        email: user.email,
+        avatar: user.avatar,
+        permissions: user.permissions,  // 用户权限列表
+      };
+    },
+    // checkPermission 可选，不提供则使用默认实现
+    async checkPermission(user, operation, context) {
+      // 自定义权限检查逻辑
+      return { allowed: true };
+    },
+  },
 });
 ```
 
@@ -1758,27 +1770,6 @@ class UserDetailModule extends DetailPageModule<User> {
 }
 ```
 
-### 用户信息
-
-#### 获取用户信息
-
-```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,
-    };
-  },
-});
-```
-
-用户信息会显示在页面右上角。
 
 ### 侧边栏折叠
 
@@ -1804,8 +1795,49 @@ interface HtmxAdminPluginOptions {
   homePath?: string;
   /** 导航配置（集中式声明导航结构，支持嵌套） */
   navigation?: NavItemConfig[];
-  /** 获取用户信息的函数（用于显示用户信息） */
-  getUserInfo?: (ctx: Context) => UserInfo | null | Promise<UserInfo | null>;
+  /** 认证提供者（用于鉴权和权限控制） */
+  authProvider?: AuthProvider;
+}
+```
+
+### AuthProvider
+
+```typescript
+interface AuthProvider {
+  /** Cookie 键名（默认 "auth_token"） */
+  cookieKey?: string;
+  /** 从 token 获取用户信息（必需） */
+  tokenToUser: (token: string, ctx: Context) => Promise<UserInfo | null>;
+  /** 自定义权限检查（可选，不提供则使用默认实现） */
+  checkPermission?: (
+    user: UserInfo | null,
+    operation: string,
+    context: HtmxAdminContext
+  ) => PermissionResult | Promise<PermissionResult>;
+}
+```
+
+### UserInfo
+
+```typescript
+interface UserInfo {
+  name?: string;
+  avatar?: string;
+  email?: string;
+  /** 用户权限列表（支持通配符和禁止权限） */
+  permissions?: string[];
+  [key: string]: any;
+}
+```
+
+### PermissionResult
+
+```typescript
+interface PermissionResult {
+  allowed: boolean;
+  message?: string;
+  operationId?: string;
+  redirectUrl?: string;
 }
 ```
 
@@ -2257,9 +2289,11 @@ class UserListModule extends ListPageModule<User> {
 
 ### 7. 安全性
 
-- 在数据源层面实现权限检查
-- 验证用户输入
-- 使用参数化查询防止 SQL 注入
+- **认证和权限**: 通过 `AuthProvider` 实现认证和权限控制
+- **权限声明**: 模块通过 `getRequiredPermission()` 声明所需权限
+- **权限匹配**: 支持通配符和禁止权限，提供灵活的权限管理
+- **输入验证**: 在数据源层面验证输入
+- **SQL 注入防护**: 使用参数化查询防止 SQL 注入
 
 ## 示例项目
 

package/dist/index.d.mts

@@ -27,8 +27,59 @@ interface UserInfo {
     name?: string;
     avatar?: string;
     email?: string;
+    /** 用户权限列表（支持通配符，如 "users.*", "users.read", "deny:users.delete"） */
+    permissions?: string[];
     [key: string]: any;
 }
+/**
+ * 权限校验结果
+ */
+interface PermissionResult {
+    /** 是否允许访问 */
+    allowed: boolean;
+    /** 如果拒绝访问，可选的错误消息 */
+    message?: string;
+    /** 如果拒绝访问，可选的重定向URL */
+    redirectUrl?: string;
+    /** 被拒绝的操作ID（用于显示详细信息） */
+    operationId?: string;
+}
+/**
+ * 认证提供者接口
+ */
+interface AuthProvider {
+    /** Cookie 中存储 token 的 key（默认 "auth_token"） */
+    cookieKey?: string;
+    /** 将 token 转换为用户信息 */
+    tokenToUser: (token: string, ctx: Context) => UserInfo | null | Promise<UserInfo | null>;
+    /** 权限校验钩子（可选，如果不提供则使用默认实现） */
+    checkPermission?: (user: UserInfo | null, operation: string, context: any) => PermissionResult | Promise<PermissionResult>;
+}
+/**
+ * 操作类型
+ */
+type OperationType = "read" | "create" | "edit" | "delete";
+/**
+ * 操作信息
+ */
+interface OperationInfo {
+    /** 操作ID（格式：moduleName.operation） */
+    operationId: string;
+    /** 模块名 */
+    moduleName: string;
+    /** 操作类型 */
+    operationType: OperationType;
+    /** 模块类型 */
+    moduleType: ModuleType;
+    /** 模块标题 */
+    moduleTitle?: string;
+    /** 模块描述 */
+    moduleDescription?: string;
+    /** HTTP 方法 */
+    httpMethod: string;
+    /** 路由路径 */
+    routePath: string;
+}
 /**
  * 模块类型信息
  */
@@ -69,8 +120,8 @@ interface HtmxAdminPluginOptions {
     homePath?: string;
     /** 导航配置（集中式声明导航结构，支持嵌套） */
     navigation?: NavItemConfig[];
-    /** 获取用户信息的函数（用于显示用户信息） */
-    getUserInfo?: (ctx: Context) => UserInfo | null | Promise<UserInfo | null>;
+    /** 认证提供者（用于鉴权和权限控制） */
+    authProvider?: AuthProvider;
 }
 /**
  * 模块类型
@@ -216,6 +267,8 @@ declare class HtmxAdminContext {
     readonly moduleMetadata: ModuleTypeInfo;
     /** 插件选项 */
     readonly pluginOptions: Required<HtmxAdminPluginOptions>;
+    /** 服务名（用于生成权限ID） */
+    readonly serviceName: string;
     /** Hono Context */
     readonly ctx: Context;
     /** 之前的模块名 */
@@ -240,7 +293,7 @@ declare class HtmxAdminContext {
     redirectUrl?: string;
     /** 是否需要刷新页面（用于 HX-Refresh） */
     refresh: boolean;
-    constructor(ctx: Context, userInfo: UserInfo | null, moduleMetadata: ModuleTypeInfo, pluginOptions: Required<HtmxAdminPluginOptions>);
+    constructor(ctx: Context, userInfo: UserInfo | null, moduleMetadata: ModuleTypeInfo, pluginOptions: Required<HtmxAdminPluginOptions>, serviceName?: string);
     /**
      * 发送通知
      * 通知将在响应时通过 OOB 更新到错误容器
@@ -334,6 +387,20 @@ declare abstract class PageModule {
      * 默认实现：首页 => 自定义页面
      */
     getBreadcrumbs(): BreadcrumbItem[];
+    /**
+     * 获取所需权限
+     * 子类可以重写此方法来声明页面所需的权限
+     *
+     * 返回值说明：
+     * - 返回空字符串 "" 或 null 或 undefined：表示开放访问（无需权限）
+     * - 返回权限字符串：表示需要该权限，如 "users.read", "users.*"
+     *
+     * 默认实现：返回空字符串（开放访问）
+     *
+     * @param ctx Hono Context（可选，用于根据请求动态决定权限）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission?(ctx?: any): string | null | undefined;
     /**
      * 处理请求的统一入口（由 RouteHandler 调用）
      * 默认实现：直接调用 render 方法
@@ -370,6 +437,15 @@ declare abstract class PageModule {
 declare abstract class DetailPageModule<T = any> extends PageModule {
     /** ID 字段名（默认 "id"） */
     protected readonly idField: string;
+    /**
+     * 获取所需权限
+     * 默认实现：返回 "{serviceName}.{moduleName}.read"
+     * 子类可以重写此方法来自定义权限要求
+     *
+     * @param ctx Hono Context（可选）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission(ctx?: any): string | null | undefined;
     /**
      * 获取数据源（抽象方法，必须实现）
      * 子类必须实现此方法来提供数据源
@@ -435,6 +511,17 @@ declare abstract class FormPageModule<T = any> extends PageModule {
     /** Zod Schema（可选，如果提供则自动生成表单字段和校验） */
     protected schema?: z.ZodObject<any>;
     constructor(schema?: z.ZodObject<any>);
+    /**
+     * 获取所需权限
+     * 根据是新建还是编辑返回不同的权限要求
+     * - 新建：{serviceName}.{moduleName}.create
+     * - 编辑：{serviceName}.{moduleName}.edit
+     * 子类可以重写此方法来自定义权限要求
+     *
+     * @param ctx Hono Context（可选）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission(ctx?: any): string | null | undefined;
     /**
      * 获取数据源（抽象方法，必须实现）
      * 子类必须实现此方法来提供数据源
@@ -558,6 +645,15 @@ declare abstract class ListPageModule<T extends {
 }> extends PageModule {
     /** ID 字段名（默认 "id"） */
     protected readonly idField: string;
+    /**
+     * 获取所需权限
+     * 默认实现：返回 "{serviceName}.{moduleName}.read"
+     * 子类可以重写此方法来自定义权限要求
+     *
+     * @param ctx Hono Context（可选）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission(ctx?: any): string | null | undefined;
     /**
      * 获取数据源（抽象方法，必须实现）
      * 子类必须实现此方法来提供数据源
@@ -688,7 +784,9 @@ declare class HtmxAdminPlugin implements Plugin<HtmxAdminModuleOptions> {
     private engine;
     private hono;
     private options;
+    private serviceName;
     private moduleTypeMap;
+    private registeredOperations;
     constructor(options?: HtmxAdminPluginOptions);
     /**
      * 声明Module配置Schema
@@ -702,10 +800,38 @@ declare class HtmxAdminPlugin implements Plugin<HtmxAdminModuleOptions> {
      * 检查并注册模块
      */
     private checkAndRegisterModules;
+    /**
+     * 根据模块类型和路由信息生成操作ID
+     */
+    private generateOperationId;
+    /**
+     * 注册内置路由（权限提示页面）
+     */
+    private registerBuiltinRoutes;
     /**
      * 注册路由
      */
     private registerRoutes;
+    /**
+     * 获取所有注册的操作（权限）列表
+     * 可用于权限管理模块作为数据源，或用于确定管理员的权限
+     *
+     * @returns 所有注册的操作信息列表
+     */
+    getRegisteredOperations(): OperationInfo[];
+    /**
+     * 获取指定模块的所有操作
+     *
+     * @param moduleName 模块名
+     * @returns 该模块的所有操作信息列表
+     */
+    getModuleOperations(moduleName: string): OperationInfo[];
+    /**
+     * 获取所有唯一的操作ID列表（去重）
+     *
+     * @returns 所有唯一的操作ID列表
+     */
+    getOperationIds(): string[];
     /**
      * 模块加载钩子：检查模块类型约束并注册路由
      */

package/dist/index.d.ts

@@ -27,8 +27,59 @@ interface UserInfo {
     name?: string;
     avatar?: string;
     email?: string;
+    /** 用户权限列表（支持通配符，如 "users.*", "users.read", "deny:users.delete"） */
+    permissions?: string[];
     [key: string]: any;
 }
+/**
+ * 权限校验结果
+ */
+interface PermissionResult {
+    /** 是否允许访问 */
+    allowed: boolean;
+    /** 如果拒绝访问，可选的错误消息 */
+    message?: string;
+    /** 如果拒绝访问，可选的重定向URL */
+    redirectUrl?: string;
+    /** 被拒绝的操作ID（用于显示详细信息） */
+    operationId?: string;
+}
+/**
+ * 认证提供者接口
+ */
+interface AuthProvider {
+    /** Cookie 中存储 token 的 key（默认 "auth_token"） */
+    cookieKey?: string;
+    /** 将 token 转换为用户信息 */
+    tokenToUser: (token: string, ctx: Context) => UserInfo | null | Promise<UserInfo | null>;
+    /** 权限校验钩子（可选，如果不提供则使用默认实现） */
+    checkPermission?: (user: UserInfo | null, operation: string, context: any) => PermissionResult | Promise<PermissionResult>;
+}
+/**
+ * 操作类型
+ */
+type OperationType = "read" | "create" | "edit" | "delete";
+/**
+ * 操作信息
+ */
+interface OperationInfo {
+    /** 操作ID（格式：moduleName.operation） */
+    operationId: string;
+    /** 模块名 */
+    moduleName: string;
+    /** 操作类型 */
+    operationType: OperationType;
+    /** 模块类型 */
+    moduleType: ModuleType;
+    /** 模块标题 */
+    moduleTitle?: string;
+    /** 模块描述 */
+    moduleDescription?: string;
+    /** HTTP 方法 */
+    httpMethod: string;
+    /** 路由路径 */
+    routePath: string;
+}
 /**
  * 模块类型信息
  */
@@ -69,8 +120,8 @@ interface HtmxAdminPluginOptions {
     homePath?: string;
     /** 导航配置（集中式声明导航结构，支持嵌套） */
     navigation?: NavItemConfig[];
-    /** 获取用户信息的函数（用于显示用户信息） */
-    getUserInfo?: (ctx: Context) => UserInfo | null | Promise<UserInfo | null>;
+    /** 认证提供者（用于鉴权和权限控制） */
+    authProvider?: AuthProvider;
 }
 /**
  * 模块类型
@@ -216,6 +267,8 @@ declare class HtmxAdminContext {
     readonly moduleMetadata: ModuleTypeInfo;
     /** 插件选项 */
     readonly pluginOptions: Required<HtmxAdminPluginOptions>;
+    /** 服务名（用于生成权限ID） */
+    readonly serviceName: string;
     /** Hono Context */
     readonly ctx: Context;
     /** 之前的模块名 */
@@ -240,7 +293,7 @@ declare class HtmxAdminContext {
     redirectUrl?: string;
     /** 是否需要刷新页面（用于 HX-Refresh） */
     refresh: boolean;
-    constructor(ctx: Context, userInfo: UserInfo | null, moduleMetadata: ModuleTypeInfo, pluginOptions: Required<HtmxAdminPluginOptions>);
+    constructor(ctx: Context, userInfo: UserInfo | null, moduleMetadata: ModuleTypeInfo, pluginOptions: Required<HtmxAdminPluginOptions>, serviceName?: string);
     /**
      * 发送通知
      * 通知将在响应时通过 OOB 更新到错误容器
@@ -334,6 +387,20 @@ declare abstract class PageModule {
      * 默认实现：首页 => 自定义页面
      */
     getBreadcrumbs(): BreadcrumbItem[];
+    /**
+     * 获取所需权限
+     * 子类可以重写此方法来声明页面所需的权限
+     *
+     * 返回值说明：
+     * - 返回空字符串 "" 或 null 或 undefined：表示开放访问（无需权限）
+     * - 返回权限字符串：表示需要该权限，如 "users.read", "users.*"
+     *
+     * 默认实现：返回空字符串（开放访问）
+     *
+     * @param ctx Hono Context（可选，用于根据请求动态决定权限）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission?(ctx?: any): string | null | undefined;
     /**
      * 处理请求的统一入口（由 RouteHandler 调用）
      * 默认实现：直接调用 render 方法
@@ -370,6 +437,15 @@ declare abstract class PageModule {
 declare abstract class DetailPageModule<T = any> extends PageModule {
     /** ID 字段名（默认 "id"） */
     protected readonly idField: string;
+    /**
+     * 获取所需权限
+     * 默认实现：返回 "{serviceName}.{moduleName}.read"
+     * 子类可以重写此方法来自定义权限要求
+     *
+     * @param ctx Hono Context（可选）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission(ctx?: any): string | null | undefined;
     /**
      * 获取数据源（抽象方法，必须实现）
      * 子类必须实现此方法来提供数据源
@@ -435,6 +511,17 @@ declare abstract class FormPageModule<T = any> extends PageModule {
     /** Zod Schema（可选，如果提供则自动生成表单字段和校验） */
     protected schema?: z.ZodObject<any>;
     constructor(schema?: z.ZodObject<any>);
+    /**
+     * 获取所需权限
+     * 根据是新建还是编辑返回不同的权限要求
+     * - 新建：{serviceName}.{moduleName}.create
+     * - 编辑：{serviceName}.{moduleName}.edit
+     * 子类可以重写此方法来自定义权限要求
+     *
+     * @param ctx Hono Context（可选）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission(ctx?: any): string | null | undefined;
     /**
      * 获取数据源（抽象方法，必须实现）
      * 子类必须实现此方法来提供数据源
@@ -558,6 +645,15 @@ declare abstract class ListPageModule<T extends {
 }> extends PageModule {
     /** ID 字段名（默认 "id"） */
     protected readonly idField: string;
+    /**
+     * 获取所需权限
+     * 默认实现：返回 "{serviceName}.{moduleName}.read"
+     * 子类可以重写此方法来自定义权限要求
+     *
+     * @param ctx Hono Context（可选）
+     * @returns 所需权限字符串，或空字符串/null/undefined 表示开放
+     */
+    getRequiredPermission(ctx?: any): string | null | undefined;
     /**
      * 获取数据源（抽象方法，必须实现）
      * 子类必须实现此方法来提供数据源
@@ -688,7 +784,9 @@ declare class HtmxAdminPlugin implements Plugin<HtmxAdminModuleOptions> {
     private engine;
     private hono;
     private options;
+    private serviceName;
     private moduleTypeMap;
+    private registeredOperations;
     constructor(options?: HtmxAdminPluginOptions);
     /**
      * 声明Module配置Schema
@@ -702,10 +800,38 @@ declare class HtmxAdminPlugin implements Plugin<HtmxAdminModuleOptions> {
      * 检查并注册模块
      */
     private checkAndRegisterModules;
+    /**
+     * 根据模块类型和路由信息生成操作ID
+     */
+    private generateOperationId;
+    /**
+     * 注册内置路由（权限提示页面）
+     */
+    private registerBuiltinRoutes;
     /**
      * 注册路由
      */
     private registerRoutes;
+    /**
+     * 获取所有注册的操作（权限）列表
+     * 可用于权限管理模块作为数据源，或用于确定管理员的权限
+     *
+     * @returns 所有注册的操作信息列表
+     */
+    getRegisteredOperations(): OperationInfo[];
+    /**
+     * 获取指定模块的所有操作
+     *
+     * @param moduleName 模块名
+     * @returns 该模块的所有操作信息列表
+     */
+    getModuleOperations(moduleName: string): OperationInfo[];
+    /**
+     * 获取所有唯一的操作ID列表（去重）
+     *
+     * @returns 所有唯一的操作ID列表
+     */
+    getOperationIds(): string[];
     /**
      * 模块加载钩子：检查模块类型约束并注册路由
      */