@linyjs/plugin-docs 0.0.13 → 0.0.14

package/docs/guides/server-module.md

@@ -73,34 +73,46 @@ method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
 
 ### 路由参数
 
+框架在调用 `handler` 时，会将 **URL 路径参数**、**查询字符串** 和 **请求体** 合并为一个 `params` 对象传入：
+
+```typescript
+// 框架内部实现（简化）：
+const params = { ...req.params, ...req.query, ...req.body }
+await route.handler(params, ctx)
+```
+
+因此在 handler 中可以直接从 `params` 上获取这三类数据，无需区分来源：
+
 ```typescript
-// 路径参数: /api/items/:id
+// 路径参数: GET /api/items/:id
 {
   path: '/api/items/:id',
   handler: async (params) => {
-    const id = params.id;  // 从 URL 获取
+    const id = params.id;  // ✅ 从 URL 路径获取
   }
 }
 
-// 查询参数: /api/items?page=1&limit=10
+// 查询参数: GET /api/items?page=1&limit=10
 {
   path: '/api/items',
   handler: async (params) => {
-    const page = params.query?.page;
-    const limit = params.query?.limit;
+    const page = params.page;   // ✅ 从查询字符串获取
+    const limit = params.limit; // ✅ 从查询字符串获取
   }
 }
 
-// 请求体: POST /api/items with JSON body
+// 请求体: POST /api/items with JSON body { "name": "..." }
 {
   method: 'POST',
   path: '/api/items',
   handler: async (params) => {
-    const { name, description } = params.body;
+    const { name, description } = params;  // ✅ 从请求体获取
   }
 }
 ```
 
+> 💡 **合并顺序**：`req.params` → `req.query` → `req.body`。如果三者存在同名字段，后者会覆盖前者。通常建议避免命名冲突。
+
 ### 响应类型
 
 框架支持三种响应类型:
