@linyjs/plugin-docs 0.0.13 → 0.0.14

package/README.md

@@ -65,28 +65,28 @@ 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/       # 最佳实践
+├── getting-started/          # 入门教程
+│   ├── quick-start.md        # 快速开始
+│   ├── installation.md       # 安装指南
+│   └── first-plugin.md       # 第一个插件
+├── guides/                   # 进阶指南
+│   ├── server-module.md      # 服务端模块
+│   ├── dependency-injection.md # 依赖注入机制
+│   ├── shared-module-interface.md # shared-module-interface 类型包
+│   ├── client-module.md      # 客户端模块
+│   ├── ui-slots.md           # UI扩展插槽
+│   ├── permissions.md        # 权限管理
+│   ├── data-persistence.md   # 数据持久化
+│   └── authentication.md     # 用户认证
+├── api-reference/            # API参考
+│   └── index.md              # 接口定义（含依赖注入接口）
+├── best-practices/           # 最佳实践
 │   ├── naming-conventions.md
 │   ├── service-definition.md  # ServiceDef 代码风格规范
 │   ├── error-handling.md
 │   ├── performance.md
 │   └── security.md
-└── faq.md                # 常见问题
+└── faq.md                    # 常见问题
 ```
 
 ## 💡 示例项目
@@ -128,6 +128,8 @@ linyjs 提供了以下核心模块，插件可以通过依赖注入方式调用
 
 ## 📖 核心模块指南
 
+- 📖 [依赖注入机制](./docs/guides/dependency-injection.md) — linyjs DI 机制完整说明
+- 📦 [shared-module-interface](./docs/guides/shared-module-interface.md) — 类型定义包使用说明
 - 💾 [数据持久化](./docs/guides/data-persistence.md) - 使用 @linyjs/mdb
 - 🔐 [用户认证](./docs/guides/authentication.md) - 使用 @linyjs/auth
 - 🛡️ [权限管理](./docs/guides/permissions.md) - 使用 @linyjs/permission

package/docs/api-reference/index.md

@@ -41,11 +41,11 @@ export const myModule: IModule = {
 服务定义的通用接口。
 
 ```typescript
