@linyjs/plugin-docs 0.0.13

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, IServiceDef } from '@linyjs/server-module-interface';
+import { ArticleController } from './controllers/ArticleController';
+
+const articleControllerDef: IServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  meta: { usageType: 'controller' }
+};
+
+export const blogServerModule: IModule = {
+  name: 'blogServer',
+  serviceDefs: [articleControllerDef]
+};
+```
+
+## 步骤 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' }
+      }
+    ];
+  }
+}
+
+const blogRouteDef: IServiceDef = {
+  serviceTag: 'blogRoute',
+  serviceImpl: BlogRouteService,
+  meta: { usageType: 'route' }
+};
+
+export const blogClientModule: IModule = {
+  name: 'blogClient',
+  serviceDefs: [blogRouteDef]
+};
+```
+
+## 步骤 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)

package/docs/getting-started/installation.md

@@ -0,0 +1,244 @@
+# 安装指南
+
+本指南将帮助你正确安装和配置 linyjs 框架及插件开发环境。
+
+## 前置要求
+
+在开始之前,请确保你的系统已安装以下软件:
+
+- **Node.js** >= 18.0 ([下载地址](https://nodejs.org/))
+- **npm** >= 9.0 (通常随 Node.js 一起安装)
+- **Git** (用于版本控制)
+
+### 验证安装
+
+```bash
+# 检查 Node.js 版本
+node --version
+# 应显示: v18.x.x 或更高
+
+# 检查 npm 版本
+npm --version
+# 应显示: 9.x.x 或更高
+
+# 检查 Git
+git --version
+```
+
+## 安装 linyjs 核心包
+
+linyjs 框架由多个 NPM 包组成。根据你的需求,可以选择性安装:
+
+### 1. 安装接口包(必需)
+
+这些包定义了插件开发的接口规范:
+
+```bash
+npm install @linyjs/server-module-interface
+npm install @linyjs/client-module-interface
+npm install @linyjs/ui-slots-interface
+```
+
+### 2. 安装 CLI 工具(推荐)
+
+CLI 工具提供零配置的插件打包功能:
+
+```bash
+# 全局安装
+npm install -g @linyjs/cli
+
+# 或在项目中使用
+npx @linyjs/cli <command>
+```
+
+### 3. 安装文档包(推荐)
+
+文档包包含完整的教程和示例:
+
+```bash
+npm install @linyjs/plugin-docs
+```
+
+安装后,文档位于 `node_modules/@linyjs/plugin-docs/docs/`。
+
+### 4. 安装其他可选包
+
+```bash
+# MongoDB 服务(数据持久化)
+npm install @linyjs/mdb
+
+# 权限管理
+npm install @linyjs/permission
+
+# 管理后台
+npm install @linyjs/admin
+```
+
+## 初始化插件项目
+
+### 方法 1: 使用 CLI 工具(推荐)
+
+```bash
+# 创建新项目
+npx @linyjs/cli init my-plugin
+
+# 进入项目目录
+cd my-plugin
+
+# 安装依赖
+npm install
+```
+
+### 方法 2: 手动创建
+
+```bash
+# 创建项目目录
+mkdir my-plugin && cd my-plugin
+
+# 初始化 npm
+npm init -y
+
+# 安装依赖
+npm install @linyjs/server-module-interface @linyjs/client-module-interface react
+npm install -D typescript @types/react
+
+# 创建 TypeScript 配置
+cat > tsconfig.json << 'EOF'
+{
+  "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/**/*"]
+}
+EOF
+
+# 创建目录结构
+mkdir -p src/{server,client}
+```
+
+## 配置开发环境
+
+### VS Code 推荐扩展
+
+- **TypeScript and JavaScript Language Features** (内置)
+- **ESLint** - 代码质量检查
+- **Prettier** - 代码格式化
+- **React Developer Tools** - React 调试
+
+### ESLint 配置(可选)
+
+```bash
+npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
+```
+
+创建 `.eslintrc.json`:
+
+```json
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "warn"
+  }
+}
+```
+
+## 验证安装
+
+创建一个简单的测试文件来验证安装是否正确:
+
+**src/server/test.ts:**
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+console.log('✓ Server module interface imported successfully');
+
+export const testModule: IModule = {
+  name: 'test',
+  serviceDefs: []
+};
+```
+
+**src/client/test.tsx:**
+
+```typescript
+import type { IModule } from '@linyjs/client-module-interface';
+import React from 'react';
+
+console.log('✓ Client module interface imported successfully');
+
+export const testModule: IModule = {
+  name: 'test',
+  serviceDefs: []
+};
+```
+
+编译测试:
+
+```bash
+npx tsc
+```
+
+如果编译成功且无错误,说明安装正确!
+
+## 常见问题
+
+### Q: 安装时遇到权限错误?
+
+**A:** 尝试使用 `sudo`(macOS/Linux)或以管理员身份运行命令提示符(Windows):
+
+```bash
+sudo npm install -g @linyjs/cli
+```
+
+或者配置 npm 使用用户目录:
+
+```bash
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Q: TypeScript 编译错误?
+
+**A:** 确保安装了正确的 TypeScript 版本:
+
+```bash
+npm install -D typescript@^5.7.0
+```
+
+### Q: 如何更新到最新版本?
+
+**A:** 使用 npm update:
+
+```bash
+npm update @linyjs/server-module-interface
+npm update @linyjs/client-module-interface
+npm update @linyjs/cli
+```
+
+## 下一步
+
+- 🎯 阅读 [快速开始](./quick-start.md) 创建你的第一个插件
+- 📖 查看 [第一个插件教程](./first-plugin.md) 深入学习
+- 💡 浏览 [示例项目](../../examples/) 获取完整代码参考
+
+---
+
+**上一篇**: [快速开始](./quick-start.md) | **下一篇**: [第一个插件教程](./first-plugin.md)