# 数据库表文档

本文档记录了AI学习搭子系统中的数据库表结构和字段说明。

## 数据库配置

- **数据库类型**: H2 Database (开发环境)
- **连接URL**: `jdbc:h2:file:./data/testdb`
- **用户名**: `sa`
- **密码**: 无
- **H2控制台**: `http://localhost:8080/api/h2-console`

---

## 1. 用户信息表 (user_info)

### 表说明
存储中小学学习搭子系统的用户基本信息，包括用户名、密码、年级、头像等。

### 表结构

| 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 主键 | 唯一 | 说明 |
|--------|----------|------|----------|--------|------|------|------|
| user_id | BIGINT | - | NOT NULL | AUTO_INCREMENT | ✓ | - | 用户ID，主键，自增 |
| username | VARCHAR | 50 | NOT NULL | - | - | ✓ | 用户名，唯一，2-50个字符 |
| password | VARCHAR | 255 | NOT NULL | - | - | - | 用户密码，至少6个字符 |
| avatar_url | VARCHAR | 255 | NULL | - | - | - | 用户头像URL |
| grade | VARCHAR | 20 | NULL | - | - | - | 年级信息 |
| create_time | TIMESTAMP | - | NOT NULL | - | - | - | 创建时间，自动设置 |
| update_time | TIMESTAMP | - | NULL | - | - | - | 更新时间，自动更新 |

### 字段详细说明

- **user_id**: 用户唯一标识符，系统自动生成
- **username**: 用户登录名，必须唯一，长度限制2-50个字符
- **password**: 用户登录密码，最少6个字符（生产环境建议使用BCrypt加密）
- **avatar_url**: 用户头像文件的URL路径，支持jpg、jpeg、png格式，最大5MB
- **grade**: 用户所在年级，如"小学一年级"、"初中二年级"、"高中三年级"等
- **create_time**: 记录创建时间，插入时自动设置
- **update_time**: 记录最后更新时间，更新时自动设置

### 约束条件

- 用户名必须唯一
- 用户名和密码不能为空
- 创建时间不可更新
- 支持头像文件上传，文件保存在 `uploads/avatars/` 目录

---

## 2. 学习目标表 (goals)

### 表说明
存储用户的学习目标信息，包括目标内容、学科、难度、进度等。

### 表结构

| 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 主键 | 说明 |
|--------|----------|------|----------|--------|------|------|
| goal_id | BIGINT | - | NOT NULL | AUTO_INCREMENT | ✓ | 目标ID，主键，自增 |
| user_id | BIGINT | - | NOT NULL | - | - | 用户ID，外键关联user_info表 |
| subject | VARCHAR | 50 | NOT NULL | - | - | 学科名称 |
| goal_type | VARCHAR | 50 | NOT NULL | - | - | 目标类型 |
| goal_content | TEXT | - | NULL | - | - | 目标内容描述 |
| difficulty | VARCHAR | 20 | NULL | - | - | 难度等级 |
| total_quantity | INT | - | NULL | 0 | - | 目标总数量 |
| completed_quantity | INT | - | NULL | 0 | - | 已完成数量 |
| estimated_time | INT | - | NULL | - | - | 预估完成时间（分钟） |
| start_time | TIMESTAMP | - | NULL | - | - | 开始执行时间 |
| status | TINYINT | - | NULL | 0 | - | 目标状态 |
| create_time | TIMESTAMP | - | NULL | CURRENT_TIMESTAMP | - | 创建时间 |

### 字段详细说明

- **goal_id**: 学习目标唯一标识符，系统自动生成
- **user_id**: 关联的用户ID，外键引用user_info表的user_id
- **subject**: 学科名称，如"数学"、"语文"、"英语"、"物理"、"化学"等
- **goal_type**: 目标类型，枚举值：
  - `DAILY`: 每日目标
  - `WEEKLY`: 每周目标
  - `MONTHLY`: 每月目标
- **goal_content**: 目标的具体内容描述，如"完成代数练习题"、"背诵古诗词"等
- **difficulty**: 难度等级，枚举值：
  - `EASY`: 简单
  - `MEDIUM`: 中等
  - `HARD`: 困难
- **total_quantity**: 目标的总数量，如练习题数量、单词数量等
- **completed_quantity**: 已完成的数量，用于计算完成进度
- **estimated_time**: 预估完成时间，单位为分钟
- **start_time**: 目标开始执行的时间
- **status**: 目标状态，数值枚举：
  - `0`: PENDING（待执行）
  - `1`: IN_PROGRESS（进行中）
  - `2`: COMPLETED（已完成）
  - `3`: CANCELLED（已取消）
- **create_time**: 目标创建时间，默认为当前时间

### 业务规则

1. **目标状态流转**:
   - 新创建的目标默认状态为PENDING（0）
   - 调用开始接口后状态变为IN_PROGRESS（1）
   - 完成后状态变为COMPLETED（2）
   - 可以取消变为CANCELLED（3）

2. **进度计算**:
   - 完成率 = completed_quantity / total_quantity * 100%
   - 当completed_quantity >= total_quantity时，自动标记为已完成

3. **时间管理**:
   - create_time记录目标创建时间
   - start_time记录实际开始执行时间
   - 可根据estimated_time进行时间规划

---

## 3. 目标详情表 (goal_of_detail)