@@ -244,7 +256,9 @@ export const cronDef = {
 
 ## 依赖注入
 
-服务之间可以通过依赖注入互相引用。
+服务之间可以通过依赖注入互相引用。框架采用**构造函数注入**模式，将依赖组装为一个对象传入构造函数。
+
+> 📖 **完整说明**：依赖注入的详细机制（包括跨模块引用、实例化流程、常见错误等）请阅读 [依赖注入机制](./dependency-injection.md)。
 
 ### 声明依赖
 
@@ -252,16 +266,27 @@ export const cronDef = {
 export const myServiceDef = {
   serviceTag: 'myService',
   serviceImpl: MyService,
-  dependencies: ['otherService'],  // 依赖其他服务
+  dependencies: ['otherService'],  // 依赖其他服务（模块内引用）
   meta: { usageType: 'normal_service' }
 };
 ```
 
+依赖引用支持两种格式：
+- **模块内引用**：`'serviceTag'`（不含点号）
+- **跨模块引用**：`'moduleName.serviceTag'`（如 `'mdb.mongoDBService'`）
+
 ### 使用依赖
 
+> ⚠️ **关键**：构造函数**必须使用解构赋值**接收依赖。框架传入的是 `{ serviceTag: instance }` 对象，而非单个服务实例。
+
 ```typescript
+// ✅ 正确：解构赋值
 class MyService {
-  constructor(private otherService: any) {}
+  private otherService: SomeService;
+
+  constructor({ otherService }: { otherService: SomeService }) {
+    this.otherService = otherService;
+  }
   
   async doSomething() {
     // 使用依赖的服务
@@ -269,6 +294,42 @@ class MyService {
     return result;
   }
 }
+
+// ❌ 错误：不解构，直接赋值
+class MyService {
+  constructor(deps: any) {
+    this.otherService = deps;  // deps 是 { otherService: <实例> }，不是实例本身
+  }
+}
+```
+
+### 跨模块依赖
+
+引用其他模块（如 mdb、auth）的服务时，需要：
+1. 在 `moduleDependencies` 中声明模块依赖
+2. 在 `dependencies` 中使用 `'moduleName.serviceTag'` 格式
+
+```typescript
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+class MyService {
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+}
+
+const myServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  dependencies: ['mdb.mongoDBService'],  // 跨模块引用
+  meta: { usageType: 'normal_service' }
+};
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['mdb'],  // 声明模块级依赖
+  serviceDefs: [myServiceDef]
+};
 ```
 
 ## 错误处理
@@ -294,7 +355,7 @@ handler: async (params, ctx) => {
 
 ```typescript
 handler: async (params, ctx) => {
-  if (!params.body.name) {
+  if (!params.name) {
     throw new Error('Name is required');  // 自动返回 400
   }
 }
@@ -326,8 +387,8 @@ interface CreateItemRequest {
   description?: string;
 }
 
-handler: async (params: { body: CreateItemRequest }) => {
-  const { name, description } = params.body;
+handler: async (params: CreateItemRequest) => {
+  const { name, description } = params;
 }
 ```
 
@@ -335,7 +396,7 @@ handler: async (params: { body: CreateItemRequest }) => {
 
 ```typescript
 handler: async (params) => {
-  const { email } = params.body;
+  const { email } = params;
   
   if (!isValidEmail(email)) {
     return {
@@ -350,11 +411,23 @@ handler: async (params) => {
 
 ```typescript
 class MyController {
-  constructor(private logger: any) {}
+  private logger: any;
+
+  constructor({ logger }: { logger: any }) {
+    this.logger = logger;
+  }
   
-  handler: async (params) => {
-    this.logger.info('Processing request...');
-    // ...
+  getRoutes() {
+    return [{
+      method: 'GET' as const,
+      path: '/api/items',
+      middlewares: [],
+      responseType: 'json' as const,
+      handler: async (params) => {
+        this.logger.info('Processing request...');
+        // ...
+      }
+    }];
   }
 }
 ```
@@ -368,6 +441,7 @@ class MyController {
 
 ## 下一步
 
+- 📖 阅读 [依赖注入机制](./dependency-injection.md) — 完整的 DI 机制说明
 - 💻 阅读 [客户端模块开发](./client-module.md)
 - 💾 阅读 [数据持久化](./data-persistence.md)
 - 🔒 阅读 [权限管理](./permissions.md)

package/docs/guides/shared-module-interface.md

@@ -0,0 +1,349 @@
+# @linyjs/shared-module-interface
+
+本指南介绍 `@linyjs/shared-module-interface` 包的用途和使用方法。
+
+## 概述
+
+`@linyjs/shared-module-interface` 是一个**纯类型包**，汇集了 linyjs 框架所有公共模块（mdb、auth、permission）的 TypeScript 接口和类型定义。
+
+### 为什么需要这个包？
+
+linyjs 插件作为独立的 npm 包或 git 仓库开发，通过依赖注入机制获取 `IMongoDBService` 等服务实例。但 TypeScript 编译器需要类型声明才能提供：
+
+- ✅ 构造函数参数的类型提示
+- ✅ 服务方法的自动补全
+- ✅ 编译时类型检查
+
+如果每个插件都单独安装 `@linyjs/mdb`、`@linyjs/auth` 等包来获取类型，会带来：
+
+- 📦 **包体积增大** — 插件打包了不需要的运行时代码
+- ⚠️ **版本冲突** — 插件与框架使用的模块版本不一致
+- 🔧 **配置冗余** — 每个插件都要在 `package.json` 中声明多个依赖
+
+`@linyjs/shared-module-interface` 通过**纯类型导出**解决这些问题——只提供类型声明，不包含任何运行时代码。
+
+## 安装
+
+在插件的 `package.json` 中添加为**开发依赖**：
+
+```json
+{
+  "devDependencies": {
+    "@linyjs/shared-module-interface": "^0.0.1"
+  }
+}
+```
+
+> ⚠️ 必须是 `devDependencies`，不是 `dependencies`。此包只包含 TypeScript 类型，编译后会被完全擦除，不应出现在运行时依赖中。
+
+## 使用方式
+
+### 导入类型
+
+所有导出都使用 `import type` 语法，确保编译后类型被完全擦除：
+
+```typescript
+import type { IMongoDBService, IUserService, IPermissionService } from '@linyjs/shared-module-interface';
+import type { ObjectId, Db, Collection, Document, Filter } from '@linyjs/shared-module-interface';
+```
+
+### 在依赖注入中使用
+
+结合 linyjs 的依赖注入机制，在构造函数中使用类型：
+
+```typescript
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+class ArticleService {
+  private mongoDBService: IMongoDBService;
+
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+
+  async getArticleById(id: string) {
+    const collection = this.mongoDBService.getCollection('articles');
+    // ✅ IMongoDBService 提供完整的类型提示
+    return await collection.findOne({
+      _id: new this.mongoDBService.ObjectId(id)
+    });
+  }
+}
+```
+
+> 📖 关于依赖注入机制的完整说明，请阅读 [依赖注入机制](./dependency-injection.md)。
+
+## 可用类型一览
+
+### mdb 模块类型
+
+| 类型 | 说明 | 运行时来源 |
+|------|------|------------|
+| `IMongoDBService` | MongoDB 服务接口 | `@linyjs/mdb` 模块通过 `mdb.mongoDBService` 注入 |
+| `ObjectId` | MongoDB ObjectId 类型 | mongodb 包（运行时通过 `service.ObjectId` 获取） |
+| `Db` | MongoDB 数据库实例类型 | mongodb 包 |
+| `Collection` | MongoDB 集合类型 | mongodb 包 |
+| `Document` | MongoDB 文档类型 | mongodb 包 |
+| `Filter` | 查询过滤器类型 | mongodb 包 |
+| `Sort` | 排序类型 | mongodb 包 |
+| `UpdateFilter` | 更新操作类型 | mongodb 包 |
+| `InsertOneResult` | 插入结果类型 | mongodb 包 |
+| `UpdateResult` | 更新结果类型 | mongodb 包 |
+| `DeleteResult` | 删除结果类型 | mongodb 包 |
+| ... | mongodb 包的全部类型 | mongodb 包 |
+
+#### IMongoDBService 接口
+
+```typescript
+interface IMongoDBService {
+  /** MongoDB ObjectId 构造器（运行时通过此属性获取，无需单独安装 mongodb） */
+  readonly ObjectId: typeof ObjectId;
+
+  /** 获取数据库实例 */
+  getDb(): Db;
+
+  /** 获取指定集合 */
+  getCollection<T extends Document = Document>(collectionName: string): Collection<T>;
+
+  /** 检查数据库连接状态 */
+  isConnected(): boolean;
+
+  /** 关闭数据库连接 */
+  close(): Promise<void>;
+}
+```
+
+### auth 模块类型
+
+| 类型 | 说明 |
+|------|------|
+| `IUserService` | 用户管理服务接口 |
+| `IAuthUser` | 完整用户信息（含密码哈希，仅内部使用） |
+| `ISafeUser` | 安全用户信息（不含密码哈希） |
+| `IJwtPayload` | JWT Payload 结构 |
+| `IAuthResult` | 认证结果（token + user） |
+| `IsRootUser` | 判断用户是否为 Root 角色的函数类型 |
+| `IsAdminUser` | 判断用户是否为 Admin 角色的函数类型 |
+
+#### IUserService 接口
+
+```typescript
+interface IUserService {
+  /** 获取所有用户列表（不含密码哈希） */
+  getAllUsers(): Promise<ISafeUser[]>;
+
+  /** 更新用户角色 */
+  updateUserRoles(userId: string, roles: string[]): Promise<ISafeUser | null>;
+}
+```
+
+> 依赖声明：`dependencies: ['authServer.userService']`
+
+### permission 模块类型
+
+| 类型 | 说明 |
+|------|------|
+| `IPermissionService` | 权限服务接口 |
+| `PermissionString` | 权限字符串格式（`resource:action`） |
+| `Role` | 用户角色类型 |
+| `IPermissionUser` | 权限模块使用的用户接口 |
+| `IPermissionPolicy` | 权限策略定义 |
+| `IPermissionCheckResult` | 权限检查结果 |
+
+#### IPermissionService 接口
+
+```typescript
+interface IPermissionService {
+  /** 检查用户是否有权限执行某个操作 */
+  check(
+    user: IPermissionUser | null,
+    permission: PermissionString,
+    context?: Record<string, any>
+  ): Promise<IPermissionCheckResult>;
+
+  /** 注册权限策略 */
+  registerPolicy(policy: IPermissionPolicy): void;
+
+  /** 批量检查权限 */
+  checkMany(
+    user: IPermissionUser | null,
+    permissions: PermissionString[],
+    context?: Record<string, any>
+  ): Promise<Record<PermissionString, IPermissionCheckResult>>;
+}
+```
+
+> 依赖声明：`dependencies: ['permissionServer.permissionService']`
+
+## ObjectId 的运行时使用
+
+`@linyjs/shared-module-interface` 是纯类型包，`ObjectId` 等类型导入在编译后会被擦除。运行时需要通过注入的 `IMongoDBService` 实例获取 `ObjectId` 构造器：
+
+```typescript
+import type { IMongoDBService, ObjectId } from '@linyjs/shared-module-interface';
+
+class ArticleService {
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+
+  async getArticleById(id: string) {
+    const collection = this.mongoDBService.getCollection('articles');
+    // ✅ 运行时通过 service.ObjectId 获取构造器
+    const article = await collection.findOne({
+      _id: new this.mongoDBService.ObjectId(id)
+    });
+    return article;
+  }
+
+  async getArticleWithType(id: string): Promise<{ _id: ObjectId; title: string } | null> {
+    const collection = this.mongoDBService.getCollection('articles');
+    // ✅ ObjectId 作为类型注解使用（编译后擦除）
+    const oid: ObjectId = new this.mongoDBService.ObjectId(id);
+    return await collection.findOne({ _id: oid });
+  }
+}
+```
+
+### 在服务类外部使用 ObjectId
+
+如果需要在服务类外部（如工具函数、模型层）创建 `ObjectId`，可以将 `mongoDBService` 引用保存到模块级变量：
+
+```typescript
+// db.ts
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+let mongoDBService: IMongoDBService | null = null;
+
+export function setMongoDBService(service: IMongoDBService) {
+  mongoDBService = service;
+}
+
+export function createObjectId(id: string) {
+  if (!mongoDBService) throw new Error('MongoDB service not initialized');
+  return new mongoDBService.ObjectId(id);
+}
+
+export function getCollection(name: string) {
+  if (!mongoDBService) throw new Error('MongoDB service not initialized');
+  return mongoDBService.getCollection(name);
+}
+```
+
+```typescript
+// service.ts
+import { setMongoDBService, createObjectId, getCollection } from './db.js';
+
+class ArticleService {
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+
+  async initialize() {
+    // 将 mongoDBService 保存到模块级变量，供工具函数使用
+    setMongoDBService(this.mongoDBService);
+  }
+
+  async getArticleById(id: string) {
+    const collection = getCollection('articles');
+    return await collection.findOne({ _id: createObjectId(id) });
+  }
+}
+```
+
+## 可注入服务汇总
+
+| 依赖引用 | 接口类型 | 来源模块 | 说明 |
+|----------|----------|----------|------|
+| `'mdb.mongoDBService'` | `IMongoDBService` | mdb | MongoDB 数据库服务 |
+| `'authServer.userService'` | `IUserService` | auth | 用户管理服务 |
+| `'authServer.initService'` | - | auth | 系统初始化服务 |
+| `'permissionServer.permissionService'` | `IPermissionService` | permission | 权限检查服务 |
+
+> 💡 使用这些服务时，需要在模块定义中声明 `moduleDependencies`。
+
+## 完整示例
+
+以下示例展示如何同时注入多个基础模块服务：
+
+```typescript
+import type { IModule, IServiceDef, IControllerService } from '@linyjs/server-module-interface';
+import type {
+  IMongoDBService,
+  IUserService,
+  IPermissionService,
+  ISafeUser
+} from '@linyjs/shared-module-interface';
+
+class AdminController implements IControllerService {
+  private mongoDBService: IMongoDBService;
+  private userService: IUserService;
+  private permissionService: IPermissionService;
+
+  constructor(deps: {
+    mongoDBService: IMongoDBService;
+    userService: IUserService;
+    permissionService: IPermissionService;
+  }) {
+    this.mongoDBService = deps.mongoDBService;
+    this.userService = deps.userService;
+    this.permissionService = deps.permissionService;
+  }
+
+  getRoutes() {
+    return [
+      {
+        method: 'GET' as const,
+        path: '/api/admin/users',
+        middlewares: ['auth'],
+        responseType: 'json' as const,
+        handler: async (params: Record<string, any>, ctx: any) => {
+          const user = ctx.user as ISafeUser;
+
+          // 使用权限服务检查权限
+          const result = await this.permissionService.check(
+            user,
+            'admin:read'
+          );
+          if (!result.allowed) {
+            return { status: 403, data: { error: result.reason } };
+          }
+
+          // 使用用户服务获取用户列表
+          const users = await this.userService.getAllUsers();
+          return { success: true, data: users };
+        }
+      }
+    ];
+  }
+}
+
+const adminControllerDef: IServiceDef = {
+  serviceTag: 'adminController',
+  serviceImpl: AdminController,
+  dependencies: [
+    'mdb.mongoDBService',
+    'authServer.userService',
+    'permissionServer.permissionService'
+  ],
+  meta: { usageType: 'controller' }
+};
+
+export const adminServerModule: IModule = {
+  name: 'adminServer',
+  moduleDependencies: ['mdb', 'authServer', 'permissionServer'],
+  serviceDefs: [adminControllerDef]
+};
+```
+
+## 相关文档
+
+- 📖 [依赖注入机制](./dependency-injection.md) — DI 的完整说明
+- 💾 [数据持久化](./data-persistence.md) — MongoDB 服务详细使用
+- 🔐 [用户认证](./authentication.md) — 认证模块使用
+- 🛡️ [权限管理](./permissions.md) — 权限模块使用
+- 🔧 [API 参考](../api-reference/index.md) — 接口类型定义
+
+---
+
+**上一篇**: [依赖注入机制](./dependency-injection.md) | **下一篇**: [客户端模块开发](./client-module.md)

package/examples/analytics-plugin/package.json

@@ -13,13 +13,13 @@
   "author": "Linyjs Team",
   "license": "MIT",
   "peerDependencies": {
-    "@linyjs/server-module-interface": "0.0.3",
-    "@linyjs/client-module-interface": "0.0.3",
-    "@linyjs/ui-slots-interface": "0.0.3"
+    "@linyjs/server-module-interface": "latest",
+    "@linyjs/client-module-interface": "latest",
+    "@linyjs/ui-slots-interface": "latest"
   },
   "devDependencies": {
-    "@linyjs/server-module-interface": "0.0.3",
-    "@linyjs/client-module-interface": "0.0.3"
+    "@linyjs/server-module-interface": "latest",
+    "@linyjs/client-module-interface": "latest"
   },
   "linyjs": {
     "compatibleVersions": ["0.8.x"],

package/examples/analytics-plugin/src/server/index.ts

@@ -158,7 +158,7 @@ class AnalyticsController {
         responseType: 'json' as const,
         handler: async (params: any, ctx: any) => {
           try {
-            const { eventName, userId, data } = params.body;
+            const { eventName, userId, data } = params;
 
             if (!eventName || !userId) {
               return {
@@ -186,8 +186,8 @@ class AnalyticsController {
         responseType: 'json' as const,
         handler: async (params: any, ctx: any) => {
           try {
-            const startDate = params.query?.start || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
-            const endDate = params.query?.end || new Date().toISOString();
+            const startDate = params.start || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+            const endDate = params.end || new Date().toISOString();
 
             const result = await this.analyticsService.getAnalytics(startDate, endDate);
             return result;
@@ -227,7 +227,7 @@ class AnalyticsController {
         responseType: 'json' as const,
         handler: async (params: any, ctx: any) => {
           try {
-            const days = parseInt(params.query?.days || '7');
+            const days = parseInt(params.days || '7');
             const result = await this.analyticsService.getUserRetention(days);
             return result;
           } catch (error: any) {

package/examples/blog-plugin/package.json

@@ -9,9 +9,9 @@
     "pack": "npx @linyjs/cli pack"
   },
   "dependencies": {
-    "@linyjs/server-module-interface": "^0.0.1",
-    "@linyjs/client-module-interface": "^0.0.1",
-    "@linyjs/mdb": "^0.0.1",
+    "@linyjs/server-module-interface": "latest",
+    "@linyjs/client-module-interface": "latest",
+    "@linyjs/mdb": "latest",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/examples/blog-plugin/src/server/index.ts

@@ -103,8 +103,8 @@ class ArticleController {
         middlewares: [],
         responseType: 'json' as const,
         handler: async (params: any, ctx: any) => {
-          const page = parseInt(params.query?.page || '1');
-          const limit = parseInt(params.query?.limit || '10');
+          const page = parseInt(params.page || '1');
+          const limit = parseInt(params.limit || '10');
           
           try {
             const result = await this.articleService.getArticles(page, limit);
@@ -146,7 +146,7 @@ class ArticleController {
         responseType: 'json' as const,
         handler: async (params: any, ctx: any) => {
           try {
-            const { title, content, author } = params.body;
+            const { title, content, author } = params;
             
             if (!title || !content) {
               return {
@@ -183,7 +183,7 @@ class ArticleController {
         handler: async (params: any, ctx: any) => {
           try {
             const id = parseInt(params.id);
-            const article = await this.articleService.updateArticle(id, params.body);
+            const article = await this.articleService.updateArticle(id, params);
             
             return {
               success: true,

package/examples/hello-world/package.json

@@ -9,8 +9,8 @@
     "pack": "npx @linyjs/cli pack"
   },
   "dependencies": {
-    "@linyjs/server-module-interface": "^0.0.1",
-    "@linyjs/client-module-interface": "^0.0.1",
+    "@linyjs/server-module-interface": "latest",
+    "@linyjs/client-module-interface": "latest",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/examples/hello-world/src/server/index.ts

@@ -14,7 +14,7 @@ class HelloController {
         responseType: 'json' as const,
         handler: async (params: any, ctx: any) => {
           // 获取查询参数(如果有)
-          const name = params.query?.name || 'World';
+          const name = params.name || 'World';
           
           return {
             message: `Hello, ${name}!`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linyjs/plugin-docs",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Plugin development documentation and examples for linyjs framework",
   "keywords": [
     "linyjs",
@@ -31,9 +31,9 @@
     "build": "tsc"
   },
   "peerDependencies": {
-    "@linyjs/client-module-interface": "0.0.11",
-    "@linyjs/server-module-interface": "0.0.11",
-    "@linyjs/ui-slots-interface": "0.0.11"
+    "@linyjs/client-module-interface": "latest",
+    "@linyjs/server-module-interface": "latest",
+    "@linyjs/ui-slots-interface": "latest"
   },
   "dependencies": {
     "commander": "^11.1.0"