@linyjs/plugin-docs 0.0.15 → 0.0.16

package/docs/guides/permissions.md

@@ -42,28 +42,41 @@ admin:access      # 访问管理后台
 
 ## 服务端权限检查
 
+服务端通过依赖注入获取 `IPermissionService` 实例。只需在 ServiceDef 中声明 `dependencies` 引用权限服务的 `serviceTag`，并在模块中声明 `moduleDependencies`，框架会自动注入服务实例。
+
 ### 在控制器中检查权限
 
 ```typescript
-class ArticleController {
+import type { IControllerService, IControllerServiceDef, IModule } from '@linyjs/server-module-interface';
+import type { IPermissionService } from '@linyjs/shared-module-interface';
+
+class ArticleController implements IControllerService {
+  private permissionService: IPermissionService;
+
+  // ✅ 通过构造函数注入获取权限服务
+  constructor({ permissionService }: { permissionService: IPermissionService }) {
+    this.permissionService = permissionService;
+  }
+
   getRoutes() {
     return [
       {
-        method: 'POST',
+        method: 'POST' as const,
         path: '/api/articles',
         middlewares: ['auth'],
-        responseType: 'json',
-        handler: async (params: any, ctx: any) => {
+        responseType: 'json' as const,
+        handler: async (params: Record<string, any>, ctx: any) => {
           const user = ctx.user;
-          
-          // 检查权限
-          if (!user.roles?.includes('admin')) {
+
+          // 通过权限服务检查权限
+          const result = await this.permissionService.check(user, 'article:write');
+          if (!result.allowed) {
             return {
               status: 403,
-              data: { error: 'Admin access required' }
+              data: { error: result.reason }
             };
           }
-          
+
           // 业务逻辑...
           const article = await createArticle(params);
           return { success: true, data: article };
@@ -72,47 +85,62 @@ class ArticleController {
     ];
   }
 }
+
+// ✅ 在 ServiceDef 中声明 dependencies 引用权限服务的 serviceTag
+const articleControllerDef: IControllerServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  dependencies: ['permissionServer.permissionService'],  // ← serviceTag
+  meta: { usageType: 'controller' },
+};
+
+export const articleServerModule: IModule = {
+  name: 'articleServer',
+  moduleDependencies: ['permissionServer'],  // ← 模块依赖
+  serviceDefs: [articleControllerDef],
+};
 ```
 
 ### 创建权限中间件
 
 ```typescript
-import type { IMiddlewareService } from '@linyjs/server-module-interface';
+import type { IMiddlewareService, IServiceDef } from '@linyjs/server-module-interface';
+import type { IPermissionService } from '@linyjs/shared-module-interface';
 
 class PermissionMiddleware implements IMiddlewareService {
+  private permissionService: IPermissionService;
+
+  // ✅ 通过构造函数注入获取权限服务
+  constructor({ permissionService }: { permissionService: IPermissionService }) {
+    this.permissionService = permissionService;
+  }
+
   getMiddlewares() {
     return [{
       middlewareId: 'checkPermission',
       handler: async (params: any, ctx: any, next: any) => {
         const user = ctx.user;
-        const requiredPermission = params.route?.meta?.requiredPermission;
-        
-        if (requiredPermission && !hasPermission(user, requiredPermission)) {
-          throw new Error('Insufficient permissions');
+        const requiredPermission = ctx.route?.meta?.requiredPermission;
+
+        if (requiredPermission) {
+          // 通过权限服务检查权限
+          const result = await this.permissionService.check(user, requiredPermission);
+          if (!result.allowed) {
+            throw new Error(result.reason || 'Insufficient permissions');
+          }
         }
-        
+
         await next();
       }
     }];
   }
 }
 
-function hasPermission(user: any, permission: string): boolean {
-  // 检查用户角色是否拥有该权限
-  const rolePermissions = {
-    admin: ['article:read', 'article:write', 'article:delete'],
-    editor: ['article:read', 'article:write'],
-    viewer: ['article:read']
-  };
-  
-  return user.roles?.some((role: string) => 
-    rolePermissions[role]?.includes(permission)
-  );
-}
-
-export const permissionMiddlewareDef = {
+// ✅ 声明 dependencies 引用权限服务的 serviceTag
+export const permissionMiddlewareDef: IServiceDef = {
   serviceTag: 'permissionMiddleware',
   serviceImpl: PermissionMiddleware,
+  dependencies: ['permissionServer.permissionService'],  // ← serviceTag
   meta: { usageType: 'middleware' }
 };
 ```
