# 数据库设计文档

## 一、数据库概览

| 项目 | 说明 |
|------|------|
| 数据库名称 | `wordbook` |
| 字符集 | `utf8mb4` |
| 排序规则 | `utf8mb4_unicode_ci` |
| 存储引擎 | `InnoDB` |

## 二、ER 图

```mermaid
erDiagram
    USER ||--|{ WORD : has
    USER {
        uuid id PK "用户ID"
        string username UK "用户名"
        string password "密码(hash)"
        datetime created_at "创建时间"
        datetime updated_at "更新时间"
        datetime deleted_at "删除时间(软删除)"
    }
    WORD {
        uuid id PK "单词记录ID"
        uuid user_id FK "所属用户ID"
        string word "单词"
        text definition "释义"
        json examples "例句列表"
        string ai_provider "AI模型来源"
        datetime created_at "创建时间"
        datetime updated_at "更新时间"
        datetime deleted_at "删除时间(软删除)"
    }
```

## 三、数据表详情

### 3.1 用户表 (users)

| 用户表名 | `users` |
|----------|---------|

| 字段名 | 数据类型 | 约束 | 索引 | 说明 |
|--------|----------|------|------|------|
| `id` | CHAR(36) | PRIMARY KEY | - | 用户唯一标识符（UUID 格式） |
| `username` | VARCHAR(50) | NOT NULL, UNIQUE | UNIQUE KEY | 用户名，全局唯一，用于登录 |
| `password` | VARCHAR(255) | NOT NULL | - | 用户密码，存储 bcrypt 哈希值，严禁明文存储 |
| `created_at` | DATETIME | DEFAULT CURRENT_TIMESTAMP | - | 账户创建时间 |
| `updated_at` | DATETIME | ON UPDATE CURRENT_TIMESTAMP | - | 账户最后更新时间 |
| `deleted_at` | DATETIME | DEFAULT NULL | INDEX | 软删除标记，NULL 表示未删除 |

**索引设计：**
- 主键索引：`id`
- 唯一索引：`username`（防止重复注册）

### 3.2 单词记录表 (words)

| 单词表名 | `words` |
|-----------|---------|

| 字段名           | 数据类型         | 约束                          | 索引                        | 说明                                         |
| ------------- | ------------ | --------------------------- | ------------------------- | ------------------------------------------ |
| `id`          | CHAR(36)     | PRIMARY KEY                 | -                         | 单词记录唯一标识符（UUID 格式）                         |
| `user_id`     | CHAR(36)     | NOT NULL, FOREIGN KEY       | -                         | 所属用户 ID，关联 users.id                        |
| `word`        | VARCHAR(100) | NOT NULL                    | INDEX idx_word_search(20) | 单词文本，支持前缀搜索优化                              |
| `definition`  | TEXT         | NOT NULL                    | -                         | AI 生成的单词释义                                 |
| `examples`    | JSON         | NOT NULL                    | -                         | 例句列表，存储 JSON 数组格式                          |
| `ai_provider` | ENUM         | NOT NULL                    | -                         | AI 模型来源标识（`deepseek`=DeepSeek，`qwen`=通义千问） |
| `created_at`  | DATETIME     | DEFAULT CURRENT_TIMESTAMP   | -                         | 单词记录创建时间                                   |
| `updated_at`  | DATETIME     | ON UPDATE CURRENT_TIMESTAMP | -                         | 单词记录最后更新时间                                 |
| `deleted_at`  | DATETIME     | DEFAULT NULL                | INDEX idx_user_word       | 软删除标记                                      |

**索引设计：**
- 主键索引：`id`
- 外键索引：`user_id`（自动创建）
- 唯一索引：`uk_user_word` (user_id, word(50)) - 防止同一用户保存重复单词
- 复合索引：`idx_user_word` (user_id, deleted_at) - 优化用户单词列表分页查询
- 前缀索引：`idx_word_search` (word(20)) - 支持单词前缀搜索优化

