架构概览

M-Doc 采用经典的分层架构，结合 Assembly 依赖注入和事件驱动设计。

---

分层架构

┌─────────────────────────────────────┐
│     HTTP Layer (Gin Router)         │  路由 + 中间件
├─────────────────────────────────────┤
│     Controller Layer                │  请求/响应处理
├─────────────────────────────────────┤
│     Service Layer                   │  业务逻辑
├─────────────────────────────────────┤
│     DAO Layer                       │  数据访问
├─────────────────────────────────────┤
│     Model Layer (GORM)              │  数据模型
└─────────────────────────────────────┘

各层职责

层级	目录	职责
Controller	app/controller/	解析请求参数，调用 Service，返回响应
Service	app/service/	业务逻辑，事务管理，事件触发
DAO	app/dao/	数据库 CRUD 操作
Model	app/model/	GORM 数据模型定义
DTO	app/dto/	数据传输对象（请求/响应结构）

控制器方法签名

控制器方法返回 dto.Response，由 WrapHandler 自动转换为 JSON：

func (c FeatureController) GetList(ctx *gin.Context) dto.Response {
    // 业务逻辑
    return dto.Response{Code: 200, Message: "成功", Data: data}
}

Assembly 依赖注入

M-Doc 使用 Assembly 模式管理组件初始化：

// config/assembly.go
func (receiver *Assembly) Get() []interfaces.AssemblyInterface {
    return []interfaces.AssemblyInterface{
        &envAssembly.Env{},           // 1. 环境变量
        &configAssembly.Config{},     // 2. 配置加载
        &loggerAssembly.Logger{},     // 3. 日志系统
        &databaseAssembly.Database{}, // 4. 数据库
        &redisAssembly.Redis{},       // 5. Redis
        &cacheAssembly.Cache{},       // 6. 缓存
        // ... 更多组件
    }
}

每个组件实现 InitConfig(helper) 方法，按顺序初始化。通过 helper 访问共享依赖：

• helper.GetDatabase() — GORM 实例
• helper.GetConfig() — Viper 配置
• helper.GetLogger() — Zap 日志
• helper.GetRedis() — Redis 客户端
• helper.GetCache() — 缓存实例

事件驱动设计

Service 层在操作完成后触发事件，监听器异步执行后续操作：

ArticleService.Publish()
    ↓
EventBus.Dispatch(ArticlePublishedEvent)
    ↓
├── LoggerListener（记录日志）
├── SummarizeListener（生成摘要）
└── VectorizeListener（更新向量索引）

这种设计实现了核心逻辑与扩展功能的解耦。

CE/EE 扩展机制

M-Doc 开源版（CE）设计为可扩展的基础：

mdoc-server (CE)          mdoc-ee (EE)
├── pkg/                  ├── 引用 CE 的 pkg
├── cmd/Start()           ├── 重写 Start() 注入 EE 功能
├── Assembly              ├── 追加 EE Assembly 组件
└── EventBus              └── 注册 EE 事件监听器

EE 版通过 Go Workspace 依赖 CE：

• 使用 CE 的公共包（pkg/）
• 在 Assembly 中追加 EE 组件
• 注册 EE 专属的事件监听器
• 添加 EE 路由（/api/ee/*）

这确保了 CE 版的完整性和独立性，同时允许 EE 版无侵入地扩展功能。

技术栈

组件	技术
HTTP 框架	Gin
ORM	GORM
配置	Viper
日志	Zap
缓存	Redis
认证	JWT + OIDC
向量搜索	langchaingo + pgvector
数据库迁移	Goose
定时任务	robfig/cron