.

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

@@ -0,0 +1,88 @@
+# 数据存储规范
+
+## 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