@linyjs/plugin-docs 0.0.15 → 0.0.17

package/docs/guides/authentication.md

@@ -11,213 +11,191 @@ linyjs 提供完整的用户认证系统，支持:
 - 🛡️ 路由级别的认证保护
 - 👤 用户信息管理
 
-## 配置认证服务
+## 内置认证服务
 
-### 在服务端模块中注入依赖
+linyjs 的 `authServer` 模块已内置完整的认证功能，包括：
 
-```typescript
-import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
-import { login, register, verifyToken } from '@linyjs/auth';
+| 功能 | 说明 |
+|------|------|
+| `POST /api/auth/register` | 用户注册接口 |
+| `POST /api/auth/login` | 用户登录接口 |
+| `GET /api/auth/me` | 获取当前用户信息（需认证） |
+| `auth` 中间件 | JWT Token 验证中间件，middlewareId 为 `'auth'` |
+| `userService` | 用户管理服务（`IUserService`），提供用户列表和角色管理 |
 
-class AuthController {
-  // ... 控制器实现
-}
+其他模块**无需自行实现**认证逻辑，只需：
 
-const authControllerDef: IServiceDef = {
-  serviceTag: 'authController',
-  serviceImpl: AuthController,
-  dependencies: [],
-  meta: { usageType: 'controller' }
-};
+1. 在 `moduleDependencies` 中声明 `'authServer'`
+2. 在路由的 `middlewares` 中引用 `'auth'` 中间件
+3. 需要用户管理时，通过 `dependencies` 注入 `IUserService`
 
-export const myServerModule: IModule = {
-  name: 'myServer',
-  moduleDependencies: ['auth'],
-  serviceDefs: [authControllerDef]
-};
-```
-
-## 基本认证操作
+## 服务端使用认证
 
-### 用户注册
+### 使用 auth 中间件保护路由
 
 ```typescript
-import { register } from '@linyjs/auth';
+import type { IControllerService, IControllerServiceDef, IModule } from '@linyjs/server-module-interface';
 
-class AuthController {
+class ProtectedController implements IControllerService {
   getRoutes() {
     return [{
-      method: 'POST' as const,
-      path: '/api/auth/register',
-      middlewares: [],
+      method: 'GET' as const,
+      path: '/api/protected',
+      middlewares: ['auth'],  // ← 引用 authServer 模块提供的 auth 中间件
       responseType: 'json' as const,
-      handler: async (req: any) => {
-        const { username, email, password } = req.body;
-        
-        try {
-          const result = await register(username, email, password);
-          return {
-            success: true,
-            message: 'Registration successful',
-            data: result
-          };
-        } catch (error) {
-          return {
-            success: false,
-            message: error instanceof Error ? error.message : 'Registration failed'
-          };
-        }
+      handler: async (params: Record<string, any>, ctx: any) => {
+        // ctx.user 由 auth 中间件注入
+        return {
+          success: true,
+          message: `Hello ${ctx.user.username}! You have access to this protected route.`
+        };
       }
     }];
   }
 }
+
+const protectedControllerDef: IControllerServiceDef = {
+  serviceTag: 'protectedController',
+  serviceImpl: ProtectedController,
+  meta: { usageType: 'controller' }
+};
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['authServer'],  // ← 声明模块依赖
+  serviceDefs: [protectedControllerDef]
+};
 ```
 
