# 数据库表文档

本文档记录了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 | - | 创建时间 |
| complete_time | TIMESTAMP | - | NULL | - | - | 完成时间 |
| answer_duration | INT | - | NULL | 0 | - | 答题时长（秒） |

### 字段详细说明

- **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**: 目标创建时间，默认为当前时间
- **complete_time**: 目标完成时间，当目标状态变为已完成时自动设置
- **answer_duration**: 答题时长，记录用户在答题页面的总停留时间，单位为秒，每次提交答案时累加

### 业务规则

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建立外键关联
   - 删除目标时，相关题目也会被级联删除

---

## 3. 用户答题记录表 (user_answer)

### 表说明
存储用户在学习过程中的答题记录，包括用户答案、正确性、用时等信息，用于学习进度跟踪和统计分析。

### 表结构

| 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 主键 | 说明 |
|--------|----------|------|----------|--------|------|------|
| answer_id | BIGINT | - | NOT NULL | AUTO_INCREMENT | ✓ | 记录ID，主键，自增 |
| user_id | BIGINT | - | NOT NULL | - | - | 用户ID，外键关联user_info表 |
| goal_id | BIGINT | - | NOT NULL | - | - | 目标ID，外键关联goals表 |
| content_id | BIGINT | - | NOT NULL | - | - | 题目ID，外键关联goal_of_detail表 |
| user_answer | TEXT | - | NULL | - | - | 用户提交的答案 |
| is_correct | TINYINT | - | NULL | - | - | 是否正确（0-错误，1-正确） |
| spend_time | INT | - | NULL | - | - | 单题用时（秒） |
| answer_time | TIMESTAMP | - | NULL | CURRENT_TIMESTAMP | - | 答题时间，自动设置 |

### 字段详细说明

- **answer_id**: 答题记录唯一标识符，系统自动生成
- **user_id**: 关联的用户ID，外键引用user_info表的user_id
- **goal_id**: 关联的学习目标ID，外键引用goals表的goal_id
- **content_id**: 关联的题目ID，外键引用goal_of_detail表的detail_id
- **user_answer**: 用户提交的答案内容，支持文本格式
- **is_correct**: 答案正确性标识：
  - `0`: 错误
  - `1`: 正确
  - `NULL`: 未评判
- **spend_time**: 用户答题用时，单位为秒，用于分析答题效率
- **answer_time**: 答题提交时间，默认为当前时间戳

### 业务规则

1. **答题记录创建**:
   - 用户提交答案时自动创建记录
   - 系统自动判断答案正确性并设置is_correct字段
   - 记录答题用时用于后续分析

2. **数据统计**:
   - 支持按用户、目标、时间范围等维度统计答题情况
   - 计算正确率、平均用时等学习指标
   - 生成学习报告和进度分析

3. **数据关联**:
   - 与用户表、目标表、题目表建立外键关联
   - 支持级联查询获取完整的答题上下文信息

---

## 表关系

### 外键关系

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

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

- `user_answer.user_id` → `user_info.user_id` (多对一关系)
  - 一个用户可以有多个答题记录
  - 每个答题记录只属于一个用户

- `user_answer.goal_id` → `goals.goal_id` (多对一关系)
  - 一个目标可以有多个答题记录
  - 每个答题记录只属于一个目标