## 四、表关联关系

### 4.1 用户与单词的关系

```
用户 (users)  1  ----  N  单词记录 (words)
```

- **关系类型**：一对多
- **外键约束**：`words.user_id` → `users.id`
- **级联规则**：`ON DELETE CASCADE`
  - 当用户被删除时，该用户的所有单词记录也会被自动删除

### 4.2 关联查询示例

```sql
-- 查询某用户的所有单词（排除已删除）
SELECT * FROM words
WHERE user_id = ? AND deleted_at IS NULL
ORDER BY created_at DESC
LIMIT ? OFFSET ?;

-- 联表查询用户信息及单词数量
SELECT u.id, u.username, COUNT(w.id) as word_count
FROM users u
LEFT JOIN words w ON u.id = w.user_id AND w.deleted_at IS NULL
WHERE u.deleted_at IS NULL
GROUP BY u.id;
```

### 4.2 唯一约束说明

`uk_user_word` 约束确保同一用户不能保存相同的单词两次：
- **触发场景**：在"手动保存单词"时
- **业务逻辑**：前端应先调用"智能查询单词"接口检查是否已保存，避免触发重复错误
- **不触发场景**："智能查询单词"接口只查询不保存，不会触发此约束

## 五、核心业务 SQL 查询示例

### 5.1 智能查询单词

**业务逻辑**：先检查数据库，未命中则调用 AI（不保存）

```sql
-- 查询：检查用户是否已保存该单词
SELECT id, word, definition, examples, ai_provider
FROM words
WHERE user_id = ? AND word = ? AND deleted_at IS NULL;
```

### 5.2 手动保存单词

**业务逻辑**：将 AI 返回的结果写入数据库

```sql
-- 插入：保存单词记录（受 uk_user_word 唯一约束保护）
INSERT INTO words (id, user_id, word, definition, examples, ai_provider)
VALUES (?, ?, ?, ?, ?, ?);
```

### 5.3 获取单词列表（分页）

**业务逻辑**：获取用户所有已保存的单词，支持分页

```sql
-- 查询：分页获取单词列表（按创建时间倒序）
SELECT id, word, definition, examples, ai_provider, created_at
FROM words
WHERE user_id = ? AND deleted_at IS NULL
ORDER BY created_at DESC
LIMIT ? OFFSET ?;

-- 计算总数（用于分页器）
SELECT COUNT(*) as total
FROM words
WHERE user_id = ? AND deleted_at IS NULL;
```

### 5.4 删除单词（软删除）

**业务逻辑**：根据单词 ID 软删除记录

```sql
-- 更新：软删除单词记录
UPDATE words
SET deleted_at = CURRENT_TIMESTAMP, updated_at = CURRENT_TIMESTAMP
WHERE id = ? AND user_id = ? AND deleted_at IS NULL;
```

## 六、索引优化说明

### 6.1 查询场景分析

| 查询场景 | 涉及字段 | 索引策略 |
|----------|----------|----------|
| 用户登录 | username | UNIQUE KEY |
| 智能查询单词 | user_id, word, deleted_at | uk_user_word（唯一约束） |
| 用户单词列表（分页） | user_id, deleted_at | 复合索引 idx_user_word |
| 单词搜索 | word | 前缀索引 idx_word_search |
| 按用户 ID 查找单词 | user_id | 外键自动索引 |

### 6.2 示例 JSON 数据结构 (examples 字段)

```json
[
  "The word 'serendipity' means finding something good without looking for it.",
  "It was pure serendipity that I met my best friend at the coffee shop.",
  "Many scientific discoveries are the result of serendipity."
]
```

## 七、数据初始化

数据库初始化脚本位于 `docs/init.sql`，该脚本会在 Docker Compose 启动 MySQL 容器时自动执行。

**严禁使用 GORM 的 `AutoMigrate` 功能进行建表，必须通过此 SQL 脚本初始化数据库。**