-### 用户登录
+> 💡 `auth` 中间件会自动从请求头提取 Bearer Token，验证后会将用户信息注入 `ctx.user`。
+
+### 注入 UserService 进行用户管理
+
+当需要获取用户列表或更新用户角色时，通过依赖注入获取 `IUserService` 实例：
 
 ```typescript
-import { login } from '@linyjs/auth';
+import type { IControllerService, IControllerServiceDef, IModule } from '@linyjs/server-module-interface';
+import type { IUserService, ISafeUser } from '@linyjs/shared-module-interface';
+
+class AdminController implements IControllerService {
+  private userService: IUserService;
+
+  // ✅ 通过构造函数注入获取用户服务
+  constructor({ userService }: { userService: IUserService }) {
+    this.userService = userService;
+  }
 
-class AuthController {
   getRoutes() {
-    return [{
-      method: 'POST' as const,
-      path: '/api/auth/login',
-      middlewares: [],
-      responseType: 'json' as const,
-      handler: async (req: any) => {
-        const { identifier, password } = req.body;
-        
-        try {
-          const result = await login(identifier, password);
-          return {
-            success: true,
-            message: 'Login successful',
-            data: result
-          };
-        } catch (error) {
-          return {
-            success: false,
-            message: error instanceof Error ? error.message : 'Login failed'
-          };
+    return [
+      {
+        method: 'GET' as const,
+        path: '/api/admin/users',
+        middlewares: ['auth'],
+        responseType: 'json' as const,
+        handler: async (params: Record<string, any>, ctx: any) => {
+          // 获取所有用户列表（不含密码哈希）
+          const users: ISafeUser[] = await this.userService.getAllUsers();
+          return { success: true, data: users };
+        }
+      },
+      {
+        method: 'PUT' as const,
+        path: '/api/admin/users/:id/roles',
+        middlewares: ['auth'],
+        responseType: 'json' as const,
+        handler: async (params: Record<string, any>, ctx: any) => {
+          // 更新用户角色
+          const updated = await this.userService.updateUserRoles(
+            params.id,
+            params.roles
+          );
+          if (!updated) {
+            return { status: 404, data: { error: 'User not found' } };
+          }
+          return { success: true, data: updated };
         }
       }
-    }];
+    ];
   }
 }
+
+// ✅ 在 ServiceDef 中声明 dependencies 引用 userService 的 serviceTag
+const adminControllerDef: IControllerServiceDef = {
+  serviceTag: 'adminController',
+  serviceImpl: AdminController,
+  dependencies: ['authServer.userService'],  // ← serviceTag
+  meta: { usageType: 'controller' }
+};
+
+export const adminServerModule: IModule = {
+  name: 'adminServer',
+  moduleDependencies: ['authServer'],  // ← 模块依赖
+  serviceDefs: [adminControllerDef]
+};
 ```
 
-### Token 验证
+### IUserService 接口
+
+`IUserService` 通过 `@linyjs/shared-module-interface` 提供类型定义：
 
 ```typescript
-import { verifyToken, getUserById } from '@linyjs/auth';
+interface IUserService {
+  /** 获取所有用户列表（不含密码哈希） */
+  getAllUsers(): Promise<ISafeUser[]>;
 
-class AuthController {
-  getRoutes() {
-    return [{
-      method: 'GET' as const,
-      path: '/api/auth/me',
-      middlewares: [],
-      responseType: 'json' as const,
-      handler: async (req: any) => {
-        const token = req.headers.authorization?.replace('Bearer ', '');
-        
-        if (!token) {
-          return {
-            success: false,
-            message: 'No token provided'
-          };
-        }
-        
-        try {
-          const payload = await verifyToken(token);
-          const user = await getUserById(payload.userId);
-          
-          return {
-            success: true,
-            data: user
-          };
-        } catch (error) {
-          return {
-            success: false,
-            message: 'Invalid token'
-          };
-        }
-      }
-    }];
-  }
+  /** 更新用户角色 */
+  updateUserRoles(userId: string, roles: string[]): Promise<ISafeUser | null>;
 }
 ```
 
-## 认证中间件
+> 📖 更多类型定义请阅读 [共享模块接口](./shared-module-interface.md)。
 
-### 创建认证中间件
+## 客户端认证
+
+### 调用认证 API
+
+客户端通过 `fetch` 调用 `authServer` 模块提供的认证 API，无需直接导入认证模块：
+
+#### 用户注册
 
 ```typescript
-import { verifyToken, getUserById } from '@linyjs/auth';
-
-async function authMiddleware(req: any, res: any, next: any) {
-  const token = req.headers.authorization?.replace('Bearer ', '');
-  
-  if (!token) {
-    return res.status(401).json({
-      success: false,
-      message: 'Authentication token required'
-    });
-  }
-  
-  try {
-    const payload = await verifyToken(token);
-    const user = await getUserById(payload.userId);
-    
-    if (!user) {
-      return res.status(401).json({
-        success: false,
-        message: 'User not found'
-      });
-    }
-    
-    // 将用户信息添加到请求对象
-    req.user = user;
-    req.userId = user._id;
-    
-    next();
-  } catch (error) {
-    return res.status(401).json({
-      success: false,
-      message: 'Invalid authentication token'
-    });
-  }
+async function register(username: string, email: string, password: string) {
+  const response = await fetch('/api/auth/register', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ username, email, password })
+  });
+  return response.json();
 }
 ```
 
-### 使用认证中间件
+#### 用户登录
 
 ```typescript
-class ProtectedController {
-  getRoutes() {
-    return [{
-      method: 'GET' as const,
-      path: '/api/protected',
-      middlewares: [authMiddleware],  // 使用认证中间件
-      responseType: 'json' as const,
-      handler: async (req: any) => {
-        return {
-          success: true,
-          message: `Hello ${req.user.username}! You have access to this protected route.`
-        };
-      }
-    }];
-  }
+async function login(identifier: string, password: string) {
+  const response = await fetch('/api/auth/login', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ identifier, password })
+  });
+  return response.json();
 }
 ```
 
