@linyjs/plugin-docs 0.0.13

package/docs/getting-started/quick-start.md

@@ -0,0 +1,235 @@
+# 快速开始
+
+## 📖 导航目录
+
+- [快速开始](./quick-start.md) - 本文档
+- [安装指南](./installation.md) - 详细安装说明
+- [第一个插件教程](./first-plugin.md) - 深入学习插件开发
+
+## 相关文档
+
+- [服务端模块开发](../guides/server-module.md)
+- [客户端模块开发](../guides/client-module.md)
+- [创建示例项目](../../examples/hello-world/)
+
+## 5分钟创建你的第一个 linyjs 插件
+
+本教程将带你从零开始,在5分钟内创建一个简单的 "Hello World" 插件。
+
+### 前置要求
+
+- Node.js >= 18.0
+- npm 或 yarn
+- 基本的 TypeScript 和 React 知识
+
+### 步骤 1: 初始化项目
+
+**推荐方式：使用 CLI 工具自动创建项目**
+
+```bash
+# 使用 @linyjs/cli 创建项目目录和基本文件
+npx @linyjs/cli init hello-plugin
+cd hello-plugin
+
+# 安装依赖
+npm install
+```
+
+CLI 工具会自动创建：
+- package.json (已配置依赖和脚本)
+- tsconfig.json (TypeScript 配置)  
+- src/server/index.ts (服务端代码模板)
+- src/client/index.tsx (客户端代码模板)
+
+**传统方式：手动创建项目**
+
+```bash
+# 创建项目目录
+mkdir hello-plugin && cd hello-plugin
+
+# 初始化 npm 项目
+npm init -y
+
+# 安装依赖
+npm install @linyjs/server-module-interface @linyjs/client-module-interface react
+npm install -D typescript @types/react
+```
+
+### 步骤 2: 项目结构
+
+使用 CLI 工具创建的项目已经包含了完整的文件结构：
+
+```
+hello-plugin/
+├── package.json          # 已预配置的依赖和脚本
+├── tsconfig.json         # 已配置 TypeScript 
+└── src/
+    ├── server/
+    │   └── index.ts      # 服务端入口 (已包含示例代码)
+    └── client/
+        └── index.tsx     # 客户端入口 (已包含示例代码)
+```
+
+**注意**：使用 CLI 创建的项目已经包含了预配置的 package.json 和 tsconfig.json，无需手动创建。
+
+如果你使用了传统方式，需要**手动创建 tsconfig.json:**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+### 步骤 3: 编写服务端代码
+
+**使用 CLI 创建的项目已经包含了示例代码**，你已经可以开始开发或修改现有代码。
+
+如果你需要自定义或创建新的服务端代码，编辑 `src/server/index.ts`:
+
+```typescript
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+
+class HelloController {
+  getRoutes() {
+    return [{
+      method: 'GET' as const,
+      path: '/api/hello',
+      middlewares: [],
+      responseType: 'json' as const,
+      handler: async () => {
+        return { message: 'Hello from plugin!' };
+      }
+    }];
+  }
+}
+
+const helloControllerDef: IServiceDef = {
+  serviceTag: 'helloController',
+  serviceImpl: HelloController,
+  meta: { usageType: 'controller' }
+};
+
+export const helloServerModule: IModule = {
+  name: 'helloServer',
+  serviceDefs: [helloControllerDef]
+};
+```
+
+### 步骤 4: 编写客户端代码
+
+**使用 CLI 创建的项目已经包含了示例代码**，你已经可以开始开发或修改现有代码。
+
+如果你需要自定义或创建新的客户端代码，编辑 `src/client/index.tsx`:
+
+```typescript
+import type { IModule, IServiceDef } from '@linyjs/client-module-interface';
+import React from 'react';
+
+function HelloPage() {
+  return (
+    <div style={{ padding: '20px' }}>
+      <h1>Hello from Plugin!</h1>
+      <p>This is your first linyjs plugin.</p>
+    </div>
+  );
+}
+
+class HelloRouteService {
+  basePath = '/hello';
+  getRoutes() {
+    return [{
+      path: '/',
+      component: HelloPage,
+      key: 'hello-page',
+      meta: { title: 'Hello' }
+    }];
+  }
+}
+
+const helloRouteDef: IServiceDef = {
+  serviceTag: 'helloRoute',
+  serviceImpl: HelloRouteService,
+  meta: { usageType: 'route' }
+};
+
+export const helloClientModule: IModule = {
+  name: 'helloClient',
+  serviceDefs: [helloRouteDef]
+};
+```
+
+### 步骤 5: 构建和打包
+
+**推荐方式：使用开发模式 (dev)**
+
+```bash
+# 一键打包、安装到开发环境
+npx @linyjs/cli dev
+```
+
+这会：
+1. 自动编译 TypeScript
+2. 打包为 .mpk 文件
+3. 安装到 SSR 的 extensions 目录
+4. 注册到 packages.json
+5. 准备就绪后重启 SSR 服务器即可测试
+
+**传统方式：手动打包**
+
+```bash
+# 编译 TypeScript
+npm run build
+
+# 使用 CLI 打包为 .mpk 文件
+npx @linyjs/cli pack
+```
+
+你会得到 `hello-plugin.mpk` 文件!
+
+### 步骤 6: 测试插件
+
+**使用 CLI dev 模式**（已自动完成安装和注册）:
+
+```bash
+# 启动 SSR 服务器
+cd /path/to/linyjs/packages/ssr
+npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+访问 `http://localhost:3000/hello` 查看你的插件!
+
+**手动部署**:
+
+```bash
+# 将插件复制到 extensions 目录
+cp hello-plugin.mpk /path/to/linyjs/packages/ssr/extensions/
+
+# 启动 SSR 服务器
+cd /path/to/linyjs/packages/ssr
+npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+访问 `http://localhost:3000/hello` 查看你的插件!
+
+### 下一步
+
+- 📖 阅读 [安装指南](./installation.md) 了解详细的安装步骤
+- 🎯 查看 [第一个插件教程](./first-plugin.md) 深入学习插件开发
+- 💡 浏览 [示例项目](../../examples/) 获取完整代码参考
+
+---
+
+**上一篇**: [返回目录](../README.md) | **下一篇**: [安装指南](./installation.md)

package/docs/guides/authentication.md

@@ -0,0 +1,428 @@
+# 用户认证
+
+本指南介绍如何在 linyjs 插件中使用认证系统实现用户登录、注册和权限验证。
+
+## 概述
+
+linyjs 提供完整的用户认证系统，支持:
+
+- 🔐 用户注册和登录
+- 🪙 JWT Token 认证
+- 🛡️ 路由级别的认证保护
+- 👤 用户信息管理
+
+## 配置认证服务
+
+### 在服务端模块中注入依赖
+
+```typescript
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+import { login, register, verifyToken } from '@linyjs/auth';
+
+class AuthController {
+  // ... 控制器实现
+}
+
+const authControllerDef: IServiceDef = {
+  serviceTag: 'authController',
+  serviceImpl: AuthController,
+  dependencies: [],
+  meta: { usageType: 'controller' }
+};
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['auth'],
+  serviceDefs: [authControllerDef]
+};
+```
+
+## 基本认证操作
+
+### 用户注册
+
+```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>
+  );
+}
+
+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
+
+```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 是否能找到对应用户