@@ -139,28 +167,45 @@ export const permissionMiddlewareDef = {
 
 ### 使用 usePermission Hook
 
+客户端通过 `useClientHook` 从 `permissionClient` 模块获取 `usePermission` Hook：
+
 ```typescript
-import { usePermission } from '@linyjs/permission';
+import { useClientHook } from '@linyjs/client-module-interface';
+
+type UsePermission = (
+  permission: string,
+  context?: Record<string, any>
+) => { hasPermission: boolean; loading: boolean };
 
 function ArticleEditor() {
-  const { hasPermission } = usePermission();
-  const canEdit = hasPermission('article:write');
-  const canDelete = hasPermission('article:delete');
-  
+  // 通过 useClientHook 从 permissionClient 模块获取 usePermission Hook
+  const usePermission = useClientHook<UsePermission>(
+    'permissionClient.permissionHooks.usePermission'
+  );
+
+  if (!usePermission) {
+    return <div>权限功能加载中...</div>;
+  }
+
+  const { hasPermission: canEdit, loading } = usePermission('article:write');
+  const { hasPermission: canDelete } = usePermission('article:delete');
+
+  if (loading) return <div>加载中...</div>;
+
   return (
     <div>
       <h1>Edit Article</h1>
-      
+
       {canEdit && (
         <button onClick={handleSave}>Save</button>
       )}
-      
+
       {canDelete && (
         <button onClick={handleDelete} style={{ color: 'red' }}>
           Delete
         </button>
       )}
-      
+
       {!canEdit && (
         <p>You don't have permission to edit this article.</p>
       )}
@@ -169,18 +214,32 @@ function ArticleEditor() {
 }
 ```
 
+> 💡 引用路径 `permissionClient.permissionHooks.usePermission` 遵循 `moduleName.serviceTag.hookName` 三段式格式。详见 [公共 Hooks 使用](./client-hooks.md)。
+
 ### 条件渲染组件
 
 ```typescript
-import { usePermission } from '@linyjs/permission';
+import { useClientHook } from '@linyjs/client-module-interface';
+
+type UsePermission = (
+  permission: string,
+  context?: Record<string, any>
+) => { hasPermission: boolean; loading: boolean };
 
 function ProtectedComponent({ children }: { children: React.ReactNode }) {
-  const { hasPermission } = usePermission();
-  
-  if (!hasPermission('admin:access')) {
+  // 通过 useClientHook 从 permissionClient 模块获取 usePermission Hook
+  const usePermission = useClientHook<UsePermission>(
+    'permissionClient.permissionHooks.usePermission'
+  );
+
+  if (!usePermission) return null;
+
+  const { hasPermission } = usePermission('admin:access');
+
+  if (!hasPermission) {
     return null;  // 不渲染
   }
-  
+
   return <>{children}</>;
 }
 
@@ -229,6 +288,8 @@ class BlogRouteService {
 
 ### 路由守卫
 
+> ⚠️ 路由守卫的 `canEnter` 回调不是 React 组件，不能使用 Hook。可直接调用权限检查 API：
+
 ```typescript
 {
   path: '/admin',
@@ -236,12 +297,18 @@ class BlogRouteService {
   key: 'admin',
   guard: {
     canEnter: async ({ location }) => {
-      const { hasPermission } = usePermission();
-      
-      if (!hasPermission('admin:access')) {
+      // 直接调用权限检查 API（由 permissionServer 模块提供）
+      const response = await fetch('/api/permission/check', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ permission: 'admin:access' }),
+      });
+      const result = await response.json();
+
+      if (!result.allowed) {
         return '/forbidden';  // 重定向
       }
-      
+
       return true;  // 允许访问
     }
   }
@@ -381,11 +448,12 @@ permissions: ['admin:access']
 ```typescript
 // 服务端必须再次验证
 handler: async (params, ctx) => {
-  // 即使客户端已检查,服务端仍需验证
-  if (!hasPermission(ctx.user, 'article:delete')) {
-    return { status: 403, data: { error: 'Forbidden' } };
+  // 即使客户端已检查，服务端仍需通过权限服务验证
+  const result = await this.permissionService.check(ctx.user, 'article:delete');
+  if (!result.allowed) {
+    return { status: 403, data: { error: result.reason } };
   }
-  
+
   // 执行删除
 }
 ```
@@ -393,11 +461,12 @@ handler: async (params, ctx) => {
 ### 3. 清晰的错误消息
 
 ```typescript
-if (!hasPermission(user, 'article:write')) {
+const result = await this.permissionService.check(user, 'article:write');
+if (!result.allowed) {
   return {
     status: 403,
-    data: { 
-      error: 'You do not have permission to edit articles',
+    data: {
+      error: result.reason || 'You do not have permission to edit articles',
       requiredPermission: 'article:write'
     }
   };
@@ -432,6 +501,8 @@ function useUserPermissions() {
 
 ## 相关文档
 
+- 📖 [共享模块接口](./shared-module-interface.md) — `IPermissionService` 等类型定义
+- 🪝 [公共 Hooks 使用](./client-hooks.md) — `useClientHook` 获取跨模块 Hook
 - 🎨 [UI 扩展插槽](./ui-slots.md)
 - 💾 [数据持久化](./data-persistence.md)
 

package/docs/guides/server-module.md

@@ -443,6 +443,8 @@ class MyController {
 
 - 📖 阅读 [依赖注入机制](./dependency-injection.md) — 完整的 DI 机制说明
 - 💻 阅读 [客户端模块开发](./client-module.md)
+- 🛤️ 阅读 [前端页面路由](./client-routes.md) — 路由定义与使用
+- 🪝 阅读 [公共 Hooks 使用](./client-hooks.md) — 跨模块资源消费
 - 💾 阅读 [数据持久化](./data-persistence.md)
 - 🔒 阅读 [权限管理](./permissions.md)
 

package/docs/guides/shared-module-interface.md

@@ -4,23 +4,17 @@
 
 ## 概述
 
-`@linyjs/shared-module-interface` 是一个**纯类型包**，汇集了 linyjs 框架所有公共模块（mdb、auth、permission）的 TypeScript 接口和类型定义。
+`@linyjs/shared-module-interface` 是一个**纯类型包**，汇集了 linyjs 框架所有公共服务的 TypeScript 接口和类型定义。
 
 ### 为什么需要这个包？
 
-linyjs 插件作为独立的 npm 包或 git 仓库开发，通过依赖注入机制获取 `IMongoDBService` 等服务实例。但 TypeScript 编译器需要类型声明才能提供：
+linyjs 插件通过依赖注入机制获取 `IMongoDBService`、`IUserService`、`IPermissionService` 等服务实例。但 TypeScript 编译器需要类型声明才能提供：
 
 - ✅ 构造函数参数的类型提示
 - ✅ 服务方法的自动补全
 - ✅ 编译时类型检查
 
-如果每个插件都单独安装 `@linyjs/mdb`、`@linyjs/auth` 等包来获取类型，会带来：
-
-- 📦 **包体积增大** — 插件打包了不需要的运行时代码
-- ⚠️ **版本冲突** — 插件与框架使用的模块版本不一致
-- 🔧 **配置冗余** — 每个插件都要在 `package.json` 中声明多个依赖
-
-`@linyjs/shared-module-interface` 通过**纯类型导出**解决这些问题——只提供类型声明，不包含任何运行时代码。
+`@linyjs/shared-module-interface` 通过**纯类型导出**解决这些问题——只提供类型声明，不包含任何运行时代码。插件无需安装任何运行时模块包，只需在 `devDependencies` 中添加此类型包即可获得完整的类型支持。
 
 ## 安装
 
@@ -38,6 +32,15 @@ linyjs 插件作为独立的 npm 包或 git 仓库开发，通过依赖注入机
 
 ## 使用方式
 
+### 核心用法：声明即可用
+
+使用框架提供的服务只需两步：
+
+1. **在 ServiceDef 中声明 `dependencies`**（引用对应的 `serviceTag`）
+2. **在 `moduleDependencies` 中声明模块依赖**
+
+框架会自动注入服务实例，无需关心运行时来源。
+
 ### 导入类型
 
 所有导出都使用 `import type` 语法，确保编译后类型被完全擦除：
@@ -53,10 +56,12 @@ import type { ObjectId, Db, Collection, Document, Filter } from '@linyjs/shared-
 
 ```typescript
 import type { IMongoDBService } from '@linyjs/shared-module-interface';
+import type { IServiceDef, IModule } from '@linyjs/server-module-interface';
 
 class ArticleService {
   private mongoDBService: IMongoDBService;
 
+  // ✅ 解构赋值接收依赖
   constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
     this.mongoDBService = mongoDBService;
   }
@@ -69,34 +74,49 @@ class ArticleService {
     });
   }
 }
