# 字词学习平台 - 数据库设计文档

## 1. 数据库选型

### 1.1 推荐方案：PostgreSQL

**选择理由：**
- ✅ **关系型数据优势**：字词、关联关系、用户等数据具有强关联性，适合关系型数据库
- ✅ **JSON 支持**：PostgreSQL 原生支持 JSON/JSONB，可以灵活存储 SVG 数据
- ✅ **全文搜索**：内置全文搜索功能，适合字词搜索场景
- ✅ **扩展性强**：支持数组类型，适合存储多个拼音、多个读音等
- ✅ **成熟稳定**：企业级数据库，性能优秀
- ✅ **开源免费**：成本可控

### 1.2 备选方案

**MySQL 8.0+**
- 优势：生态成熟，使用广泛
- 劣势：JSON 支持不如 PostgreSQL 完善

**MongoDB**
- 优势：文档型数据库，灵活性强
- 劣势：关联查询复杂，不适合强关联关系场景

## 2. 数据库分离设计

### 2.1 核心设计思路

**字和词分离为两个独立的数据库**

**设计原则：**
1. ✅ **汉字数据库**：专门存储汉字相关数据，包含汉字的特有属性（笔画、结构、部首等）
2. ✅ **词语数据库**：专门存储词语相关数据，包含词语的组成和关联关系
3. ✅ **数据隔离**：字和词的数据结构差异较大，分离后更便于管理和优化
4. ✅ **扩展性好**：后续如需支持英语单词，可单独设计英语数据库

**注意：**
- 英语展示不考虑和汉字放在一个库
- 当前版本先完成汉字数据库的设计和实现
- 词语数据库表暂时设计，后续实现

## 3. 汉字数据库设计

### 3.1 汉字主表 (chars)

存储汉字的基础信息。

```sql
CREATE TABLE chars (
  id BIGSERIAL PRIMARY KEY,
  char VARCHAR(10) NOT NULL UNIQUE COMMENT '汉字内容，如"中"',
  strokes INT NOT NULL COMMENT '笔画数',
  pinyin TEXT[] NOT NULL COMMENT '拼音数组，支持多音字，如["zhōng", "zhòng"]',
  radicals VARCHAR(10) COMMENT '偏旁部首',
  frequency INT COMMENT '使用频率: 0(最常用), 1(较常用), 2(次常用), 3(二级字), 4(三级字), 5(生僻字)',
  structure VARCHAR(10) COMMENT '汉字结构代码，如"D0"(独体结构), "H2"(左窄右宽)等',
  traditional VARCHAR(50) COMMENT '繁体字写法，可能有多个，用逗号分隔',
  stroke_data JSONB COMMENT '笔画数据，JSON格式，存储笔画顺序和路径信息',
  grade INT COMMENT '年级: 0-9，NULL表示未设置',
  description TEXT COMMENT '描述信息',
  status VARCHAR(20) DEFAULT 'active' COMMENT '状态: active(启用), inactive(禁用)',
  
  -- 索引
  INDEX idx_char (char),
  INDEX idx_strokes (strokes),
  INDEX idx_pinyin (pinyin),
  INDEX idx_radicals (radicals),
  INDEX idx_frequency (frequency),
  INDEX idx_structure (structure),
  INDEX idx_grade (grade),
  INDEX idx_status (status)
);

-- 全文搜索索引
CREATE INDEX idx_char_fulltext ON chars USING GIN (to_tsvector('simple', char));
```

**字段说明：**
- `char`: 汉字内容，唯一不重复，如"中"
- `strokes`: 笔画数，整数类型
- `pinyin`: PostgreSQL 数组类型，存储多个拼音，支持多音字
- `radicals`: 偏旁部首，如"中"的部首是"丨"
- `frequency`: 使用频率，0为最常用，1为较常用，2为次常用，3为二级字，4为三级字，5为不在《通用规范汉字》的生僻字
- `structure`: 汉字结构代码，参考结构代码表（见 `structure_codes.json`），如"D0"(独体结构)、"H2"(左窄右宽)等
- `traditional`: 繁体字写法，可能有多个，用逗号分隔，如"乾幹"
- `stroke_data`: JSONB 类型，存储笔画数据，包含笔画顺序和路径信息（原 svg_data 字段）
- `grade`: 年级，0-9年级，NULL 表示未设置
- `status`: 启用/禁用状态，支持软删除