-## 客户端认证
+#### 获取当前用户
+
+```typescript
+async function getCurrentUser(token: string) {
+  const response = await fetch('/api/auth/me', {
+    headers: { 'Authorization': `Bearer ${token}` }
+  });
+  return response.json();
+}
+```
 
 ### 登录表单示例
 
 ```typescript
-import type { IModule } from '@linyjs/client-module-interface';
 import React, { useState } from 'react';
 
 function LoginForm() {
@@ -226,34 +204,32 @@ function LoginForm() {
     password: ''
   });
   const [error, setError] = useState('');
-  
+
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
-    
+
     try {
       const response = await fetch('/api/auth/login', {
         method: 'POST',
-        headers: {
-          'Content-Type': 'application/json'
-        },
+        headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(formData)
       });
-      
+
       const result = await response.json();
-      
-      if (result.success) {
+
+      if (result.success !== false) {
         // 保存 token 到 localStorage 或 cookie
         localStorage.setItem('token', result.data.token);
         // 跳转或刷新页面
         window.location.reload();
       } else {
-        setError(result.message);
+        setError(result.message || result.error);
       }
     } catch (err) {
       setError('Network error');
     }
   };
-  
+
   return (
     <form onSubmit={handleSubmit}>
       <div>
@@ -279,110 +255,191 @@ function LoginForm() {
     </form>
   );
 }
-
-class LoginFormService {
-  getComponents() {
-    return {
-      LoginForm: {
-        component: LoginForm,
-        meta: { usageType: 'normal_component' }
-      }
-    };
-  }
-}
-
-const loginFormDef: IServiceDef = {
-  serviceTag: 'loginForm',
-  serviceImpl: LoginFormService,
-  meta: { usageType: 'normal_service' }
-};
-
-export const authClientModule: IModule = {
-  name: 'authClient',
-  serviceDefs: [loginFormDef]
-};
 ```
 
 ## 认证状态管理
 
