@linyjs/plugin-docs 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @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
+# 生成 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 # 数据持久化
+├── api-reference/        # API参考
+│   ├── server-interface.md
+│   ├── client-interface.md
+│   └── ui-slots-interface.md
+├── best-practices/       # 最佳实践
+│   ├── naming-conventions.md
+│   ├── 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 框架](https://github.com/linyjs/linyjs)
+- [CLI 工具文档](https://github.com/linyjs/linyjs/tree/main/packages/cli)
+- [报告文档问题](https://github.com/linyjs/linyjs/issues)
+
+## 📄 许可证
+
+MIT License

package/docs/api-reference/index.md

@@ -0,0 +1,341 @@
+# 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;
+  }
+}
+```
+
+---
+
+## 相关文档
+
+- 📖 [服务端模块开发](../guides/server-module.md)
+- 💻 [客户端模块开发](../guides/client-module.md)
+- 🎨 [UI 扩展插槽](../guides/ui-slots.md)
+
+---
+
+**返回**: [文档首页](../README.md)