**说明：** 音频文件已迁移至 `char_readings` 表，按音义项分别存储。

**结构代码说明：**
- 结构代码定义见 `structure_codes.json` 文件
- 常见结构代码：D0(独体结构)、D1(镶嵌结构)、B1-B4(上下结构)、H1-H3(左右结构)、R1-R6(半包围结构)等

### 3.2 汉字音义项表 (char_readings)

存储每个汉字在不同读音/含义下的信息，支持多音字、多义字。单音字一条记录，多音字/同音多义字多条记录。

```sql
CREATE TABLE char_readings (
  id BIGSERIAL PRIMARY KEY,
  char_id BIGINT NOT NULL,
  pinyin VARCHAR(20) NOT NULL COMMENT '读音，如 zhōng、zhòng',
  meaning VARCHAR(200) COMMENT '义项说明，同音多义时用于区分，如"中间；中心"、"击中；符合"',
  introduce TEXT NOT NULL COMMENT '该音义项下的提示语',
  audio_file_ref VARCHAR(500) COMMENT '音频相对路径，与配置中的 base URL 拼接，如 audio/chars/中/zhōng.mp3',
  image_file_ref VARCHAR(500) COMMENT '图片相对路径，可选，幼小低年级字才有释义图',
  sort_order INT DEFAULT 0 COMMENT '排序，常用音义可放前面',
  
  FOREIGN KEY (char_id) REFERENCES chars(id) ON DELETE CASCADE,
  INDEX idx_char_id (char_id),
  INDEX idx_pinyin (pinyin),
  INDEX idx_char_pinyin (char_id, pinyin)
);
```

**字段说明：**
- `char_id`: 关联的汉字ID
- `pinyin`: 该音义项的读音
- `meaning`: 义项说明，同音多义时用于区分
- `introduce`: 该音义项下的提示语（如"中，中间的中"）
- `audio_file_ref`: 音频相对路径，采用 relative 方案，与配置中的 base URL 拼接成完整地址
- `image_file_ref`: 图片相对路径，可选，仅部分字（如幼小低年级需掌握的字）有此字段
- `sort_order`: 排序，常用音义优先展示

**路径约定：**
- 音频、图片均使用 relative 方案，数据库仅存相对路径
- base URL 在应用配置中维护，迁移 CDN/域名时无需更新数据库
- 示例：`audio_file_ref = "audio/chars/中/zhōng.mp3"`，完整地址 = `{base_url}/{audio_file_ref}`

### 3.3 汉字图片表 (char_images)

存储汉字字形相关图片（原图、标准图等，与读音无关）。

```sql
CREATE TABLE char_images (
  id BIGSERIAL PRIMARY KEY,
  char_id BIGINT NOT NULL COMMENT '关联的汉字ID',
  image_type VARCHAR(20) NOT NULL COMMENT '图片类型: original(原图), standard(标准图)',
  file_path VARCHAR(500) NOT NULL COMMENT '图片文件路径',
  file_name VARCHAR(200) NOT NULL COMMENT '原始文件名',
  file_size BIGINT COMMENT '文件大小(字节)',
  width INT COMMENT '图片宽度',
  height INT COMMENT '图片高度',
  mime_type VARCHAR(50) COMMENT 'MIME类型',
  is_primary BOOLEAN DEFAULT FALSE COMMENT '是否为主图',
  sort_order INT DEFAULT 0 COMMENT '排序顺序',
  
  FOREIGN KEY (char_id) REFERENCES chars(id) ON DELETE CASCADE,
  INDEX idx_char_id (char_id),
  INDEX idx_image_type (image_type),
  INDEX idx_is_primary (is_primary)
);
```

**字段说明：**
- `char_id`: 关联的汉字ID
- `image_type`: 区分原图和标准图
- `file_path`: 图片存储路径
- `is_primary`: 标记主图，用于列表展示
- `sort_order`: 排序字段，支持多图排序

