.
This commit is contained in:
1
docs/02-技术文档/.gitkeep
Normal file
1
docs/02-技术文档/.gitkeep
Normal file
@@ -0,0 +1 @@
|
||||
# 技术文档目录
|
||||
161
docs/02-技术文档/模块化架构设计.md
Normal file
161
docs/02-技术文档/模块化架构设计.md
Normal file
@@ -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
|
||||
247
docs/02-技术文档/项目架构设计.md
Normal file
247
docs/02-技术文档/项目架构设计.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 项目架构设计
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
ssq-desk 是基于 Wails 框架开发的桌面应用，提供双色球历史数据查询和统计分析功能。
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术架构
|
||||
|
||||
### 2.1 整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ 前端 (Vue 3 + Arco) │
|
||||
│ ┌────────────┐ ┌──────────────┐ │
|
||||
│ │ 查询界面 │ │ 结果展示 │ │
|
||||
│ └────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────┘
|
||||
↕ Wails Context
|
||||
┌─────────────────────────────────────┐
|
||||
│ 后端 (Go + Wails) │
|
||||
│ ┌──────────┐ ┌──────────────┐ │
|
||||
│ │ API层 │→ │ Service层 │ │
|
||||
│ └──────────┘ └──────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌──────────────────────────────┐ │
|
||||
│ │ Storage层 (Repository) │ │
|
||||
│ └──────────────────────────────┘ │
|
||||
└─────────────────────────────────────┘
|
||||
↕
|
||||
┌─────────────────────────────────────┐
|
||||
│ 数据层 │
|
||||
│ ┌──────────┐ ┌──────────────┐ │
|
||||
│ │ MySQL │ │ SQLite │ │
|
||||
│ │ (远程) │ │ (本地缓存) │ │
|
||||
│ └──────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 模块化架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ App (app.go) │
|
||||
│ 模块管理器统一管理 │
|
||||
└─────────────────────────────────────┘
|
||||
↕
|
||||
┌─────────────────────────────────────┐
|
||||
│ Module Manager │
|
||||
│ ┌────────┐ ┌────────┐ ┌──────┐ │
|
||||
│ │ SSQ │ │ Auth │ │Update│ │
|
||||
│ │ Module │ │ Module │ │Module│ │
|
||||
│ └────────┘ └────────┘ └──────┘ │
|
||||
└─────────────────────────────────────┘
|
||||
↕
|
||||
┌─────────────────────────────────────┐
|
||||
│ API Layer │
|
||||
│ ┌────────┐ ┌────────┐ │
|
||||
│ │SSQ API │ │Auth API│ │
|
||||
│ └────────┘ └────────┘ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.3 目录结构
|
||||
|
||||
```
|
||||
ssq-desk/
|
||||
├─ app.go # Wails 应用结构，模块管理器
|
||||
├─ main.go # 应用入口
|
||||
├─ internal/ # 内部包
|
||||
│ ├─ module/ # 模块层（新增）
|
||||
│ │ ├─ module.go # 模块接口定义
|
||||
│ │ ├─ manager.go # 模块管理器
|
||||
│ │ ├─ ssq_module.go # SSQ 查询模块
|
||||
│ │ ├─ auth_module.go # 授权码模块
|
||||
│ │ └─ update_module.go # 版本更新模块
|
||||
│ ├─ api/ # API 层（Wails 绑定接口）
|
||||
│ │ ├─ ssq_api.go # 双色球查询 API
|
||||
│ │ └─ auth_api.go # 授权码 API
|
||||
│ ├─ service/ # 业务逻辑层
|
||||
│ │ ├─ query_service.go # 查询服务
|
||||
│ │ └─ auth_service.go # 授权服务
|
||||
│ ├─ storage/ # 存储层
|
||||
│ │ ├─ models/ # 数据模型
|
||||
│ │ │ ├─ ssq_history.go # 历史数据模型
|
||||
│ │ │ └─ authorization.go # 授权模型
|
||||
│ │ └─ repository/ # 数据访问层
|
||||
│ │ ├─ mysql_repo.go # MySQL 仓库
|
||||
│ │ ├─ sqlite_repo.go # SQLite 仓库
|
||||
│ │ └─ auth_repository.go # 授权仓库
|
||||
│ └─ database/ # 数据库连接
|
||||
│ ├─ mysql.go # MySQL 连接
|
||||
│ └─ sqlite.go # SQLite 连接
|
||||
├─ web/ # 前端目录
|
||||
│ ├─ src/
|
||||
│ │ ├─ views/ # 页面组件
|
||||
│ │ │ └─ query/ # 查询页面
|
||||
│ │ ├─ components/ # 公共组件
|
||||
│ │ └─ wailsjs/ # Wails 生成的文件
|
||||
│ └─ package.json
|
||||
└─ wails.json # Wails 配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据流设计
|
||||
|
||||
### 3.1 查询流程
|
||||
|
||||
```
|
||||
用户输入查询条件
|
||||
↓
|
||||
前端调用 Wails 绑定方法
|
||||
↓
|
||||
API 层接收参数
|
||||
↓
|
||||
Service 层处理业务逻辑
|
||||
↓
|
||||
Repository 层查询数据
|
||||
├─ 优先查询 SQLite（本地缓存）
|
||||
└─ 如需更新，查询 MySQL（远程）
|
||||
↓
|
||||
返回结果给前端
|
||||
↓
|
||||
前端展示结果（分类统计 + 详细列表）
|
||||
```
|
||||
|
||||
### 3.2 数据同步流程
|
||||
|
||||
```
|
||||
应用启动/手动触发
|
||||
↓
|
||||
检查远程数据更新
|
||||
↓
|
||||
增量同步（基于 issue_number）
|
||||
↓
|
||||
写入 SQLite 本地缓存
|
||||
↓
|
||||
更新同步状态和日志
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心功能模块
|
||||
|
||||
### 4.1 模块化设计
|
||||
|
||||
采用模块化架构，各功能模块相互独立、松散耦合：
|
||||
|
||||
- **模块接口**：统一的 `Module` 接口
|
||||
- **模块管理器**：统一管理模块的注册、初始化、启动、停止
|
||||
- **模块独立性**：各模块可独立开发、测试、部署
|
||||
|
||||
详细设计参见：[模块化架构设计](./模块化架构设计.md)
|
||||
|
||||
### 4.2 SSQ 查询模块
|
||||
- **模块名称**：`ssq`
|
||||
- **功能**：根据红球、蓝球条件查询历史数据
|
||||
- **输入**：6个红球 + 1个蓝球 + 蓝球筛选范围
|
||||
- **输出**：分类统计 + 详细记录列表
|
||||
- **特性**：支持部分匹配、颜色标识匹配结果
|
||||
|
||||
### 4.3 授权码模块
|
||||
- **模块名称**：`auth`
|
||||
- **功能**：设备授权码验证、激活状态管理
|
||||
- **存储**：SQLite 本地数据库
|
||||
- **启动行为**：应用启动时自动检查授权状态
|
||||
|
||||
### 4.4 版本更新模块
|
||||
- **模块名称**：`update`
|
||||
- **功能**：版本更新检查、下载、安装
|
||||
- **状态**：待实现
|
||||
|
||||
### 4.5 数据同步模块（待模块化）
|
||||
- **功能**：MySQL 与 SQLite 数据同步
|
||||
- **策略**：增量同步、全量同步、手动刷新
|
||||
- **错误处理**：网络异常、数据冲突处理
|
||||
|
||||
---
|
||||
|
||||
## 5. 性能优化策略
|
||||
|
||||
### 5.1 数据查询
|
||||
- **本地优先**：优先使用 SQLite 本地缓存
|
||||
- **分页加载**：查询结果分页显示
|
||||
- **索引优化**：为常用查询字段建立索引
|
||||
|
||||
### 5.2 数据同步
|
||||
- **异步同步**：后台异步同步，不阻塞主流程
|
||||
- **增量更新**：仅同步增量数据，减少网络传输
|
||||
- **智能调度**：根据数据更新频率调整同步策略
|
||||
|
||||
### 5.3 前端优化
|
||||
- **虚拟滚动**：大量数据使用虚拟滚动
|
||||
- **懒加载**：按需加载详细数据
|
||||
- **缓存策略**：合理使用 LocalStorage 缓存
|
||||
|
||||
---
|
||||
|
||||
## 6. 安全设计
|
||||
|
||||
### 6.1 数据安全
|
||||
- **连接加密**：MySQL 连接使用 TLS/SSL
|
||||
- **密码管理**：数据库密码加密存储
|
||||
- **本地数据**：敏感数据本地加密存储
|
||||
|
||||
### 6.2 授权验证
|
||||
- **设备绑定**：授权码与设备绑定
|
||||
- **激活验证**：启动时验证激活状态
|
||||
- **离线模式**：授权失效时限制功能
|
||||
|
||||
---
|
||||
|
||||
## 7. 错误处理
|
||||
|
||||
### 7.1 网络错误
|
||||
- **连接失败**：自动切换到离线模式
|
||||
- **超时处理**：设置合理的超时时间
|
||||
- **重试机制**：自动重试失败的请求
|
||||
|
||||
### 7.2 数据错误
|
||||
- **数据校验**：入库前校验数据完整性
|
||||
- **异常处理**：捕获并记录异常日志
|
||||
- **用户提示**：友好的错误提示信息
|
||||
|
||||
---
|
||||
|
||||
## 8. 扩展性设计
|
||||
|
||||
### 8.1 功能扩展
|
||||
- **模块化设计**：功能模块独立，易于扩展（已实现）
|
||||
- 新增功能只需实现 `Module` 接口并注册
|
||||
- 模块之间不直接依赖，通过管理器解耦
|
||||
- 支持模块的独立开发、测试、部署
|
||||
- **接口抽象**：定义清晰的接口，便于替换实现
|
||||
- **配置驱动**：支持配置文件扩展功能
|
||||
|
||||
### 8.2 数据扩展
|
||||
- **多数据源**：支持多种数据源接入
|
||||
- **数据格式**：支持多种数据格式导入
|
||||
- **统计分析**：预留统计分析扩展接口
|
||||
|
||||
---
|
||||
|
||||
> 文档维护者：JueChen
|
||||
> 创建时间：2026-01-07
|
||||
Reference in New Issue
Block a user