@linyjs/plugin-docs 0.1.0

package/docs/faq.md

@@ -0,0 +1,323 @@
+# 常见问题 (FAQ)
+
+## 入门相关
+
+### Q1: linyjs 是什么?
+
+**A:** linyjs 是一个插件式的前后端应用平台,允许开发者通过创建 `.mpk` 格式的插件来扩展平台功能。它提供了完整的前后端开发框架,包括依赖注入、权限控制、UI扩展等特性。
+
+### Q2: 我需要哪些前置知识?
+
+**A:** 
+- TypeScript (必需)
+- React (客户端开发)
+- Node.js (服务端开发)
+- 基本的 HTTP/API 概念
+
+### Q3: 如何开始第一个插件?
+
+**A:** 阅读 [快速开始](./getting-started/quick-start.md) 教程,5分钟即可创建你的第一个插件!
+
+---
+
+## 安装和配置
+
+### Q4: 如何安装 linyjs CLI 工具?
+
+**A:** 
+```bash
+# 全局安装(推荐)
+npm install -g @linyjs/cli
+
+# 或使用 npx
+npx @linyjs/cli <command>
+```
+
+### Q5: TypeScript 编译错误怎么办?
+
+**A:** 确保:
+1. 安装了正确版本的 TypeScript (`^5.7.0`)
+2. `tsconfig.json` 配置正确
+3. 所有类型定义包已安装 (`@types/react` 等)
+
+### Q6: 如何更新到最新版本?
+
+**A:** 
+```bash
+npm update @linyjs/server-module-interface
+npm update @linyjs/client-module-interface
+npm update @linyjs/cli
+```
+
+---
+
+## 开发相关
+
+### Q7: 如何调试插件?
+
+**A:** 
+
+**方法 1: 使用 tsx 运行**
+```bash
+npx tsx src/server/index.ts
+```
+
+**方法 2: 添加日志**
+```typescript
+console.log('[MyPlugin]', 'Debug info:', data);
+```
+
+**方法 3: 浏览器 DevTools**
+客户端代码可以在浏览器中调试。
+
+### Q8: 插件之间如何通信?
+
+**A:** 
+
+**方式 1: 通过共享服务**
+```typescript
+// 插件 A 提供服务
+export const serviceA = {
+  serviceTag: 'sharedService',
+  serviceImpl: SharedService
+};
+
+// 插件 B 使用服务
+export const serviceB = {
+  serviceTag: 'consumer',
+  serviceImpl: ConsumerService,
+  dependencies: ['pluginA.sharedService']
+};
+```
+
+**方式 2: 通过全局状态**
+使用 jotai atoms 共享状态。
+
+### Q9: 如何处理插件版本兼容性?
+
+**A:** 在 `manifest.json` 中指定依赖版本:
+```json
+{
+  "dependencies": {
+    "core-auth": "^1.0.0",
+    "core-mongodb": ">=1.2.0"
+  }
+}
+```
+
+### Q10: 插件可以修改其他插件的行为吗?
+
+**A:** 可以通过以下方式:
+1. **覆盖路由**: 注册相同路径的路由(后加载的优先)
+2. **扩展 Slot**: 向现有 Slot 添加新组件
+3. **装饰器模式**: 包装其他插件的服务
+
+---
+
+## 打包和发布
+
+### Q11: 如何打包插件?
+
+**A:** 使用 CLI 工具:
+```bash
+cd my-plugin
+npx @linyjs/cli pack
+```
+
+这将自动完成:构建、生成 manifest、验证结构、打包压缩。
+
+### Q12: .mpk 文件是什么格式?
+
+**A:** `.mpk` 是 ZIP 压缩格式,包含:
+```
+my-plugin.mpk (ZIP)
+├── manifest.json       # 插件清单
+├── server/             # 服务端模块
+│   └── index.js        # 编译后的 JS
+├── client/             # 客户端模块
+│   └── index.js        # 编译后的 JS
+└── assets/             # 静态资源
+```
+
+### Q13: 如何测试插件?
+
+**A:** 
+```bash
+# 将插件复制到 extensions 目录
+cp my-plugin.mpk /path/to/linyjs/packages/ssr/extensions/
+
+# 启动 SSR 服务器
+cd /path/to/linyjs/packages/ssr
+npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+---
+
+## 高级主题
+
+### Q14: 为什么我的插件无法访问 React Context?
+
+**A:** 这通常是因为 React 实例不共享导致的。确保:
+1. CLI 已 external React(默认行为)
+2. 宿主应用提供了 React(通过 Import Map)
+3. 所有插件使用同一个 React 版本
+
+```html
+<!-- 宿主应用的 HTML -->
+<script type="importmap">
+{
+  "imports": {
+    "react": "/vendor/react.production.min.js",
+    "react-dom": "/vendor/react-dom.production.min.js"
+  }
+}
+</script>
+```
+
+### Q15: CLI 打包的 Bundle 体积太大怎么办?
+
+**A:** CLI 默认启用了优化:
+- ✅ esbuild - 极速构建和小体积
+- ✅ Minification - 代码压缩
+- ✅ Tree Shaking - 移除未使用代码
+- ✅ External Dependencies - React 等由宿主提供
+
+进一步优化:
+```typescript
+// 使用懒加载
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'))
+
+// 代码分割
+import('./module').then(module => {
+  // 动态导入
+})
+```
+
+### Q16: 如何处理插件卸载?
+
+**A:** 建议在插件中提供清理逻辑:
+```typescript
+export function onUninstall() {
+  // 清理数据
+  db.collection('my_data').deleteMany({ plugin: 'my-plugin' });
+}
+```
+
+### Q17: 插件可以访问环境变量吗?
+
+**A:** 可以,通过 `process.env`:
+```typescript
+const apiKey = process.env.MY_PLUGIN_API_KEY;
+```
+
+确保在 `.env` 文件中配置:
+```bash
+MY_PLUGIN_API_KEY=your-api-key
+```
+
+---
+
+## 性能和优化
+
+### Q18: 如何优化插件性能?
+
+**A:** 
+1. **懒加载组件**
+```typescript
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+```
+
+2. **避免不必要的重渲染**
+```typescript
+import { memo } from 'react';
+const ExpensiveComponent = memo(({ data }) => {
+  return <div>{/* ... */}</div>;
+});
+```
+
+3. **使用缓存**
+```typescript
+const cachedData = useMemo(() => expensiveCalculation(data), [data]);
+```
+
+### Q19: 如何减少 Bundle 大小?
+
+**A:** 
+- 使用 tree shaking(确保使用 ES modules)
+- External 大型依赖(如 lodash)
+- 代码分割和懒加载
+- 压缩图片等资源
+
+---
+
+## 安全性
+
+### Q20: 如何防止 XSS 攻击?
+
+**A:** 
+```typescript
+function SafeDisplay({ content }: { content: string }) {
+  // 转义 HTML
+  const escaped = escapeHtml(content);
+  return <div dangerouslySetInnerHTML={{ __html: escaped }} />;
+}
+```
+
+### Q21: 如何防止 SQL 注入?
+
+**A:** 使用参数化查询:
+```typescript
+// ❌ 不安全
+const user = await db.collection('users').findOne({ 
+  email: userInput  // 可能被注入
+});
+
+// ✅ 安全(使用 MongoDB 的参数化查询)
+const user = await db.collection('users').findOne({ 
+  email: userInput  // MongoDB 会自动处理
+});
+```
+
+### Q22: 如何验证用户输入?
+
+**A:** 
+```typescript
+handler: async (params) => {
+  const { email } = params.body;
+  
+  // 验证邮箱格式
+  if (!isValidEmail(email)) {
+    return {
+      status: 400,
+      data: { error: 'Invalid email format' }
+    };
+  }
+}
+```
+
+---
+
+## 获取帮助
+
+### Q23: 遇到问题怎么办?
+
+**A:** 
+1. 📖 查阅本文档和相关指南
+2. 💡 查看[示例项目](../examples/)
+3. 🔍 搜索 GitHub Issues
+4. 💬 在社区论坛提问
+5. 🐛 报告 Bug: [GitHub Issues](https://github.com/linyjs/linyjs/issues)
+
+### Q24: 如何贡献文档?
+
+**A:** 
+1. Fork 仓库
+2. 修改或添加文档
+3. 提交 Pull Request
+4. 等待审查和合并
+
+详见 [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+---
+
+**返回**: [文档首页](../README.md)

package/docs/getting-started/first-plugin.md

@@ -0,0 +1,358 @@
+# 第一个插件教程
+
+在本教程中,我们将创建一个完整的博客插件,包含文章的增删改查(CRUD)功能。
+
+## 学习目标
+
+完成本教程后,你将能够:
+
+- ✅ 创建服务端 API 控制器
+- ✅ 创建客户端 React 页面
+- ✅ 实现数据持久化(使用内存存储模拟)
+- ✅ 理解插件的完整工作流程
+
+## 项目结构
+
+最终的项目结构如下:
+
+```
+my-blog-plugin/
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── server/
+    │   └── index.ts          # 服务端模块
+    └── client/
+        ├── index.tsx         # 客户端模块
+        ├── pages/
+        │   ├── ArticleList.tsx
+        │   └── ArticleDetail.tsx
+        └── components/
+            └── ArticleCard.tsx
+```
+
+## 步骤 1: 初始化项目
+
+```bash
+mkdir my-blog-plugin && cd my-blog-plugin
+npm init -y
+npm install @linyjs/server-module-interface @linyjs/client-module-interface react
+npm install -D typescript @types/react
+```
+
+创建 `tsconfig.json`(参考[安装指南](./installation.md))。
+
+## 步骤 2: 定义数据类型
+
+创建 `src/shared/types.ts`:
+
+```typescript
+export interface Article {
+  id: number;
+  title: string;
+  content: string;
+  author: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ArticleListResponse {
+  data: Article[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+```
+
+## 步骤 3: 创建服务端代码
+
+### 3.1 文章服务
+
+创建 `src/server/services/ArticleService.ts`:
+
+```typescript
+import type { Article } from '../../shared/types';
+
+export class ArticleService {
+  private articles: Article[] = [];
+  private nextId = 1;
+
+  async getArticles(page = 1, limit = 10) {
+    const skip = (page - 1) * limit;
+    const total = this.articles.length;
+    const items = this.articles.slice(skip, skip + limit);
+    
+    return {
+      data: items,
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit)
+    };
+  }
+
+  async getArticleById(id: number): Promise<Article> {
+    const article = this.articles.find(a => a.id === id);
+    if (!article) {
+      throw new Error('Article not found');
+    }
+    return article;
+  }
+
+  async createArticle(data: Partial<Article>): Promise<Article> {
+    const article: Article = {
+      id: this.nextId++,
+      title: data.title || 'Untitled',
+      content: data.content || '',
+      author: data.author || 'Anonymous',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+    
+    this.articles.push(article);
+    return article;
+  }
+
+  async updateArticle(id: number, data: Partial<Article>): Promise<Article> {
+    const index = this.articles.findIndex(a => a.id === id);
+    if (index === -1) {
+      throw new Error('Article not found');
+    }
+    
+    this.articles[index] = {
+      ...this.articles[index],
+      ...data,
+      updatedAt: new Date().toISOString()
+    };
+    
+    return this.articles[index];
+  }
+
+  async deleteArticle(id: number): Promise<void> {
+    const index = this.articles.findIndex(a => a.id === id);
+    if (index === -1) {
+      throw new Error('Article not found');
+    }
+    this.articles.splice(index, 1);
+  }
+}
+```
+
+### 3.2 文章控制器
+
+创建 `src/server/controllers/ArticleController.ts`:
+
+```typescript
+import type { IControllerService } from '@linyjs/server-module-interface';
+import { ArticleService } from '../services/ArticleService';
+
+export class ArticleController implements IControllerService {
+  private articleService: ArticleService;
+
+  constructor() {
+    this.articleService = new ArticleService();
+  }
+
+  getRoutes() {
+    return [
+      {
+        method: 'GET' as const,
+        path: '/api/articles',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async (params: any) => {
+          const page = parseInt(params.query?.page || '1');
+          const limit = parseInt(params.query?.limit || '10');
+          return await this.articleService.getArticles(page, limit);
+        }
+      },
+      {
+        method: 'POST' as const,
+        path: '/api/articles',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async (params: any) => {
+          const article = await this.articleService.createArticle(params.body);
+          return { success: true, data: article };
+        }
+      }
+      // 添加更多路由...
+    ];
+  }
+}
+```
+
+### 3.3 服务端模块入口
+
+创建 `src/server/index.ts`:
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+import { ArticleController } from './controllers/ArticleController';
+
+export const blogServerModule: IModule = {
+  name: 'blogServer',
+  serviceDefs: [
+    {
+      serviceTag: 'articleController',
+      serviceImpl: ArticleController,
+      meta: { usageType: 'controller' }
+    }
+  ]
+};
+```
+
+## 步骤 4: 创建客户端代码
+
+### 4.1 文章列表组件
+
+创建 `src/client/components/ArticleCard.tsx`:
+
+```typescript
+import React from 'react';
+import type { Article } from '../../shared/types';
+
+interface ArticleCardProps {
+  article: Article;
+  onClick?: () => void;
+}
+
+export function ArticleCard({ article, onClick }: ArticleCardProps) {
+  return (
+    <div 
+      style={{ 
+        border: '1px solid #ddd',
+        borderRadius: '8px',
+        padding: '16px',
+        marginBottom: '16px',
+        cursor: onClick ? 'pointer' : 'default'
+      }}
+      onClick={onClick}
+    >
+      <h3 style={{ margin: '0 0 8px 0' }}>{article.title}</h3>
+      <p style={{ color: '#666', margin: '0 0 8px 0' }}>
+        By {article.author} • {new Date(article.createdAt).toLocaleDateString()}
+      </p>
+      <p style={{ margin: 0 }}>{article.content.substring(0, 100)}...</p>
+    </div>
+  );
+}
+```
+
+### 4.2 文章列表页面
+
+创建 `src/client/pages/ArticleList.tsx`:
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import type { Article, ArticleListResponse } from '../../shared/types';
+import { ArticleCard } from '../components/ArticleCard';
+
+export function ArticleList() {
+  const [articles, setArticles] = useState<Article[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/articles')
+      .then(res => res.json())
+      .then((data: ArticleListResponse) => {
+        setArticles(data.data);
+        setLoading(false);
+      })
+      .catch(err => {
+        console.error('Failed to fetch articles:', err);
+        setLoading(false);
+      });
+  }, []);
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <h1>Blog Articles</h1>
+      {articles.length === 0 ? (
+        <p>No articles yet.</p>
+      ) : (
+        articles.map(article => (
+          <ArticleCard key={article.id} article={article} />
+        ))
+      )}
+    </div>
+  );
+}
+```
+
+### 4.3 客户端模块入口
+
+创建 `src/client/index.tsx`:
+
+```typescript
+import type { IModule } from '@linyjs/client-module-interface';
+import { ArticleList } from './pages/ArticleList';
+
+class BlogRouteService {
+  basePath = '/blog';
+  
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: ArticleList,
+        key: 'article-list',
+        meta: { title: 'Blog' }
+      }
+    ];
+  }
+}
+
+export const blogClientModule: IModule = {
+  name: 'blogClient',
+  serviceDefs: [
+    {
+      serviceTag: 'blogRoute',
+      serviceImpl: BlogRouteService,
+      meta: { usageType: 'route' }
+    }
+  ]
+};
+```
+
+## 步骤 5: 构建和测试
+
+```bash
+# 编译 TypeScript
+npx tsc
+
+# 打包为 .mpk
+npx @linyjs/cli pack
+
+# 测试插件
+cp my-blog-plugin.mpk /path/to/linyjs/packages/ssr/extensions/
+cd /path/to/linyjs/packages/ssr
+npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+访问 `http://localhost:3000/blog` 查看你的博客插件!
+
+## 扩展功能
+
+现在你已经有了基础框架,可以尝试添加:
+
+- 📝 文章详情页面
+- ✏️ 文章编辑功能
+- 🗑️ 文章删除功能
+- 🔍 文章搜索功能
+- 👤 用户认证和权限控制
+
+## 下一步
+
+- 📖 阅读 [服务端模块开发](../guides/server-module.md) 深入学习后端开发
+- 💻 阅读 [客户端模块开发](../guides/client-module.md) 学习前端开发
+- 💾 阅读 [数据持久化](../guides/data-persistence.md) 学习如何使用 MongoDB
+
+---
+
+**上一篇**: [安装指南](./installation.md) | **下一篇**: [服务端模块开发](../guides/server-module.md)