joey5628/platform-pipi

Fork 0

Files

T

R524809 3569961115 feat: 汉字介绍待续

2026-02-09 13:30:43 +08:00

17 KiB

Raw Blame History

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

1. 数据库选型

1.1 推荐方案：PostgreSQL

选择理由：

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

1.2 备选方案

MySQL 8.0+

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

MongoDB

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

2. 数据库分离设计

2.1 核心设计思路

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

设计原则：

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

注意：

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

3. 汉字数据库设计

3.1 汉字主表 (chars)

存储汉字的基础信息。

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)

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

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)

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

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)

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

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)

存储字词关联的例句。

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)

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

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)

存储管理员用户信息。

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)

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

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)

存储词语的基础信息。

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)

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

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)

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

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)

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

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 分区功能

17 KiB Raw Blame History Unescape Escape

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

1. 数据库选型

1.1 推荐方案：PostgreSQL

1.2 备选方案

2. 数据库分离设计

2.1 核心设计思路

3. 汉字数据库设计

3.1 汉字主表 (chars)

3.2 汉字音义项表 (char_readings)

3.3 汉字图片表 (char_images)

3.4 汉字关联表 (char_relations)

3.5 句子表 (sentences)

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

3.7 用户表 (users)

3.8 操作日志表 (operation_logs)

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

4.1 词语主表 (chinese_words)

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

4.3 词语图片表 (word_images)

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

5. 数据库关系图

5.1 汉字数据库关系图

5.2 词语数据库关系图

5.3 公共表

6. 索引优化建议

6.1 汉字数据库查询优化索引

6.2 词语数据库查询优化索引

6.3 关联查询优化

7. 数据迁移策略

7.1 初始化数据

7.2 数据导入

7.3 数据迁移注意事项

8. 数据备份策略

8.1 备份方案

8.2 恢复方案

9. 性能优化建议

9.1 查询优化

9.2 数据量预估

9.3 分表策略（如需要）

17 KiB

Raw Blame History