### 3.4 汉字关联表 (char_relations)

存储汉字之间的关联关系（如形近字、同音字等）。

```sql
CREATE TABLE char_relations (
  id BIGSERIAL PRIMARY KEY,
  source_char_id BIGINT NOT NULL COMMENT '源汉字ID',
  target_char_id BIGINT NOT NULL COMMENT '目标汉字ID',
  relation_type VARCHAR(20) NOT NULL COMMENT '关联类型: similar_shape(形近字), same_pinyin(同音字), same_radical(同部首), similar_structure(同结构)',
  sort_order INT DEFAULT 0 COMMENT '排序顺序',
  
  FOREIGN KEY (source_char_id) REFERENCES chars(id) ON DELETE CASCADE,
  FOREIGN KEY (target_char_id) REFERENCES chars(id) ON DELETE CASCADE,
  UNIQUE (source_char_id, target_char_id, relation_type),
  INDEX idx_source_char (source_char_id),
  INDEX idx_target_char (target_char_id),
  INDEX idx_relation_type (relation_type)
);
```

**关联类型说明：**
- `similar_shape`: 形近字，如"人"和"入"
- `same_pinyin`: 同音字，如"中"和"钟"
- `same_radical`: 同部首，如"中"和"串"
- `similar_structure`: 同结构，如都是左右结构

### 3.5 句子表 (sentences)

存储字词关联的例句。

```sql
CREATE TABLE sentences (
  id BIGSERIAL PRIMARY KEY,
  content TEXT NOT NULL COMMENT '句子内容',
  translation TEXT COMMENT '翻译（英语句子需要）',
  audio_path VARCHAR(500) COMMENT '音频文件路径',
  source VARCHAR(100) COMMENT '来源，如教材名称',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  INDEX idx_content_fulltext (to_tsvector('simple', content))
);
```

### 3.6 汉字-句子关联表 (char_sentences)

存储汉字和句子的关联关系。

```sql
CREATE TABLE char_sentences (
  id BIGSERIAL PRIMARY KEY,
  char_id BIGINT NOT NULL COMMENT '汉字ID',
  sentence_id BIGINT NOT NULL COMMENT '句子ID',
  sort_order INT DEFAULT 0 COMMENT '排序顺序',
  
  FOREIGN KEY (char_id) REFERENCES chars(id) ON DELETE CASCADE,
  FOREIGN KEY (sentence_id) REFERENCES sentences(id) ON DELETE CASCADE,
  UNIQUE (char_id, sentence_id),
  INDEX idx_char_id (char_id),
  INDEX idx_sentence_id (sentence_id)
);
```

### 3.7 用户表 (users)

存储管理员用户信息。

```sql
CREATE TABLE users (
  id BIGSERIAL PRIMARY KEY,
  username VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名',
  email VARCHAR(100) UNIQUE COMMENT '邮箱',
  password_hash VARCHAR(255) NOT NULL COMMENT '密码哈希',
  role VARCHAR(20) NOT NULL DEFAULT 'admin' COMMENT '角色: super_admin(超级管理员), admin(一般管理员)',
  real_name VARCHAR(50) COMMENT '真实姓名',
  avatar VARCHAR(500) COMMENT '头像URL',
  status VARCHAR(20) DEFAULT 'active' COMMENT '状态: active(启用), inactive(禁用)',
  last_login_at TIMESTAMP COMMENT '最后登录时间',
  last_login_ip VARCHAR(50) COMMENT '最后登录IP',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  INDEX idx_username (username),
  INDEX idx_email (email),
  INDEX idx_role (role),
  INDEX idx_status (status)
);
```

### 3.8 操作日志表 (operation_logs)

记录用户操作日志，用于审计。

```sql
CREATE TABLE operation_logs (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT COMMENT '操作用户ID',
  action VARCHAR(50) NOT NULL COMMENT '操作类型: create, update, delete, upload等',
  resource_type VARCHAR(50) NOT NULL COMMENT '资源类型: word, image, sentence等',
  resource_id BIGINT COMMENT '资源ID',
  description TEXT COMMENT '操作描述',
  ip_address VARCHAR(50) COMMENT 'IP地址',
  user_agent TEXT COMMENT '用户代理',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE SET NULL,
  INDEX idx_user_id (user_id),
  INDEX idx_action (action),
  INDEX idx_resource (resource_type, resource_id),
  INDEX idx_created_at (created_at)
);
```

