248 lines
9.2 KiB
Markdown
248 lines
9.2 KiB
Markdown
# 项目架构设计
|
||
|
||
## 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
|