ssq-desk/docs/01-规范/03-数据库规范.md

数据存储规范

1. 存储架构

1.1 远程数据库（MySQL）

• 用途：完整历史数据源
• 地址：39.99.243.191:3306
• 账号：u_ssq
• 密码：u_ssq@260106
• 连接方式：需要时连接，支持离线模式

1.2 本地数据库（SQLite）

• 用途：本地数据缓存、离线查询支持
• 位置：应用数据目录
• 同步策略：增量同步，定期更新

1.3 文件存储

• 配置文件：应用配置、用户偏好
• 离线数据包：完整历史数据导出/导入
• 缓存文件：临时数据

1.4 前端存储

• LocalStorage：临时数据、用户偏好、UI 状态

2. 数据库设计规范

2.1 表名规范

• 小写字母，单词间下划线：ssq_history、query_cache

2.2 字段规范

• 小写字母，单词间下划线：issue_number、red_ball_1、created_at
• 主键统一使用 id（INT 或 BIGINT）
• 时间字段：created_at、updated_at（DATETIME）

2.3 数据类型规范

• 期号：VARCHAR(20)，如 "2025145"
• 球号：TINYINT，范围 1-33（红球）或 1-16（蓝球）
• 日期：DATE 或 DATETIME

2.4 索引规范

• 主键索引：PRIMARY KEY (id)
• 查询索引：INDEX idx_issue_number (issue_number)
• 日期索引：INDEX idx_open_date (open_date)

3. 数据同步规范

3.1 同步策略

• 增量同步：基于 id 或 issue_number 增量更新
• 全量同步：首次安装或数据修复
• 同步时机：应用启动检查、手动触发、定时任务

3.2 数据校验

• 期号唯一性校验
• 球号范围校验（红球 1-33，蓝球 1-16）
• 数据完整性校验

3.3 错误处理

• 网络错误：使用本地缓存
• 数据冲突：以远程为准或用户选择
• 同步失败：记录日志，下次重试

4. Go 结构体映射

4.1 ORM 工具

• 使用 gorm 进行 ORM 映射
• MySQL 和 SQLite 使用相同模型结构

4.2 结构体规范

type SsqHistory struct {
    ID         int       `gorm:"primaryKey" json:"id"`
    IssueNumber string   `gorm:"type:varchar(20);not null;index" json:"issue_number"`
    OpenDate    *time.Time `gorm:"type:date" json:"open_date"`
    RedBall1    int       `gorm:"type:tinyint;not null" json:"red_ball_1"`
    // ... 其他字段
    CreatedAt   time.Time `json:"created_at"`
    UpdatedAt   time.Time `json:"updated_at"`
}

4.3 表名映射

• 实现 TableName() 方法指定表名
• 或使用 gorm 默认命名规则

---

文档维护者：JueChen
创建时间：2026-01-07