+
+// ✅ 在 ServiceDef 中声明 dependencies 即可获取服务
+const articleServiceDef: IServiceDef = {
+  serviceTag: 'articleService',
+  serviceImpl: ArticleService,
+  dependencies: ['mdb.mongoDBService'],  // 引用对应 serviceTag
+  meta: { usageType: 'normal_service' }
+};
+
+export const articleServerModule: IModule = {
+  name: 'articleServer',
+  moduleDependencies: ['mdb'],  // 声明模块依赖
+  serviceDefs: [articleServiceDef]
+};
 ```
 
 > 📖 关于依赖注入机制的完整说明，请阅读 [依赖注入机制](./dependency-injection.md)。
 
-## 可用类型一览
+## 可用服务类型一览
 
-### mdb 模块类型
+以下是通过 `@linyjs/shared-module-interface` 提供的所有公共服务类型。插件只需在 ServiceDef 中声明对应的 `serviceTag` 和 `moduleDependencies`，即可获取服务实例。
 
-| 类型 | 说明 | 运行时来源 |
-|------|------|------------|
-| `IMongoDBService` | MongoDB 服务接口 | `@linyjs/mdb` 模块通过 `mdb.mongoDBService` 注入 |
-| `ObjectId` | MongoDB ObjectId 类型 | mongodb 包（运行时通过 `service.ObjectId` 获取） |
-| `Db` | MongoDB 数据库实例类型 | mongodb 包 |
-| `Collection` | MongoDB 集合类型 | mongodb 包 |
-| `Document` | MongoDB 文档类型 | mongodb 包 |
-| `Filter` | 查询过滤器类型 | mongodb 包 |
-| `Sort` | 排序类型 | mongodb 包 |
-| `UpdateFilter` | 更新操作类型 | mongodb 包 |
-| `InsertOneResult` | 插入结果类型 | mongodb 包 |
-| `UpdateResult` | 更新结果类型 | mongodb 包 |
-| `DeleteResult` | 删除结果类型 | mongodb 包 |
-| ... | mongodb 包的全部类型 | mongodb 包 |
+### IMongoDBService — 数据库服务
 
-#### IMongoDBService 接口
+| 类型 | 说明 |
+|------|------|
+| `IMongoDBService` | 数据库服务接口 |
+| `ObjectId` | ObjectId 类型（运行时通过 `service.ObjectId` 获取构造器） |
+| `Db` | 数据库实例类型 |
+| `Collection` | 集合类型 |
+| `Document` | 文档类型 |
+| `Filter` | 查询过滤器类型 |
+| `Sort` | 排序类型 |
+| `UpdateFilter` | 更新操作类型 |
+| `InsertOneResult` | 插入结果类型 |
+| `UpdateResult` | 更新结果类型 |
+| `DeleteResult` | 删除结果类型 |
+
+#### 接口定义
 
 ```typescript
 interface IMongoDBService {
-  /** MongoDB ObjectId 构造器（运行时通过此属性获取，无需单独安装 mongodb） */
+  /** ObjectId 构造器（运行时通过此属性获取，无需单独安装 mongodb） */
   readonly ObjectId: typeof ObjectId;
 
   /** 获取数据库实例 */
@@ -113,7 +133,24 @@ interface IMongoDBService {
 }
 ```
 
-### auth 模块类型
+#### 声明方式
+
+```typescript
+const myServiceDef: IServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  dependencies: ['mdb.mongoDBService'],  // ← serviceTag
+  meta: { usageType: 'normal_service' }
+};
+
+const myModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['mdb'],  // ← 模块依赖
+  serviceDefs: [myServiceDef]
+};
+```
+
+### IUserService — 用户管理服务
 
 | 类型 | 说明 |
 |------|------|
@@ -125,7 +162,7 @@ interface IMongoDBService {
 | `IsRootUser` | 判断用户是否为 Root 角色的函数类型 |
 | `IsAdminUser` | 判断用户是否为 Admin 角色的函数类型 |
 
-#### IUserService 接口
+#### 接口定义
 
 ```typescript
 interface IUserService {
@@ -137,9 +174,24 @@ interface IUserService {
 }
 ```
 
-> 依赖声明：`dependencies: ['authServer.userService']`
+#### 声明方式
 
-### permission 模块类型
+```typescript
+const myServiceDef: IServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  dependencies: ['authServer.userService'],  // ← serviceTag
+  meta: { usageType: 'normal_service' }
+};
+
+const myModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['authServer'],  // ← 模块依赖
+  serviceDefs: [myServiceDef]
+};
+```
+
+### IPermissionService — 权限检查服务
 
 | 类型 | 说明 |
 |------|------|
@@ -150,7 +202,7 @@ interface IUserService {
 | `IPermissionPolicy` | 权限策略定义 |
 | `IPermissionCheckResult` | 权限检查结果 |
 
-#### IPermissionService 接口
+#### 接口定义
 
 ```typescript
 interface IPermissionService {
@@ -173,11 +225,36 @@ interface IPermissionService {
 }
 ```
 
-> 依赖声明：`dependencies: ['permissionServer.permissionService']`
+#### 声明方式
+
+```typescript
+const myServiceDef: IServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  dependencies: ['permissionServer.permissionService'],  // ← serviceTag
+  meta: { usageType: 'normal_service' }
+};
+
+const myModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['permissionServer'],  // ← 模块依赖
+  serviceDefs: [myServiceDef]
+};
+```
+
+## 可注入服务汇总
+
+| 声明 dependencies | 声明 moduleDependencies | 接口类型 |
+|-------------------|------------------------|----------|
+| `'mdb.mongoDBService'` | `'mdb'` | `IMongoDBService` |
+| `'authServer.userService'` | `'authServer'` | `IUserService` |
+| `'permissionServer.permissionService'` | `'permissionServer'` | `IPermissionService` |
+
+> 💡 只需在 ServiceDef 的 `dependencies` 中声明 serviceTag、在模块的 `moduleDependencies` 中声明模块依赖，框架会自动注入服务实例。
 
 ## ObjectId 的运行时使用
 
-`@linyjs/shared-module-interface` 是纯类型包，`ObjectId` 等类型导入在编译后会被擦除。运行时需要通过注入的 `IMongoDBService` 实例获取 `ObjectId` 构造器：
+`@linyjs/shared-module-interface` 是纯类型包，`ObjectId` 等类型导入在编译后会被擦除。运行时需要通过注入的服务实例获取 `ObjectId` 构造器：
 
 ```typescript
 import type { IMongoDBService, ObjectId } from '@linyjs/shared-module-interface';
