@linyjs/plugin-docs 0.0.13

package/README.md

@@ -0,0 +1,137 @@
+# @linyjs/plugin-docs
+
+**适用于 linyjs v0.x**
+
+查看其他版本: [v1.x](link) | [v2.x](link)
+
+## 📖 简介
+
+`@linyjs/plugin-docs` 是 linyjs 框架的官方插件开发文档和示例包,提供:
+
+- ✅ **结构化文档** - 从入门到进阶的完整教程
+- ✅ **可运行示例** - 3个完整的插件示例项目
+- ✅ **API参考** - 详细的接口文档和类型定义
+- ✅ **最佳实践** - 行业标准的开发规范
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+npm install @linyjs/plugin-docs
+```
+
+### 访问文档
+
+文档位于 `node_modules/@linyjs/plugin-docs/docs/` 目录:
+
+```bash
+# 查看入门教程
+cat node_modules/@linyjs/plugin-docs/docs/getting-started/quick-start.md
+
+# 查看API参考
+ls node_modules/@linyjs/plugin-docs/docs/api-reference/
+```
+
+### 快速创建插件项目
+
+使用 CLI 工具创建新的插件项目:
+
+```bash
+# 创建新的插件项目
+npx @linyjs/cli init my-plugin
+cd my-plugin
+npm install
+
+# 进入开发模式
+npx @linyjs/cli dev
+```
+
+CLI 工具会自动创建完整的项目结构，包含 package.json、TypeScript 配置和示例代码。
+
+### 生成示例项目
+
+使用 CLI 工具生成示例项目:
+
+```bash
+# 生成 Hello World 示例
+npx @linyjs/cli example hello-world
+
+# 生成博客插件示例
+npx @linyjs/cli example blog-plugin -o ./my-blog
+```
+
+## 📚 文档结构
+
+```
+docs/
+├── getting-started/      # 入门教程
+│   ├── quick-start.md    # 快速开始
+│   ├── installation.md   # 安装指南
+│   └── first-plugin.md   # 第一个插件
+├── guides/               # 进阶指南
+│   ├── server-module.md  # 服务端模块
+│   ├── client-module.md  # 客户端模块
+│   ├── ui-slots.md       # UI扩展插槽
+│   ├── permissions.md    # 权限管理
+│   ├── data-persistence.md # 数据持久化
+│   └── authentication.md # 用户认证
+├── api-reference/        # API参考
+│   ├── server-interface.md
+│   ├── client-interface.md
+│   └── ui-slots-interface.md
+├── best-practices/       # 最佳实践
+│   ├── naming-conventions.md
+│   ├── service-definition.md  # ServiceDef 代码风格规范
+│   ├── error-handling.md
+│   ├── performance.md
+│   └── security.md
+└── faq.md                # 常见问题
+```
+
+## 💡 示例项目
+
+```
+examples/
+├── hello-world/          # 最简示例(一个API + 一个页面)
+├── blog-plugin/          # 完整博客插件(CRUD + 权限)
+└── analytics-plugin/     # 数据分析插件(定时任务 + 可视化)
+```
+
+每个示例都是完整的、可独立运行的插件项目,包含:
+- 完整的 TypeScript 代码
+- package.json 和 tsconfig.json 配置
+- 详细的 README 说明
+- 可直接打包为 .mpk 文件
+
+## 🔧 核心模块
+
+linyjs 提供了以下核心模块，插件可以通过依赖注入方式调用这些基础服务：
+
+### @linyjs/mdb
+**MongoDB 数据库服务**
+- 提供数据持久化存储
+- 支持 CRUD 操作和复杂查询
+- 详情：[数据持久化指南](./docs/guides/data-persistence.md)
+
+### @linyjs/auth  
+**用户认证系统**
+- 支持用户注册、登录、Token 验证
+- 提供 JWT 身份验证
+- 详情：[认证指南](./docs/guides/authentication.md)
+
+### @linyjs/permission
+**权限管理系统**  
+- 基于角色的访问控制(RBAC)
+- 细粒度的权限定义
+- 详情：[权限管理指南](./docs/guides/permissions.md)
+
+## 📖 核心模块指南
+
+- 💾 [数据持久化](./docs/guides/data-persistence.md) - 使用 @linyjs/mdb
+- 🔐 [用户认证](./docs/guides/authentication.md) - 使用 @linyjs/auth
+- 🛡️ [权限管理](./docs/guides/permissions.md) - 使用 @linyjs/permission
+
+## 📄 许可证
+
+MIT License

package/docs/api-reference/index.md

@@ -0,0 +1,361 @@
+# API 参考
+
+本章节提供 linyjs 框架核心接口的详细文档。
+
+## 服务端接口
+
+### IModule
+
+服务端模块的基础接口。
+
+```typescript
+interface IModule {
+  name: string;
+  moduleDependencies?: string[];
+  serviceDefs: IServiceDef[];
+}
+```
+
+**字段说明:**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | ✅ | 模块唯一标识符 |
+| `moduleDependencies` | string[] | ❌ | 依赖的其他模块 |
+| `serviceDefs` | IServiceDef[] | ✅ | 服务定义列表 |
+
+**示例:**
+
+```typescript
+export const myModule: IModule = {
+  name: 'myModule',
+  moduleDependencies: ['logger'],
+  serviceDefs: [/* ... */]
+};
+```
+
+---
+
+### IServiceDef
+
+服务定义的通用接口。
+
+```typescript
+interface IServiceDef {
+  serviceTag: string;
+  serviceImpl: any;
+  dependencies?: string[];
+  meta: ServiceMetadata;
+}
+```
+
+**字段说明:**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `serviceTag` | string | ✅ | 服务的唯一标签 |
+| `serviceImpl` | class | ✅ | 服务实现类 |
+| `dependencies` | string[] | ❌ | 依赖的其他服务 |
+| `meta` | ServiceMetadata | ✅ | 元数据(包含 usageType) |
+
+---
+
+### IControllerService
+
+控制器服务接口,用于定义 API 路由。
+
+```typescript
+interface IControllerService {
+  getRoutes(): IRouteDefinition[];
+}
+```
+
+**方法:**
+
+- `getRoutes()` - 返回路由定义数组
+
+**示例:**
+
+详见 [服务端模块开发](../guides/server-module.md#控制器controller)
+
+---
+
+### IMiddlewareService
+
+中间件服务接口。
+
+```typescript
+interface IMiddlewareService {
+  getMiddlewares(): IMiddlewareDefinition[];
+}
+```
+
+**示例:**
+
+详见 [服务端模块开发](../guides/server-module.md#中间件middleware)
+
+---
+
+### ICronService
+
+定时任务服务接口。
+
+```typescript
+interface ICronService {
+  getCronJobs(): ICronJobDefinition[];
+}
+```
+
+**示例:**
+
+详见 [服务端模块开发](../guides/server-module.md#定时任务cron)
+
+---
+
+## 客户端接口
+
+### IModule (Client)
+
+客户端模块的基础接口。
+
+```typescript
+interface IModule {
+  name: string;
+  serviceDefs: IServiceDef[];
+}
+```
+
+---
+
+### IRouteService
+
+路由服务接口,用于定义客户端路由。
+
+```typescript
+interface IRouteService {
+  basePath?: string;
+  getRoutes(): IClientRouteDefinition[];
+}
+```
+
+**字段说明:**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `basePath` | string | ❌ | 路由前缀 |
+| `getRoutes()` | method | ✅ | 返回路由定义数组 |
+
+**示例:**
+
+```typescript
+class MyRouteService implements IRouteService {
+  basePath = '/my';
+  
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: MyPage,
+        key: 'my-page',
+        meta: { title: 'My Page' }
+      }
+    ];
+  }
+}
+```
+
+---
+
+### IGlobalStateService
+
+全局状态服务接口。
+
+```typescript
+interface IGlobalStateService {
+  atoms: Record<string, any>;
+}
+```
+
+**示例:**
+
+```typescript
+import { atom } from 'jotai';
+
+class MyStateService implements IGlobalStateService {
+  atoms = {
+    myState: atom({ items: [] }),
+    selectedItem: atom(null)
+  };
+}
+```
+
+---
+
+### IComponentListService
+
+组件注册服务接口。
+
+```typescript
+interface IComponentListService {
+  components: Record<string, React.ComponentType>;
+}
+```
+
+**示例:**
+
+```typescript
+class MyComponentService implements IComponentListService {
+  components = {
+    MyButton,
+    MyCard
+  };
+}
+```
+
+---
+
+### IHooksService
+
+Hooks 注册服务接口。
+
+```typescript
+interface IHooksService {
+  hooks: Record<string, Function>;
+}
+```
+
+**示例:**
+
+```typescript
+class MyHooksService implements IHooksService {
+  hooks = {
+    useMyData
+  };
+}
+```
+
+---
+
+## UI 插槽接口
+
+### ISlotComponent
+
+UI 扩展插槽组件接口。
+
+```typescript
+interface ISlotComponent {
+  id: string;
+  position: SlotPosition;
+  component: React.ComponentType;
+  priority?: number;
+  packageName?: string;
+  shouldRender?: (context: SlotContext) => boolean;
+}
+```
+
+**字段说明:**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | ✅ | 插槽组件唯一ID |
+| `position` | string | ✅ | 插槽位置 |
+| `component` | React.Component | ✅ | React 组件 |
+| `priority` | number | ❌ | 优先级(0-100+) |
+| `packageName` | string | ❌ | 包名称 |
+| `shouldRender` | function | ❌ | 条件渲染函数 |
+
+**可用插槽位置:**
+
+- `admin-sidebar` - 管理后台侧边栏
+- `admin-header` - 管理后台顶部导航
+- `admin-dashboard` - 管理后台仪表盘
+- `personal-dashboard` - 个人仪表盘
+- `plugin-marketplace` - 插件市场
+
+**示例:**
+
+```typescript
+registry.register({
+  id: 'analytics-menu',
+  position: 'admin-sidebar',
+  component: AnalyticsMenu,
+  priority: 50,
+  shouldRender: (context) => {
+    return context.user?.roles?.includes('admin');
+  }
+});
+```
+
+---
+
+## 响应类型
+
+### JSON Response
+
+```typescript
+{
+  responseType: 'json',
+  handler: async () => {
+    return { message: 'Hello' };
+  }
+}
+```
+
+### File Download
+
+```typescript
+{
+  responseType: 'file',
+  handler: async () => {
+    return {
+      filePath: '/path/to/file.pdf',
+      filename: 'document.pdf',
+      contentType: 'application/pdf'
+    };
+  }
+}
+```
+
+### Video Stream
+
+```typescript
+{
+  responseType: 'video_stream',
+  handler: async (params) => {
+    const stream = fs.createReadStream(`/videos/${params.id}.mp4`);
+    return stream;
+  }
+}
+```
+
+---
+
+## 基础模块
+
+linyjs 框架提供了以下基础模块，插件开发者可以通过依赖注入方式使用：
+
+### 数据库模块
+- **@linyjs/mdb** - 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#-核心模块)
+
+---
+
+**返回**: [文档首页](../README.md)