### 表说明
存储AI生成的题目详情信息，与学习目标表关联，支持选择题、填空题、单词题等多种题型。

### 表结构

| 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 主键 | 说明 |
|--------|----------|------|----------|--------|------|------|
| detail_id | BIGINT | - | NOT NULL | AUTO_INCREMENT | ✓ | 题目ID，主键，自增 |
| goal_id | BIGINT | - | NOT NULL | - | - | 目标ID，外键关联goals表 |
| subject | VARCHAR | 50 | NOT NULL | - | - | 学科名称 |
| content_type | INT | - | NOT NULL | - | - | 题目类型：1-选择题，2-填空题，3-单词 |
| content | TEXT | - | NOT NULL | - | - | 题目内容 |
| options | TEXT | - | NULL | - | - | 选择题选项，JSON格式存储 |
| answer | TEXT | - | NOT NULL | - | - | 题目答案 |
| difficulty | VARCHAR | 20 | NULL | - | - | 难度等级 |
| knowledge_point | VARCHAR | 100 | NULL | - | - | 知识点 |
| create_time | TIMESTAMP | - | NOT NULL | CURRENT_TIMESTAMP | - | 创建时间 |

### 字段详细说明

- **detail_id**: 题目唯一标识符，系统自动生成
- **goal_id**: 关联的学习目标ID，外键引用goals表的goal_id
- **subject**: 学科名称，与目标表的subject字段对应
- **content_type**: 题目类型，数值枚举：
  - `1`: 选择题（包含多个选项）
  - `2`: 填空题（需要填写答案）
  - `3`: 单词题（英语单词练习）
- **content**: 题目的具体内容，如"计算：3 + 5 = ?"
- **options**: 选择题的选项，JSON数组格式存储，如["A. 6", "B. 7", "C. 8", "D. 9"]
- **answer**: 题目的正确答案
- **difficulty**: 难度等级，与目标表的difficulty字段对应：
  - `简单`: 基础题目
  - `中等`: 中等难度题目
  - `困难`: 高难度题目
- **knowledge_point**: 题目涉及的知识点，如"加减法"、"代数"等
- **create_time**: 题目创建时间，AI生成时自动设置

### 业务规则

1. **题目生成规则**:
   - 每个目标可以包含多个题目
   - 题目数量由目标的total_quantity字段决定
   - AI根据目标的学科、难度等信息生成相应题目

2. **题目类型说明**:
   - 选择题：包含题目内容和多个选项，options字段存储选项数组
   - 填空题：只包含题目内容和答案，options字段为空
   - 单词题：英语单词练习，可能包含释义、例句等

3. **数据关联**:
   - 与goals表通过goal_id建立外键关联
   - 删除目标时，相关题目也会被级联删除

---

## 表关系

### 外键关系

- `goals.user_id` → `user_info.user_id` (多对一关系)
  - 一个用户可以有多个学习目标
  - 每个学习目标只属于一个用户

- `goal_of_detail.goal_id` → `goals.goal_id` (多对一关系)
  - 一个学习目标可以包含多个题目
  - 每个题目只属于一个学习目标
  - 支持级联删除：删除目标时自动删除相关题目

### 索引建议

为了提高查询性能，建议创建以下索引：

```sql
-- 用户表索引
CREATE INDEX idx_user_username ON user_info(username);
CREATE INDEX idx_user_create_time ON user_info(create_time);

-- 目标表索引
CREATE INDEX idx_goal_user_id ON goals(user_id);
CREATE INDEX idx_goal_status ON goals(status);
CREATE INDEX idx_goal_subject ON goals(subject);
CREATE INDEX idx_goal_create_time ON goals(create_time);
CREATE INDEX idx_goal_user_status ON goals(user_id, status);

-- 目标详情表索引
CREATE INDEX idx_detail_goal_id ON goal_of_detail(goal_id);
CREATE INDEX idx_detail_subject ON goal_of_detail(subject);
CREATE INDEX idx_detail_content_type ON goal_of_detail(content_type);
CREATE INDEX idx_detail_difficulty ON goal_of_detail(difficulty);
CREATE INDEX idx_detail_create_time ON goal_of_detail(create_time);
CREATE INDEX idx_detail_goal_type ON goal_of_detail(goal_id, content_type);}}}
```

---

## 数据初始化

系统启动时会自动初始化测试数据，包括：

### 默认用户
- 用户1: username="student1", grade="初中一年级"
- 用户2: username="student2", grade="高中二年级"
- 用户3: username="teacher1", grade="教师"
- 用户4: username="parent1", grade="家长"

### 示例目标
系统会为测试用户创建一些示例学习目标，涵盖不同学科和难度等级。

---

## 维护说明

1. **数据备份**: H2数据库文件位于 `data/testdb.mv.db`，定期备份此文件
2. **日志监控**: 所有数据库操作都有详细日志记录
3. **性能优化**: 根据查询模式适当添加索引
4. **数据清理**: 定期清理过期的已完成目标数据

---

## 版本历史

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| 1.0 | 2025-01-29 | 初始版本，创建用户表和目标表 | 系统 |
| 1.1 | 2025-01-29 | 新增目标详情表(goal_of_detail)，支持AI出题功能 | 系统 |

---

*最后更新时间: 2025-01-29*