## 4. 词语数据库设计（暂时设计）

### 4.1 词语主表 (chinese_words)

存储词语的基础信息。

```sql
CREATE TABLE chinese_words (
  id BIGSERIAL PRIMARY KEY,
  word VARCHAR(100) NOT NULL UNIQUE COMMENT '词语内容，如"中国"',
  pinyin TEXT[] COMMENT '拼音数组，如["zhōng", "guó"]',
  grade INT COMMENT '年级: 0-9，NULL表示未设置',
  description TEXT COMMENT '词语解释',
  audios TEXT[] COMMENT '音频文件路径数组',
  status VARCHAR(20) DEFAULT 'active' COMMENT '状态: active(启用), inactive(禁用)',
  
  -- 索引
  INDEX idx_word (word),
  INDEX idx_grade (grade),
  INDEX idx_status (status)
);

-- 全文搜索索引
CREATE INDEX idx_word_fulltext ON chinese_words USING GIN (to_tsvector('simple', word));
```

### 4.2 词语-汉字关联表 (word_characters)

存储词语和组成汉字的关联关系。

```sql
CREATE TABLE word_characters (
  id BIGSERIAL PRIMARY KEY,
  word_id BIGINT NOT NULL COMMENT '词语ID',
  char_id BIGINT NOT NULL COMMENT '汉字ID（关联到汉字数据库）',
  position INT NOT NULL COMMENT '汉字在词语中的位置，从1开始',
  
  FOREIGN KEY (word_id) REFERENCES chinese_words(id) ON DELETE CASCADE,
  INDEX idx_word_id (word_id),
  INDEX idx_char_id (char_id),
  INDEX idx_position (position)
);
```

**注意：** 词语数据库和汉字数据库是分离的，`char_id` 字段存储的是汉字数据库中的汉字ID，需要通过跨库查询或应用层关联。

### 4.3 词语图片表 (word_images)

存储词语关联的图片信息。

```sql
CREATE TABLE word_images (
  id BIGSERIAL PRIMARY KEY,
  word_id BIGINT NOT NULL COMMENT '关联的词语ID',
  image_type VARCHAR(20) NOT NULL COMMENT '图片类型: original(原图), standard(标准图)',
  file_path VARCHAR(500) NOT NULL COMMENT '图片文件路径',
  file_name VARCHAR(200) NOT NULL COMMENT '原始文件名',
  file_size BIGINT COMMENT '文件大小(字节)',
  width INT COMMENT '图片宽度',
  height INT COMMENT '图片高度',
  mime_type VARCHAR(50) COMMENT 'MIME类型',
  is_primary BOOLEAN DEFAULT FALSE COMMENT '是否为主图',
  sort_order INT DEFAULT 0 COMMENT '排序顺序',
  
  FOREIGN KEY (word_id) REFERENCES chinese_words(id) ON DELETE CASCADE,
  INDEX idx_word_id (word_id),
  INDEX idx_image_type (image_type),
  INDEX idx_is_primary (is_primary)
);
```

### 4.4 词语-句子关联表 (word_sentences)

存储词语和句子的关联关系。

```sql
CREATE TABLE word_sentences (
  id BIGSERIAL PRIMARY KEY,
  word_id BIGINT NOT NULL COMMENT '词语ID',
  sentence_id BIGINT NOT NULL COMMENT '句子ID',
  sort_order INT DEFAULT 0 COMMENT '排序顺序',
  
  FOREIGN KEY (word_id) REFERENCES chinese_words(id) ON DELETE CASCADE,
  FOREIGN KEY (sentence_id) REFERENCES sentences(id) ON DELETE CASCADE,
  UNIQUE (word_id, sentence_id),
  INDEX idx_word_id (word_id),
  INDEX idx_sentence_id (sentence_id)
);
```

## 5. 数据库关系图

### 5.1 汉字数据库关系图

