# 数据存储规范

## 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 结构体规范
```go
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