mengstack-api/internal/kernel/plugin/.spec/module.md

Plugin 系统规范

模块边界

plugin 包定义插件的契约与注册中心，是所有业务模块（包括内核模块和第三方插件）的统一接入方式。

属于本模块： Plugin 接口定义、注册中心、生命周期管理 不属于本模块： 具体插件的业务逻辑

Plugin 接口

每个插件必须实现：

type Plugin interface {
    Metadata() Metadata           // 身份标识（name/version/description）
    FxOption() fx.Option          // 依赖注入（提供 repo/service/handler）
    SetupRoutes(engine, authMW, tenantResolver) // HTTP 路由注册
    Init() error                  // 启动钩子（worker/cache/外部连接）
    MigrationsFS() fs.FS          // 插件自主迁移（独立 schema_migrations_{name} 表）
}

生命周期

1. app.go 启动 → fx 解析所有 Module → 依赖注入
2. OnStart → 核心迁移 → 插件迁移 → plugin.InitAll()
3. HTTP Server 启动 → 请求路由到各插件 Handler
4. OnStop → 优雅关闭

创建新插件步骤

1. 在 internal/modules/<name>/ 创建 4 层目录
2. domain/ — 定义实体 + Repository 接口（零外部依赖）
3. infrastructure/ — GORM Repo 实现 + migrate.go
4. application/ — Service 编排
5. interfaces/ — Handler + Routes + Plugin 实现
6. 在 app.go 的 NewApp() 注册 fx.Module
7. 在 newEngine() 调用 plugin.SetupRoutes()

插件自主迁移

• 每个插件的迁移使用独立表：schema_migrations_{pluginName}
• 插件通过 MigrationsFS() 返回嵌入的迁移文件 FS
• 返回 nil 表示无迁移
• 迁移在核心迁移之后、Init() 之前执行

路由约定

• 插件路由前缀：/api/v1/{module}/
• 必须经过 authMW（JWT 认证）+ MultiTenant（租户识别）
• 公开接口（如注册）不走 authMW

禁止

• 插件不得 import 其他插件的内部代码
• 插件不得直接操作其他插件的数据库表
• 插件间通信走事件总线（kernel/eventbus）
• kernel/ 不得 import 任何插件代码