```
chars (汉字主表)
  ├── char_readings (音义项表) - 一对多，支持多音字、多义字
  ├── char_images (字形图片表) - 一对多
  ├── char_relations (汉字关联) - 自关联（多对多）
  ├── char_sentences (汉字-句子关联) - 多对多
  └── operation_logs (操作日志) - 关联资源

char_readings (音义项表)
  └── 存储 introduce、audio_file_ref、image_file_ref 等按读音/义项区分的数据

sentences (句子表)
  └── char_sentences (汉字-句子关联) - 多对多
```

### 5.2 词语数据库关系图

```
chinese_words (词语主表)
  ├── word_characters (词语-汉字关联) - 多对多（跨库关联）
  ├── word_images (图片表) - 一对多
  ├── word_sentences (词语-句子关联) - 多对多
  └── operation_logs (操作日志) - 关联资源

sentences (句子表)
  └── word_sentences (词语-句子关联) - 多对多
```

### 5.3 公共表

```
users (用户表)
  └── operation_logs (操作日志) - 一对多

sentences (句子表)
  ├── char_sentences (汉字-句子关联) - 多对多
  └── word_sentences (词语-句子关联) - 多对多
```

## 6. 索引优化建议

### 6.1 汉字数据库查询优化索引
- 汉字内容索引：支持快速查找
- 笔画数索引：支持按笔画数筛选
- 拼音索引：支持按拼音查找
- 部首索引：支持按部首查找
- 结构代码索引：支持按结构筛选
- 频率索引：支持按使用频率筛选
- 全文搜索索引：支持模糊搜索

### 6.2 词语数据库查询优化索引
- 词语内容索引：支持快速查找
- 年级索引：支持按年级筛选
- 全文搜索索引：支持模糊搜索

### 6.3 关联查询优化
- 外键索引：所有外键字段建立索引
- 关联表索引：char_readings、char_relations、char_sentences、word_characters、word_sentences 的关联字段索引

## 7. 数据迁移策略

### 7.1 初始化数据
- 创建默认超级管理员账户
- 初始化年级数据字典（可选）
- 导入汉字结构代码数据（structure_codes.json）

### 7.2 数据导入
- 支持批量导入汉字数据（参考 char_common_base.json 格式）
- 支持批量导入音义项数据（参考 char_introduce.json，需按多音/多义拆分为多条 char_readings）
- 支持批量导入词语数据
- 支持 CSV/Excel 格式导入

### 7.3 数据迁移注意事项
- 从旧的 words 表迁移到 chars 表时，需要：
  - 将 `content` 字段映射到 `char` 字段
  - 将 `svg_data` 字段重命名为 `stroke_data`
  - 补充 `strokes`、`pinyin`、`radicals`、`frequency`、`structure`、`traditional` 字段
  - 过滤出 `type = 'chinese_char'` 的数据
- 从 char_introduce.json 迁移到 char_readings 时，需要：
  - 单音字：每条 JSON 对应一条 char_readings 记录
  - 多音字/多义字：需人工或脚本标注拆分，每个音义项一条 char_readings 记录

## 8. 数据备份策略

### 8.1 备份方案
- 每日全量备份
- 实时增量备份（可选）
- 汉字数据库和词语数据库分别备份

### 8.2 恢复方案
- 支持时间点恢复
- 定期恢复演练

## 9. 性能优化建议

### 9.1 查询优化
- 使用连接池管理数据库连接
- 复杂查询使用视图或物化视图
- 合理使用缓存（Redis）
- 跨库查询（词语-汉字关联）建议在应用层实现，避免跨库JOIN

### 9.2 数据量预估
- 汉字数据：预计 8,000+ 条（通用规范汉字表）
- 音义项数据：预计 10,000～12,000 条（多音字对应多条记录）
- 词语数据：预计 10,000+ 条
- 图片数据：预计 50,000+ 条
- 关联关系：预计 100,000+ 条

### 9.3 分表策略（如需要）
- 当 chars 表数据量超过 100 万时，考虑按频率分表
- 当 chinese_words 表数据量超过 100 万时，考虑按年级分表
- 使用 PostgreSQL 分区功能