9.2 KiB
9.2 KiB
项目架构设计
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接口 - 模块管理器：统一管理模块的注册、初始化、启动、停止
- 模块独立性：各模块可独立开发、测试、部署
详细设计参见：模块化架构设计
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