.

docs/02-技术文档/模块化架构设计.md

@@ -0,0 +1,161 @@
+# 模块化架构设计
+
+## 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