- `user_answer.content_id` → `goal_of_detail.detail_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. **数据清理**: 定期清理过期的已完成目标数据

---

## 4. 学习报告表 (study_report)

### 表说明
存储用户学习报告信息，包括学习统计数据、知识点分析、难度分析等，用于生成详细的学习报告。

### 表结构

| 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 主键 | 说明 |
|--------|----------|------|----------|--------|------|------|
| report_id | BIGINT | - | NOT NULL | AUTO_INCREMENT | ✓ | 报告ID，主键，自增 |
| goal_id | BIGINT | - | NOT NULL | - | - | 目标ID，外键关联goals表 |
| user_id | BIGINT | - | NOT NULL | - | - | 用户ID，外键关联user_info表 |
| generate_time | TIMESTAMP | - | NOT NULL | CURRENT_TIMESTAMP | - | 报告生成时间 |
| accuracy | DECIMAL | 5,2 | NULL | - | - | 正确率（百分比） |
| knowledge_analysis | TEXT | - | NULL | - | - | 知识点分析，JSON格式存储 |
| difficulty_analysis | TEXT | - | NULL | - | - | 难度分析，JSON格式存储 |
| share_url | VARCHAR | 255 | NULL | - | - | 分享链接 |

### 字段详细说明

- **report_id**: 学习报告唯一标识符，系统自动生成
- **goal_id**: 关联的学习目标ID，外键引用goals表的goal_id
- **user_id**: 关联的用户ID，外键引用user_info表的user_id
- **generate_time**: 报告生成时间，默认为当前时间戳
- **accuracy**: 学习正确率，范围0-100，保留两位小数
- **knowledge_analysis**: 知识点分析数据，JSON格式存储各知识点的掌握情况
- **difficulty_analysis**: 难度分析数据，JSON格式存储各难度等级的表现情况
- **share_url**: 报告分享链接，用于分享学习成果

### 业务规则

1. **报告生成规则**:
   - 目标完成后自动生成学习报告
   - 根据答题记录统计正确率和分析数据
   - 支持手动重新生成报告

2. **数据分析**:
   - 知识点分析：统计各知识点的答题情况和掌握程度
   - 难度分析：分析不同难度题目的正确率和用时
   - 学习趋势：记录学习进步情况

3. **数据关联**:
   - 与目标表、用户表建立外键关联
   - 支持级联查询获取完整的报告上下文信息

---

## 5. AI对话记录表 (ai_chat)

### 表说明
存储用户与AI助手的对话记录，支持学习指导、答疑解惑等功能。

### 表结构

| 字段名 | 数据类型 | 长度 | 是否为空 | 默认值 | 主键 | 说明 |
|--------|----------|------|----------|--------|------|------|
| chat_id | BIGINT | - | NOT NULL | AUTO_INCREMENT | ✓ | 对话ID，主键，自增 |
| user_id | BIGINT | - | NOT NULL | - | - | 用户ID，外键关联user_info表 |
| content | TEXT | - | NOT NULL | - | - | 消息内容 |
| type | TINYINT | - | NOT NULL | - | - | 消息类型（0-用户，1-AI） |
| timestamp | TIMESTAMP | - | NOT NULL | CURRENT_TIMESTAMP | - | 消息时间戳 |

### 字段详细说明

- **chat_id**: 对话记录唯一标识符，系统自动生成
- **user_id**: 关联的用户ID，外键引用user_info表的user_id
- **content**: 消息的具体内容，支持文本格式
- **type**: 消息类型标识：
  - `0`: 用户发送的消息
  - `1`: AI回复的消息
- **timestamp**: 消息发送时间，默认为当前时间戳

### 业务规则

1. **对话管理**:
   - 支持实时对话交互
   - 保存完整的对话历史记录
   - 支持对话记录的查询和清理

2. **AI集成**:
   - 集成DeepSeek大模型提供智能回复
   - 支持学习指导和问题解答
   - 提供个性化的学习建议

3. **数据关联**:
   - 与用户表建立外键关联
   - 支持按用户查询对话记录

---

## 版本历史

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| 1.0 | 2025-01-29 | 初始版本，创建用户表和目标表 | 系统 |
| 1.1 | 2025-01-29 | 新增目标详情表(goal_of_detail)，支持AI出题功能 | 系统 |
| 1.2 | 2025-01-29 | 新增用户答题记录表(user_answer)，支持答题记录和统计分析 | 系统 |
| 1.3 | 2025-01-29 | 为goals表新增complete_time字段，记录目标完成时间 | 系统 |
| 1.4 | 2025-01-29 | 为goals表新增answer_duration字段，记录用户答题时长 | 系统 |
| 1.5 | 2025-01-30 | 新增学习报告表(study_report)，支持学习报告生成和分享功能 | 系统 |
| 1.6 | 2025-01-30 | 新增AI对话记录表(ai_chat)，支持AI助手对话功能 | 系统 |
| 1.7 | 2025-01-30 | 完善学习报告详情页面，支持知识点分布和难度分析 | 系统 |

---

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