@@ -207,7 +284,7 @@ class ArticleService {
 
 ### 在服务类外部使用 ObjectId
 
-如果需要在服务类外部（如工具函数、模型层）创建 `ObjectId`，可以将 `mongoDBService` 引用保存到模块级变量：
+如果需要在服务类外部（如工具函数、模型层）创建 `ObjectId`，可以将服务引用保存到模块级变量：
 
 ```typescript
 // db.ts
@@ -240,7 +317,7 @@ class ArticleService {
   }
 
   async initialize() {
-    // 将 mongoDBService 保存到模块级变量，供工具函数使用
+    // 将服务保存到模块级变量，供工具函数使用
     setMongoDBService(this.mongoDBService);
   }
 
@@ -251,20 +328,9 @@ class ArticleService {
 }
 ```
 
-## 可注入服务汇总
-
-| 依赖引用 | 接口类型 | 来源模块 | 说明 |
-|----------|----------|----------|------|
-| `'mdb.mongoDBService'` | `IMongoDBService` | mdb | MongoDB 数据库服务 |
-| `'authServer.userService'` | `IUserService` | auth | 用户管理服务 |
-| `'authServer.initService'` | - | auth | 系统初始化服务 |
-| `'permissionServer.permissionService'` | `IPermissionService` | permission | 权限检查服务 |
-
-> 💡 使用这些服务时，需要在模块定义中声明 `moduleDependencies`。
-
 ## 完整示例
 
-以下示例展示如何同时注入多个基础模块服务：
+以下示例展示如何同时注入多个公共服务：
 
 ```typescript
 import type { IModule, IServiceDef, IControllerService } from '@linyjs/server-module-interface';
@@ -339,9 +405,9 @@ export const adminServerModule: IModule = {
 ## 相关文档
 
 - 📖 [依赖注入机制](./dependency-injection.md) — DI 的完整说明
-- 💾 [数据持久化](./data-persistence.md) — MongoDB 服务详细使用
-- 🔐 [用户认证](./authentication.md) — 认证模块使用
-- 🛡️ [权限管理](./permissions.md) — 权限模块使用
+- 💾 [数据持久化](./data-persistence.md) — 数据库服务详细使用
+- 🔐 [用户认证](./authentication.md) — 用户服务使用
+- 🛡️ [权限管理](./permissions.md) — 权限服务使用
 - 🔧 [API 参考](../api-reference/index.md) — 接口类型定义
 
 ---

package/docs/guides/ui-slots.md

@@ -468,8 +468,10 @@ registry.register({
 ## 相关文档
 
 - 📖 [客户端模块开发](./client-module.md)
+- 🛤️ [前端页面路由](./client-routes.md)
+- 🪝 [公共 Hooks 使用](./client-hooks.md)
 - 🔒 [权限管理](./permissions.md)
 
 ---
 
-**上一篇**: [客户端模块开发](./client-module.md) | **下一篇**: [权限管理](./permissions.md)
+**上一篇**: [公共 Hooks 使用](./client-hooks.md) | **下一篇**: [权限管理](./permissions.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linyjs/plugin-docs",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Plugin development documentation and examples for linyjs framework",
   "keywords": [
     "linyjs",