# 项目架构设计 ## 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