@linyjs/plugin-docs 0.1.2 → 0.1.3

package/README.md

@@ -74,7 +74,8 @@ docs/
 │   ├── client-module.md  # 客户端模块
 │   ├── ui-slots.md       # UI扩展插槽
 │   ├── permissions.md    # 权限管理
-│   └── data-persistence.md # 数据持久化
+│   ├── data-persistence.md # 数据持久化
+│   └── authentication.md # 用户认证
 ├── api-reference/        # API参考
 │   ├── server-interface.md
 │   ├── client-interface.md
@@ -102,12 +103,40 @@ examples/
 - 详细的 README 说明
 - 可直接打包为 .mpk 文件
 
+## 🔧 核心模块
+
+linyjs 提供了以下核心模块，插件可以通过依赖注入方式调用这些基础服务：
+
+### @linyjs/mongodb
+**MongoDB 数据库服务**
+- 提供数据持久化存储
+- 支持 CRUD 操作和复杂查询
+- 详情：[数据持久化指南](./docs/guides/data-persistence.md)
+
+### @linyjs/auth  
+**用户认证系统**
+- 支持用户注册、登录、Token 验证
+- 提供 JWT 身份验证
+- 详情：[认证指南](./docs/guides/authentication.md)
+
+### @linyjs/permission
+**权限管理系统**  
+- 基于角色的访问控制(RBAC)
+- 细粒度的权限定义
+- 详情：[权限管理指南](./docs/guides/permissions.md)
+
 ## 🔗 相关链接
 
 - [linyjs 框架](https://github.com/linyjs/linyjs)
 - [CLI 工具文档](https://github.com/linyjs/linyjs/tree/main/packages/cli)
 - [报告文档问题](https://github.com/linyjs/linyjs/issues)
 
+## 📖 核心模块指南
+
+- 💾 [数据持久化](./docs/guides/data-persistence.md) - 使用 @linyjs/mongodb
+- 🔐 [用户认证](./docs/guides/authentication.md) - 使用 @linyjs/auth
+- 🛡️ [权限管理](./docs/guides/permissions.md) - 使用 @linyjs/permission
+
 ## 📄 许可证
 
 MIT License

package/docs/api-reference/index.md

@@ -330,11 +330,31 @@ registry.register({
 
 ---
 
+## 基础模块
+
+linyjs 框架提供了以下基础模块，插件开发者可以通过依赖注入方式使用：
+
+### 数据库模块
+- **@linyjs/mongodb** - MongoDB 数据库服务
+- 提供数据库连接、CRUD 操作、索引管理等功能
+- 详见：[数据持久化指南](../guides/data-persistence.md)
+
+### 认证模块
+- **@linyjs/auth** - 用户认证系统
+- 提供用户注册、登录、Token 验证等功能
+- 详见：[认证指南](../guides/authentication.md)
+
+### 权限模块
+- **@linyjs/permission** - 权限管理系统
+- 提供基于角色的访问控制(RBAC)
+- 详见：[权限管理指南](../guides/permissions.md)
+
 ## 相关文档
 
 - 📖 [服务端模块开发](../guides/server-module.md)
 - 💻 [客户端模块开发](../guides/client-module.md)
 - 🎨 [UI 扩展插槽](../guides/ui-slots.md)
+- 💾 [基础模块使用指南](../README.md#-核心模块)
 
 ---
 

package/docs/guides/authentication.md

@@ -0,0 +1,420 @@
+# 用户认证
+
+本指南介绍如何在 linyjs 插件中使用认证系统实现用户登录、注册和权限验证。
+
+## 概述
+
+linyjs 提供完整的用户认证系统，支持:
+
+- 🔐 用户注册和登录
+- 🪙 JWT Token 认证
+- 🛡️ 路由级别的认证保护
+- 👤 用户信息管理
+
+## 配置认证服务
+
+### 在服务端模块中注入依赖
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+import { login, register, verifyToken } from '@linyjs/auth';
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['auth'],  // 依赖认证模块
+  serviceDefs: [
+    {
+      serviceTag: 'authController',
+      serviceImpl: AuthController,
+      dependencies: [],  // 依赖注入将在类构造函数中使用
+      meta: { usageType: 'controller' }
+    }
+  ]
+};
+```
+
+## 基本认证操作
+
+### 用户注册
+
+```typescript
+import { register } from '@linyjs/auth';
+
+class AuthController {
+  getRoutes() {
+    return [{
+      method: 'POST' as const,
+      path: '/api/auth/register',
+      middlewares: [],
+      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'
+          };
+        }
+      }
+    }];
+  }
+}
+```
+
+### 用户登录
+
+```typescript
+import { login } from '@linyjs/auth';
+
+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'
+          };
+        }
+      }
+    }];
+  }
+}
+```
+
+### Token 验证
+
+```typescript
+import { verifyToken, getUserById } from '@linyjs/auth';
+
+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'
+          };
+        }
+      }
+    }];
+  }
+}
+```
+
+## 认证中间件
+
+### 创建认证中间件
+
+```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'
+    });
+  }
+}
+```
+
+### 使用认证中间件
+
+```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.`
+        };
+      }
+    }];
+  }
+}
+```
+
+## 客户端认证
+
+### 登录表单示例
+
+```typescript
+import type { IModule } from '@linyjs/client-module-interface';
+import React, { useState } from 'react';
+
+function LoginForm() {
+  const [formData, setFormData] = useState({
+    identifier: '',
+    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'
+        },
+        body: JSON.stringify(formData)
+      });
+      
+      const result = await response.json();
+      
+      if (result.success) {
+        // 保存 token 到 localStorage 或 cookie
+        localStorage.setItem('token', result.data.token);
+        // 跳转或刷新页面
+        window.location.reload();
+      } else {
+        setError(result.message);
+      }
+    } catch (err) {
+      setError('Network error');
+    }
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <div>
+        <label>用户名或邮箱:</label>
+        <input
+          type="text"
+          value={formData.identifier}
+          onChange={(e) => setFormData({ ...formData, identifier: e.target.value })}
+          required
+        />
+      </div>
+      <div>
+        <label>密码:</label>
+        <input
+          type="password"
+          value={formData.password}
+          onChange={(e) => setFormData({ ...formData, password: e.target.value })}
+          required
+        />
+      </div>
+      {error && <div className="error">{error}</div>}
+      <button type="submit">登录</button>
+    </form>
+  );
+}
+
+export const authClientModule: IModule = {
+  name: 'authClient',
+  serviceDefs: [{
+    serviceTag: 'loginForm',
+    serviceImpl: function() {
+      getComponents() {
+        return {
+          LoginForm: {
+            component: LoginForm,
+            meta: { usageType: 'normal_component' }
+          }
+        };
+      }
+    },
+    meta: { usageType: 'normal_service' }
+  }]
+};
+```
+
+## 认证状态管理
+
+### 创建认证 Hook
+
+```typescript
+import { useState, useEffect } from 'react';
+
+interface User {
+  _id: string;
+  username: string;
+  email: string;
+  createdAt: Date;
+  roles?: string[];
+}
+
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(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');
+      }
+    })
+    .finally(() => {
+      setLoading(false);
+    });
+  }, []);
+  
+  const login = async (identifier: string, password: string) => {
+    const response = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ identifier, password })
+    });
+    
+    const result = await response.json();
+    
+    if (result.success) {
+      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
+  };
+}
+```
+
+## 最佳实践
+
+### 1. Token 存储
+- 使用 `localStorage` 或 `cookie` 存储 token
+- 考虑安全性时优先使用 `httpOnly` cookie
+- 实现 token 自动刷新机制
+
+### 2. 错误处理
+- 捕获并处理认证相关的错误
+- 提供用户友好的错误消息
+- 记录详细的错误日志用于调试
+
+### 3. 安全性
+- 始终在服务端验证 token
+- 不要在客户端存储敏感信息
+- 使用强密码策略
+- 考虑实现两步验证增强安全性
+
+### 4. 用户体验
+- 记住用户的登录状态
+- 自动续期 token 避免频繁登录
+- 在 token 过期时友好提示用户
+
+## 故障排除
+
+### 常见问题
+
+1. **Token 无法验证**
+   - 检查 JWT_SECRET 是否正确配置
+   - 确认 token 未过期
+   - 验证 token 格式是否正确
+
+2. **用户无法登录**
+   - 检查用户名/邮箱和密码是否正确
+   - 确认用户账户已激活
+   - 检查数据库连接是否正常
+
+3. **中间件无法获取用户信息** 
+   - 确认 token 在请求头中正确传递
+   - 检查 verifyToken 函数是否正常工作
+   - 验证 getUserById 是否能找到对应用户

package/examples/blog-plugin/README.md

@@ -306,6 +306,9 @@ npx @linyjs/cli validate *.mpk
 - 🔧 [API 参考](../../docs/api-reference/server-interface.md)
 - 📚 [服务端模块指南](../../docs/guides/server-module.md)
 - 🎨 [客户端模块指南](../../docs/guides/client-module.md)
+- 💾 [数据持久化](../../docs/guides/data-persistence.md) - 使用 MongoDB 模块
+- 🔐 [用户认证](../../docs/guides/authentication.md) - 使用 Auth 模块  
+- 🛡️ [权限管理](../../docs/guides/permissions.md) - 使用 Permission 模块
 
 ## 许可证
 

package/package.json

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