# 模块化架构设计

## 1. 设计理念

采用模块化设计，各功能模块相互独立、松散耦合，便于维护和扩展。

### 1.1 模块独立性
- 每个功能模块（ssq查询、授权码、版本更新）独立实现
- 模块之间不直接依赖，通过模块管理器统一管理
- 模块可以独立开发、测试、部署

### 1.2 松耦合设计
- 模块通过接口定义，不依赖具体实现
- 模块管理器负责模块的注册、初始化、启动、停止
- App 层只依赖模块管理器，不直接依赖具体模块

## 2. 模块接口

### 2.1 Module 接口

```go
type Module interface {
    Name() string              // 模块名称
    Init(ctx context.Context) error    // 初始化
    Start(ctx context.Context) error    // 启动
    Stop(ctx context.Context) error     // 停止
    GetAPI() interface{}       // 获取 API 接口
}
```

### 2.2 BaseModule 基础实现

提供模块的基础实现，各模块可以继承并扩展。

## 3. 模块管理器

### 3.1 Manager 功能
- 模块注册：`Register(module Module)`
- 模块获取：`Get(name string)`
- 批量操作：`InitAll()`, `StartAll()`, `StopAll()`
- API 收集：`GetAPIs()`

### 3.2 使用方式

```go
manager := module.NewManager()

// 注册模块
ssqModule, _ := module.NewSsqModule()
manager.Register(ssqModule)

authModule, _ := module.NewAuthModule()
manager.Register(authModule)

// 初始化所有模块
manager.InitAll(ctx)

// 启动所有模块
manager.StartAll(ctx)
```

## 4. 功能模块

### 4.1 SSQ 查询模块

**模块名称**: `ssq`

**功能**: 双色球历史数据查询

**API**: `*api.SsqAPI`

**实现文件**: `internal/module/ssq_module.go`

### 4.2 授权码模块

**模块名称**: `auth`

**功能**: 设备授权码验证和激活

**API**: `*api.AuthAPI`

**实现文件**: `internal/module/auth_module.go`

**启动行为**: 自动检查授权状态

### 4.3 版本更新模块

**模块名称**: `update`

**功能**: 版本更新检查、下载、安装

**API**: 待实现

**实现文件**: `internal/module/update_module.go`

**状态**: 占位符，待实现

## 5. 目录结构

```
internal/
├─ module/              # 模块层
│  ├─ module.go         # 模块接口定义
│  ├─ manager.go        # 模块管理器
│  ├─ ssq_module.go     # SSQ 查询模块
│  ├─ auth_module.go    # 授权码模块
│  └─ update_module.go  # 版本更新模块（待实现）
├─ api/                 # API 层
│  ├─ ssq_api.go        # SSQ API
│  └─ auth_api.go       # Auth API
├─ service/             # 服务层
└─ storage/             # 存储层
```

## 6. 模块扩展

### 6.1 添加新模块

1. 实现 `Module` 接口
2. 创建模块文件（如 `xxx_module.go`）
3. 在 `NewApp()` 中注册模块

```go
xxxModule, _ := module.NewXxxModule()
manager.Register(xxxModule)
```

### 6.2 模块生命周期

```
注册 → 初始化 → 启动 → 运行 → 停止
```

- **注册**: 模块创建并注册到管理器
- **初始化**: 模块初始化资源（数据库、配置等）
- **启动**: 模块启动服务（检查授权、启动定时任务等）
- **运行**: 模块提供服务
- **停止**: 模块清理资源

## 7. 优势

### 7.1 可维护性
- 模块独立，修改不影响其他模块
- 清晰的模块边界和职责

### 7.2 可扩展性
- 新增功能只需添加新模块
- 模块可以独立开发和测试

### 7.3 可测试性
- 模块可以独立测试
- 便于 Mock 和单元测试

### 7.4 松耦合
- 模块之间不直接依赖
- 通过接口和管理器解耦

---

> 文档维护者：JueChen  
> 创建时间：2026-01-07