-### 创建认证 Hook
+### 创建并注册认证 Hook
+
+在客户端模块中创建自定义 `useAuth` Hook，并通过 ServiceDef 注册到全局注册表，供其他模块通过 `useClientHook` 消费：
 
 ```typescript
 import { useState, useEffect } from 'react';
+import type { IModule, IHooksDef, IHooksService } from '@linyjs/client-module-interface';
 
-interface User {
-  _id: string;
-  username: string;
-  email: string;
-  createdAt: Date;
-  roles?: string[];
-}
-
-export function useAuth() {
-  const [user, setUser] = useState<User | null>(null);
+// 自定义认证 Hook
+function useAuth() {
+  const [user, setUser] = useState<any>(null);
   const [loading, setLoading] = useState(true);
-  
+
   useEffect(() => {
     const token = localStorage.getItem('token');
-    
+
     if (!token) {
       setLoading(false);
       return;
     }
-    
+
     fetch('/api/auth/me', {
-      headers: {
-        'Authorization': `Bearer ${token}`
-      }
-    })
-    .then(response => response.json())
-    .then(result => {
-      if (result.success) {
-        setUser(result.data);
-      } else {
-        localStorage.removeItem('token');
-      }
+      headers: { 'Authorization': `Bearer ${token}` }
     })
-    .finally(() => {
-      setLoading(false);
-    });
+      .then(response => response.json())
+      .then(result => {
+        if (result.user) {
+          setUser(result.user);
+        } else {
+          localStorage.removeItem('token');
+        }
+      })
+      .finally(() => {
+        setLoading(false);
+      });
   }, []);
-  
+
   const login = async (identifier: string, password: string) => {
     const response = await fetch('/api/auth/login', {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json'
-      },
+      headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ identifier, password })
     });
-    
+
     const result = await response.json();
-    
-    if (result.success) {
+
+    if (result.success !== false) {
       localStorage.setItem('token', result.data.token);
       setUser(result.data.user);
       return true;
     }
-    
+
     return false;
   };
-  
+
   const logout = () => {
     localStorage.removeItem('token');
     setUser(null);
   };
-  
+
   const isAuthenticated = !!user;
-  
-  return {
-    user,
-    loading,
-    isAuthenticated,
-    login,
-    logout
+
+  return { user, loading, isAuthenticated, login, logout };
+}
+
+// 通过 ServiceDef 注册 Hook
+class AuthHooksService implements IHooksService {
+  hooks = {
+    useAuth,
   };
 }
+
+const authHooksDef: IHooksDef = {
+  serviceTag: 'authHooks',
+  serviceImpl: AuthHooksService,
+  meta: { usageType: 'hook' },
+};
+
+export const myClientModule: IModule = {
+  name: 'myClient',
+  serviceDefs: [authHooksDef],
+};
+```
+
+### 跨模块使用认证 Hook
+
+其他模块的组件通过 `useClientHook` 获取 `useAuth` Hook，无需直接导入：
+
+```typescript
+import { useClientHook } from '@linyjs/client-module-interface';
+
+type UseAuth = () => {
+  user: any;
+  loading: boolean;
+  isAuthenticated: boolean;
+  login: (identifier: string, password: string) => Promise<boolean>;
+  logout: () => void;
+};
+
+function NavBar() {
+  // 通过 useClientHook 从注册了 authHooks 的模块获取 useAuth Hook
+  const useAuth = useClientHook<UseAuth>('myClient.authHooks.useAuth');
+
+  if (!useAuth) {
+    return <div>认证功能加载中...</div>;
+  }
+
+  const { user, isAuthenticated, login, logout } = useAuth();
+
+  return (
+    <nav>
+      {isAuthenticated ? (
+        <>
+          <span>欢迎, {user.username}</span>
+          <button onClick={logout}>退出</button>
+        </>
+      ) : (
+        <button onClick={() => login('admin', 'password')}>登录</button>
+      )}
+    </nav>
+  );
+}
+```
+
+> 💡 引用路径 `myClient.authHooks.useAuth` 遵循 `moduleName.serviceTag.hookName` 三段式格式。详见 [公共 Hooks 使用](./client-hooks.md)。
+
+## 路由认证保护
+
+### 在路由元数据中声明认证要求
+
+```typescript
+class MyRouteService {
+  basePath = '/dashboard';
+
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: Dashboard,
+        key: 'dashboard',
+        meta: {
+          requiresAuth: true,  // 标记需要认证
+        }
+      }
+    ];
+  }
+}
+```
+
+### 路由守卫
+
+> ⚠️ 路由守卫的 `canEnter` 回调不是 React 组件，不能使用 Hook。可直接调用认证 API：
+
+```typescript
+{
+  path: '/dashboard',
+  component: Dashboard,
+  key: 'dashboard',
+  guard: {
+    canEnter: async ({ location }) => {
+      const token = localStorage.getItem('token');
+
+      if (!token) {
+        return '/login';  // 未登录，重定向到登录页
+      }
+
+      // 调用认证 API 验证 token
+      const response = await fetch('/api/auth/me', {
+        headers: { 'Authorization': `Bearer ${token}` }
+      });
+      const result = await response.json();
+
+      if (!result.user) {
+        localStorage.removeItem('token');
+        return '/login';  // token 无效，重定向到登录页
+      }
+
+      return true;  // 允许访问
+    }
+  }
+}
 ```
 
 ## 最佳实践
@@ -398,7 +455,7 @@ export function useAuth() {
 - 记录详细的错误日志用于调试
 
 ### 3. 安全性
-- 始终在服务端验证 token
+- 始终在服务端通过 `auth` 中间件验证 token
 - 不要在客户端存储敏感信息
 - 使用强密码策略
 - 考虑实现两步验证增强安全性
@@ -422,7 +479,23 @@ export function useAuth() {
    - 确认用户账户已激活
    - 检查数据库连接是否正常
 
-3. **中间件无法获取用户信息** 
-   - 确认 token 在请求头中正确传递
-   - 检查 verifyToken 函数是否正常工作
-   - 验证 getUserById 是否能找到对应用户
+3. **中间件无法获取用户信息**
+   - 确认 token 在请求头中正确传递（`Authorization: Bearer <token>`）
+   - 确认路由的 `middlewares` 中正确引用了 `'auth'`
+   - 确认模块的 `moduleDependencies` 中声明了 `'authServer'`
+
+4. **无法注入 UserService**
+   - 确认 ServiceDef 的 `dependencies` 中使用了 `'authServer.userService'`
+   - 确认模块的 `moduleDependencies` 中声明了 `'authServer'`
+   - 确认构造函数使用了解构赋值接收依赖
+
+## 相关文档
+
+- 📖 [共享模块接口](./shared-module-interface.md) — `IUserService` 等类型定义
+- 🪝 [公共 Hooks 使用](./client-hooks.md) — `useClientHook` 获取跨模块 Hook
+- 🛤️ [前端页面路由](./client-routes.md) — 路由守卫详细用法
+- 🔐 [权限管理](./permissions.md) — 权限服务使用
+
+---
+
+**上一篇**: [数据持久化](./data-persistence.md) | **下一篇**: [权限管理](./permissions.md)