-interface IServiceDef {
+interface IServiceDef<S extends IService = IService, M extends IServiceMetadata = IServiceMetadata> {
   serviceTag: string;
-  serviceImpl: any;
-  dependencies?: string[];
-  meta: ServiceMetadata;
+  serviceImpl: IServiceMaker<S>;  // class 或工厂函数
+  dependencies?: string[];         // 支持 'serviceTag' 或 'moduleName.serviceTag'
+  meta?: M;
 }
 ```
 
@@ -53,10 +53,12 @@ interface IServiceDef {
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `serviceTag` | string | ✅ | 服务的唯一标签 |
-| `serviceImpl` | class | ✅ | 服务实现类 |
-| `dependencies` | string[] | ❌ | 依赖的其他服务 |
-| `meta` | ServiceMetadata | ✅ | 元数据(包含 usageType) |
+| `serviceTag` | string | ✅ | 服务的唯一标签（模块内唯一） |
+| `serviceImpl` | class \| function | ✅ | 服务实现，可以是类或工厂函数 |
+| `dependencies` | string[] | ❌ | 依赖的其他服务，支持模块内和跨模块引用 |
+| `meta` | ServiceMetadata | ✅ | 元数据（包含 usageType） |
+
+> ⚠️ **构造函数约定**：框架将依赖组装为 `{ serviceTag: instance }` 对象传入构造函数，构造函数**必须使用解构赋值**。详见 [依赖注入机制](../guides/dependency-injection.md#构造函数约定)。
 
 ---
 
@@ -334,6 +336,17 @@ registry.register({
 
 linyjs 框架提供了以下基础模块，插件开发者可以通过依赖注入方式使用：
 
+### 可注入服务汇总
+
+| 依赖引用 | 接口类型 | 来源模块 | 说明 |
+|----------|----------|----------|------|
+| `'mdb.mongoDBService'` | `IMongoDBService` | @linyjs/mdb | MongoDB 数据库服务 |
+| `'authServer.userService'` | `IUserService` | @linyjs/auth | 用户管理服务 |
+| `'authServer.initService'` | - | @linyjs/auth | 系统初始化服务 |
+| `'permissionServer.permissionService'` | `IPermissionService` | @linyjs/permission | 权限检查服务 |
+
+> 💡 使用 `@linyjs/shared-module-interface` 包获取这些接口的 TypeScript 类型定义，详见 [shared-module-interface 指南](../guides/shared-module-interface.md)。
+
 ### 数据库模块
 - **@linyjs/mdb** - MongoDB 数据库服务
 - 提供数据库连接、CRUD 操作、索引管理等功能
@@ -349,8 +362,78 @@ linyjs 框架提供了以下基础模块，插件开发者可以通过依赖注
 - 提供基于角色的访问控制(RBAC)
 - 详见：[权限管理指南](../guides/permissions.md)
 
+## 依赖注入接口
+
+### IService / IServiceMaker
+
+服务基础类型和实现类型定义：
+
+```typescript
+// 所有服务的基础类型
+type IService = object
+
+// 服务类构造器
+type IServiceConstructor<S> = new (...args: any[]) => S
+
+// 服务工厂函数
+type IServiceFactory<S> = (...args: any[]) => S
+
+// 服务实现（类或工厂函数）
+type IServiceMaker<S> = IServiceConstructor<S> | IServiceFactory<S>
+```
+
+### 依赖引用格式
+
+`IServiceDef.dependencies` 中的字符串支持两种格式：
+
+| 格式 | 示例 | 说明 |
+|------|------|------|
+| 模块内引用 | `'myService'` | 从当前模块已实例化的服务中查找 |
+| 跨模块引用 | `'mdb.mongoDBService'` | 格式为 `moduleName.serviceTag`，从指定模块查找 |
+
+> 📖 完整的依赖注入机制说明，请阅读 [依赖注入机制指南](../guides/dependency-injection.md)。
+
+### IMongoDBService
+
+由 @linyjs/mdb 模块实现，通过 `'mdb.mongoDBService'` 注入：
+
+```typescript
+interface IMongoDBService {
+  readonly ObjectId: typeof ObjectId;
+  getDb(): Db;
+  getCollection<T>(name: string): Collection<T>;
+  isConnected(): boolean;
+  close(): Promise<void>;
+}
+```
+
+### IUserService
+
+由 @linyjs/auth 模块实现，通过 `'authServer.userService'` 注入：
+
+```typescript
+interface IUserService {
+  getAllUsers(): Promise<ISafeUser[]>;
+  updateUserRoles(userId: string, roles: string[]): Promise<ISafeUser | null>;
+}
+```
+
+### IPermissionService
+
+由 @linyjs/permission 模块实现，通过 `'permissionServer.permissionService'` 注入：
+
+```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>>;
+}
+```
+
 ## 相关文档
 
+- 📖 [依赖注入机制](../guides/dependency-injection.md) — DI 完整说明
+- 📦 [shared-module-interface 指南](../guides/shared-module-interface.md) — 类型定义包
 - 📖 [服务端模块开发](../guides/server-module.md)
 - 💻 [客户端模块开发](../guides/client-module.md)
 - 🎨 [UI 扩展插槽](../guides/ui-slots.md)

package/docs/best-practices/error-handling.md

@@ -35,7 +35,7 @@ handler: async (params, ctx) => {
 handler: async (params, ctx) => {
   try {
     // 输入验证错误
-    if (!params.body.email) {
+    if (!params.email) {
       return {
         status: 400,
         data: { error: 'Email is required' }
@@ -43,7 +43,7 @@ handler: async (params, ctx) => {
     }
 
     // 业务逻辑错误
-    const user = await findUser(params.body.email);
+    const user = await findUser(params.email);
     if (!user) {
       return {
         status: 404,
@@ -92,7 +92,7 @@ class AuthorizationError extends Error {
 // 在处理器中使用
 handler: async (params, ctx) => {
   try {
-    if (!isValidEmail(params.body.email)) {
+    if (!isValidEmail(params.email)) {
       throw new ValidationError('Invalid email format', 'email');
     }
 

package/docs/best-practices/security.md

@@ -16,7 +16,7 @@
 ```typescript
 // 严格的输入验证
 handler: async (params, ctx) => {
-  const { email, password, age } = params.body;
+  const { email, password, age } = params;
 
   // 邮箱格式验证
   if (!isValidEmail(email)) {
@@ -73,7 +73,7 @@ const userSchema = Joi.object({
 
 // 在处理器中使用验证
 handler: async (params, ctx) => {
-  const { error, value } = userSchema.validate(params.body);
+  const { error, value } = userSchema.validate(params);
 
   if (error) {
     return {

package/docs/faq.md

@@ -282,7 +282,7 @@ const user = await db.collection('users').findOne({
 **A:** 
 ```typescript
 handler: async (params) => {
-  const { email } = params.body;
+  const { email } = params;
   
   // 验证邮箱格式
   if (!isValidEmail(email)) {

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

@@ -162,8 +162,8 @@ export class ArticleController implements IControllerService {
         middlewares: [],
         responseType: 'json' as const,
         handler: async (params: 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');
           return await this.articleService.getArticles(page, limit);
         }
       },
@@ -173,7 +173,7 @@ export class ArticleController implements IControllerService {
         middlewares: [],
         responseType: 'json' as const,
         handler: async (params: any) => {
-          const article = await this.articleService.createArticle(params.body);
+          const article = await this.articleService.createArticle(params);
           return { success: true, data: article };
         }
       }