WeReadBoard/docs/METADATA_DOC.md

# 微信读书数据展示网站 - 元数据文档

> 版本：2.0.0 | 更新时间：2026-07-17 | 数据库：MySQL weread_dashboard | 数据模型版本：v2.0

---

## 1. 数据库概览

| 属性 | 值 |
|------|-----|
| 数据库名称 | weread_dashboard |
| 字符集 | utf8mb4 |
| 排序规则 | utf8mb4_unicode_ci |
| 存储引擎 | InnoDB |
| 表数量 | 31 |
| 数据总量 | 685 行 |

### 设计规范

1. **双列时间戳**：所有 `INT UNSIGNED` 时间戳字段均伴随 `_dt TIMESTAMP` 列，便于直接查询展示
2. **审计列**：每张表统一维护 `created_at`（创建时间）和 `updated_at`（更新时间），自动维护
3. **中文注释**：每个字段均带 `COMMENT` 中文注释
4. **索引设计**：主键、唯一约束、复合索引按实际查询模式设计

---

## 2. 表分类

| 分类 | 表名 | 说明 | 数据来源 |
|------|------|------|----------|
| **书架数据** | books | 书架电子书 | 采集脚本 |
| **书架数据** | shelf_albums | 书架有声书/专辑 | 采集脚本 |
| **书架数据** | shelf_meta | 书架元信息 | 采集脚本 |
| **书架数据** | archives | 书单/归档 | 采集脚本 |
| **阅读统计** | reading_stats | 阅读统计概要 | 采集脚本 |
| **阅读统计** | read_times | 阅读时长时间序列 | 采集脚本 |
| **阅读统计** | read_longest | 阅读时长排行 | 采集脚本 |
| **阅读统计** | read_stat_items | 统计摘要项 | 采集脚本 |
| **阅读统计** | prefer_categories | 偏好分类 | 采集脚本 |
| **阅读统计** | prefer_authors | 偏好作者 | 采集脚本 |
| **阅读统计** | prefer_publishers | 偏好出版社 | 采集脚本 |
| **阅读统计** | prefer_cps | 偏好版权方 | 采集脚本 |
| **阅读统计** | prefer_books | 偏好书籍卡片 | 采集脚本 |
| **阅读统计** | prefer_time | 24h 时段分布 | 采集脚本 |
| **阅读统计** | read_rank | 好友阅读排行 | 采集脚本 |
| **阅读统计** | medals | 勋章 | 采集脚本 |
| **阅读统计** | year_reports | 年度报告 | 采集脚本 |
| **笔记数据** | notebooks | 笔记本概览 | 采集脚本 |
| **笔记数据** | book_highlights | 划线内容 | 用户点击时获取 |
| **笔记数据** | book_chapters | 章节信息 | 用户点击时获取 |
| **笔记数据** | book_reviews | 个人想法/点评 | 用户点击时获取 |
| **笔记数据** | book_best_bookmarks | 热门划线 | 用户点击时获取 |
| **笔记数据** | book_underlines | 划线热度统计 | 用户点击时获取 |
| **笔记数据** | public_reviews | 公开点评 | 用户点击时获取 |
| **书籍详情** | book_details | 书籍详细信息 | 用户点击时获取 |
| **书籍详情** | book_progress | 阅读进度 | 用户点击时获取 |
| **发现/推荐** | recommended_books | 推荐书籍 | 用户浏览推荐时获取 |
| **发现/推荐** | similar_books | 相似书推荐 | 用户点击时获取 |
| **搜索** | search_sessions | 搜索会话 | 用户搜索时获取 |
| **搜索** | search_results | 搜索结果 | 用户搜索时获取 |
| **系统** | fetch_meta | 数据采集元信息 | 采集脚本 |

---

## 3. 表结构详情

### 3.1 books — 书架电子书

> 来源：`/shelf/sync` 的 `books[]` | 记录数：404

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| book_id | VARCHAR(64) | 是 (PK) | - | 书籍唯一标识 |
| title | VARCHAR(255) | 是 | '' | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| category | VARCHAR(128) | 否 | NULL | 分类（如 "文学-古代诗词"） |
| finish_reading | TINYINT(1) | 是 | 0 | 是否读完 (1=读完) |
| read_update_time | INT UNSIGNED | 否 | NULL | 最近阅读时间 (Unix 时间戳) |
| read_update_time_dt | TIMESTAMP | 否 | NULL | 最近阅读时间 (可读格式) |
| secret | TINYINT(1) | 是 | 0 | 是否私密 (1=私密) |
| is_top | TINYINT(1) | 是 | 0 | 是否置顶 (1=置顶) |
| update_time | INT UNSIGNED | 否 | NULL | 书籍更新时间 (Unix 时间戳) |
| update_time_dt | TIMESTAMP | 否 | NULL | 书籍更新时间 (可读格式) |
| deep_link | VARCHAR(512) | 否 | NULL | 微信读书 App 深度链接 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(book_id), idx_books_category(category), idx_books_finish_reading(finish_reading), idx_books_secret(secret), idx_books_is_top(is_top), idx_books_read_update_time(read_update_time DESC), idx_books_title(title)

---

### 3.2 shelf_albums — 书架有声书/专辑

> 来源：`/shelf/sync` 的 `albums[]` | 记录数：0

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| album_id | VARCHAR(64) | 是 (PK) | - | 专辑唯一标识 |
| name | VARCHAR(255) | 否 | NULL | 专辑名称 |
| author_name | VARCHAR(255) | 否 | NULL | 演播/作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| track_count | INT UNSIGNED | 否 | 0 | 音频集数 |
| finish_status | VARCHAR(32) | 否 | NULL | 完结状态文案（如 "已完结"） |
| finish | TINYINT(1) | 是 | 0 | 是否完结 (1=完结) |
| pay_type | INT UNSIGNED | 否 | NULL | 付费类型 |
| intro | TEXT | 否 | NULL | 专辑简介 |
| update_time | INT UNSIGNED | 否 | NULL | 更新时间 (Unix 时间戳) |
| update_time_dt | TIMESTAMP | 否 | NULL | 更新时间 (可读格式) |
| secret | TINYINT(1) | 是 | 0 | 是否私密 (1=私密) |
| lecture_paid | TINYINT(1) | 是 | 0 | 是否已购买 (1=已购买) |
| lecture_read_update_time | INT UNSIGNED | 否 | NULL | 最近收听时间 (Unix 时间戳) |
| lecture_read_update_time_dt | TIMESTAMP | 否 | NULL | 最近收听时间 (可读格式) |
| is_top | TINYINT(1) | 是 | 0 | 是否置顶 (1=置顶) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(album_id), idx_albums_finish(finish), idx_albums_secret(secret), idx_albums_lecture_read_time(lecture_read_update_time DESC)

---

### 3.3 shelf_meta — 书架元信息

> 来源：`/shelf/sync` 的 `mp` 和 `bookCount` | 记录数：1

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mp_enabled | TINYINT(1) | 是 | 0 | 是否有文章收藏入口 (1=有) |
| book_count | INT UNSIGNED | 否 | 0 | 可枚举电子书数量 |
| album_count | INT UNSIGNED | 否 | 0 | 有声书/专辑数量 |
| total_count | INT UNSIGNED | 否 | 0 | 书架总条目数 |
| raw_json | LONGTEXT | 否 | NULL | 原始 API 返回 JSON |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id)

---

### 3.4 archives — 书单/归档

> 来源：`/shelf/sync` 的 `archive[]` | 记录数：6

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| name | VARCHAR(255) | 否 | NULL | 书单名称 |
| book_ids | LONGTEXT | 否 | NULL | bookId 列表 (JSON 数组) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_archives_name(name)

---

### 3.5 reading_stats — 阅读统计概要

> 来源：`/readdata/detail` | 记录数：2

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度: overall/annually/monthly/weekly |
| period | VARCHAR(20) | 是 | '' | 周期标识 (如 "overall" 或 "2026") |
| base_time | INT UNSIGNED | 否 | NULL | 统计周期基准时间戳 |
| base_time_dt | TIMESTAMP | 否 | NULL | 统计周期基准时间 (可读格式) |
| total_read_time | INT UNSIGNED | 是 | 0 | 总阅读时长 (秒) |
| read_days | INT UNSIGNED | 是 | 0 | 有效阅读天数 |
| day_average_read_time | DOUBLE | 否 | 0 | 日均阅读时长 (秒) |
| compare | DOUBLE | 否 | NULL | 与上周期对比比例 (正=增长) |
| regist_time | INT UNSIGNED | 否 | NULL | 用户注册时间 (Unix 时间戳) |
| regist_time_dt | TIMESTAMP | 否 | NULL | 用户注册时间 (可读格式) |
| record_reading_time | INT UNSIGNED | 否 | 0 | 总朗读/记录类阅读时长 (秒) |
| read_rate | DOUBLE | 否 | NULL | 文字阅读占比百分比 |
| wr_read_time | INT UNSIGNED | 否 | NULL | 文字阅读时长 (秒) |
| wr_listen_time | INT UNSIGNED | 否 | NULL | 听书时长 (秒) |
| author_count | INT UNSIGNED | 否 | NULL | 符合统计条件的作者总数 |
| prefer_category_word | VARCHAR(128) | 否 | NULL | 偏好分类文案 (如 "偏好阅读文学") |
| prefer_time_word | VARCHAR(128) | 否 | NULL | 偏好时段文案 (如 "偏好上午阅读") |
| read_records_word | VARCHAR(64) | 否 | NULL | 书籍分布模块标题文案 |
| read_distribution_word | VARCHAR(64) | 否 | NULL | 点评分布模块标题文案 |
| read_time_gears | VARCHAR(128) | 否 | NULL | 阅读时长档位 (JSON 数组) |
| style_type | VARCHAR(32) | 否 | NULL | 样式类型 (如 normal) |
| raw_json | LONGTEXT | 否 | NULL | 原始 API 返回 JSON |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), uk_reading_stats_mode_period(mode, period), idx_reading_stats_mode(mode)

---

### 3.6 read_times — 阅读时长时间序列

> 来源：`/readdata/detail` 的 `readTimes` 和 `dailyReadTimes` | 记录数：21

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(30) | 是 | - | 统计维度 (含 _daily 后缀表示每日数据) |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| bucket_timestamp | INT UNSIGNED | 是 | - | 分桶起始时间戳 |
| bucket_timestamp_dt | TIMESTAMP | 否 | NULL | 分桶起始时间 (可读格式) |
| duration | INT UNSIGNED | 是 | 0 | 阅读时长 (秒) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_read_times_mode_period(mode, period), idx_read_times_bucket(bucket_timestamp)

---

### 3.7 read_longest — 阅读时长排行

> 来源：`/readdata/detail` 的 `readLongest[]` | 记录数：20

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| title | VARCHAR(255) | 否 | NULL | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| read_time | INT UNSIGNED | 是 | 0 | 阅读时长 (秒) |
| record_reading_time | INT UNSIGNED | 否 | NULL | 朗读/记录类阅读时长 (秒) |
| tags | VARCHAR(512) | 否 | NULL | 标签 (JSON 数组，如 ["笔记最多"]) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_read_longest_mode_period(mode, period), idx_read_longest_book_id(book_id), idx_read_longest_read_time(read_time DESC)

---

### 3.8 read_stat_items — 阅读统计摘要项

> 来源：`/readdata/detail` 的 `readStat[]` | 记录数：8

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| stat_name | VARCHAR(64) | 否 | NULL | 统计项名称 (读过/读完/阅读/笔记) |
| counts | VARCHAR(64) | 否 | NULL | 统计值文案 (如 "404本") |
| scheme | VARCHAR(512) | 否 | NULL | App 跳转链接 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_read_stat_items_mode_period(mode, period)

---

### 3.9 prefer_categories — 偏好分类

> 来源：`/readdata/detail` 的 `preferCategory[]` | 记录数：16

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| category_id | INT UNSIGNED | 否 | NULL | 分类 ID |
| category_title | VARCHAR(128) | 否 | NULL | 分类名称 (如 "文学") |
| parent_category_id | INT UNSIGNED | 否 | NULL | 父分类 ID |
| parent_category_title | VARCHAR(128) | 否 | NULL | 父分类名称 (如 "精品小说") |
| category_type | TINYINT | 否 | 0 | 分类类型标记 (0=普通, 1/2=特殊) |
| val | DOUBLE | 否 | 0 | 偏好权重 (归一化相对值) |
| reading_time | INT UNSIGNED | 否 | 0 | 该分类阅读时长 (秒) |
| reading_count | INT UNSIGNED | 否 | 0 | 该分类阅读本数 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_prefer_cat_mode_period(mode, period), idx_prefer_cat_category_id(category_id)

---

### 3.10 prefer_authors — 偏好作者

> 来源：`/readdata/detail` 的 `preferAuthor[]` | 记录数：20

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| author_id | INT UNSIGNED | 否 | NULL | 作者 ID |
| name | VARCHAR(255) | 否 | NULL | 作者名 |
| count | INT UNSIGNED | 否 | 0 | 阅读该作者的书本数 |
| read_time | VARCHAR(64) | 否 | NULL | 阅读时长 (格式化字符串，如 "5小时30分钟") |
| user_json | TEXT | 否 | NULL | 作者关联用户信息 (JSON) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_prefer_author_mode_period(mode, period), idx_prefer_author_name(name)

---

### 3.11 prefer_publishers — 偏好出版社

> 来源：`/readdata/detail` 的 `preferPublisher[]` | 记录数：20

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| name | VARCHAR(255) | 否 | NULL | 出版社名 |
| count | INT UNSIGNED | 否 | 0 | 阅读该出版社书籍本数 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_prefer_pub_mode_period(mode, period)

---

### 3.12 prefer_cps — 偏好版权方

> 来源：`/readdata/detail` 的 `preferCp[]` | 记录数：20

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| count | INT UNSIGNED | 否 | 0 | 阅读该版权方书籍本数 |
| cp_name | VARCHAR(255) | 否 | NULL | 版权方名称 |
| cp_user_vid | VARCHAR(64) | 否 | NULL | 版权方用户 VID |
| cp_avatar | VARCHAR(512) | 否 | NULL | 版权方头像 URL |
| cp_role | VARCHAR(64) | 否 | NULL | 版权方角色 |
| copyright_json | TEXT | 否 | NULL | 版权方完整信息 (JSON) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_prefer_cp_mode_period(mode, period)

---

### 3.13 prefer_books — 偏好书籍卡片

> 来源：`/readdata/detail` 的 `preferBooks[]` | 记录数：24

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| book_id | VARCHAR(64) | 否 | NULL | 书籍 ID |
| title | VARCHAR(255) | 否 | NULL | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| reason | TEXT | 否 | NULL | 推荐理由 |
| prefer_type | VARCHAR(64) | 否 | NULL | 偏好类型 |
| book_json | TEXT | 否 | NULL | 书籍完整信息 (JSON) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_prefer_books_mode_period(mode, period), idx_prefer_books_book_id(book_id)

---

### 3.14 prefer_time — 24小时阅读时段分布

> 来源：`/readdata/detail` 的 `preferTime[]` | 记录数：24

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| hour_index | TINYINT UNSIGNED | 是 | - | 小时 (0-23) |
| duration | INT UNSIGNED | 是 | 0 | 阅读时长 (秒) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_prefer_time_mode_period(mode, period)

---

### 3.15 read_rank — 好友阅读排行

> 来源：`/readdata/detail` 的 `rank` | 记录数：0

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| rank_text | VARCHAR(255) | 否 | NULL | 排行文案 (如 "朋友中排第3名") |
| scheme | VARCHAR(512) | 否 | NULL | 排行跳转链接 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_read_rank_mode_period(mode, period)

---

### 3.16 medals — 勋章

> 来源：`/readdata/detail` 的 `medals[]` | 记录数：30

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| medal_json | TEXT | 否 | NULL | 勋章信息 (JSON) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_medals_mode_period(mode, period)

---

### 3.17 year_reports — 年度报告

> 来源：`/readdata/detail` 的 `yearReport[]` | 记录数：0

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| mode | VARCHAR(20) | 是 | - | 统计维度 |
| period | VARCHAR(20) | 是 | '' | 周期标识 |
| report_year | VARCHAR(10) | 否 | NULL | 报告年份 |
| report_json | TEXT | 否 | NULL | 报告入口信息 (JSON) |
| monthly_times | VARCHAR(512) | 否 | NULL | 12个月阅读时长 (JSON 数组，单位秒) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_year_reports_mode_period(mode, period), idx_year_reports_year(report_year)

---

### 3.18 notebooks — 笔记本概览

> 来源：`/user/notebooks` | 记录数：32

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| book_id | VARCHAR(64) | 是 (PK) | - | 书籍 ID |
| title | VARCHAR(255) | 否 | NULL | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| review_count | INT UNSIGNED | 是 | 0 | 想法/点评数 |
| note_count | INT UNSIGNED | 是 | 0 | 划线数 |
| bookmark_count | INT UNSIGNED | 是 | 0 | 书签数 |
| total_note_count | INT UNSIGNED | 是 | 0 | 笔记总数 (review+note+bookmark) |
| reading_progress | INT UNSIGNED | 是 | 0 | 阅读进度 (0-100) |
| marked_status | TINYINT(1) | 是 | 0 | 标记状态 (1=读完) |
| sort | BIGINT | 否 | NULL | 排序值 (最近笔记时间) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(book_id), idx_notebooks_marked_status(marked_status), idx_notebooks_sort(sort DESC)

---

### 3.19 book_highlights — 划线内容

> 来源：`/book/bookmarklist` 的 `updated[]` | 记录数：0（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| bookmark_id | VARCHAR(64) | 否 | NULL | 划线唯一 ID |
| chapter_uid | INT UNSIGNED | 否 | NULL | 所在章节 UID |
| mark_text | LONGTEXT | 否 | NULL | 划线原文内容 |
| create_time | INT UNSIGNED | 否 | NULL | 创建时间 (Unix 时间戳) |
| create_time_dt | TIMESTAMP | 否 | NULL | 创建时间 (可读格式) |
| type | TINYINT | 否 | NULL | 类型 (1=划线) |
| range_text | VARCHAR(64) | 否 | NULL | 位置范围 (如 "2959-3007") |
| color_style | TINYINT | 否 | NULL | 划线颜色样式 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), uk_highlights_bookmark(book_id, bookmark_id), idx_highlights_book_id(book_id), idx_highlights_chapter(book_id, chapter_uid), idx_highlights_create_time(create_time DESC)

---

### 3.20 book_chapters — 章节信息

> 来源：`/book/chapterinfo` 和 `/book/bookmarklist` 的 `chapters` | 记录数：0（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| chapter_uid | INT UNSIGNED | 是 | - | 章节 UID |
| chapter_idx | INT UNSIGNED | 否 | NULL | 章节序号 |
| title | VARCHAR(255) | 否 | NULL | 章节标题 |
| word_count | INT UNSIGNED | 否 | NULL | 章节字数 |
| level | TINYINT | 否 | NULL | 目录层级 (1=一级, 2=二级) |
| update_time | INT UNSIGNED | 否 | NULL | 章节更新时间 (Unix 时间戳) |
| update_time_dt | TIMESTAMP | 否 | NULL | 章节更新时间 (可读格式) |
| price | INT UNSIGNED | 否 | 0 | 章节价格 (0=免费) |
| paid | TINYINT(1) | 是 | 0 | 是否已购买 (1=已购买) |
| is_mp_chapter | TINYINT(1) | 是 | 0 | 是否公众号章节 (1=是) |
| anchors | TEXT | 否 | NULL | 章节内锚点/子标题 (JSON 数组) |
| synckey | INT UNSIGNED | 否 | NULL | 同步 key (版本号) |
| chapter_update_time | INT UNSIGNED | 否 | NULL | 章节列表最后更新时间 (Unix 时间戳) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), uk_book_chapter(book_id, chapter_uid), idx_chapters_book_idx(book_id, chapter_idx)

---

### 3.21 book_reviews — 个人想法/点评

> 来源：`/review/list/mine` | 记录数：0（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| review_id | VARCHAR(64) | 否 | NULL | 想法唯一 ID |
| content | LONGTEXT | 否 | NULL | 想法内容文本 |
| abstract | LONGTEXT | 否 | NULL | 想法对应的划线原文 (仅划线想法有值) |
| range_text | VARCHAR(64) | 否 | NULL | 划线原文位置范围 (如 "2959-3007") |
| chapter_uid | INT UNSIGNED | 否 | NULL | 章节 UID |
| chapter_idx | INT UNSIGNED | 否 | NULL | 章节序号 |
| chapter_name | VARCHAR(255) | 否 | NULL | 所在章节名 (章节点评时有值) |
| create_time | INT UNSIGNED | 否 | NULL | 创建时间 (Unix 时间戳) |
| create_time_dt | TIMESTAMP | 否 | NULL | 创建时间 (可读格式) |
| star | TINYINT | 否 | -1 | 评分 (0-5, -1=无评分) |
| is_finish | TINYINT(1) | 否 | 0 | 是否书评 (1=书评) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), uk_reviews_review_id(review_id), idx_reviews_book_id(book_id), idx_reviews_chapter(book_id, chapter_uid), idx_reviews_create_time(create_time DESC)

---

### 3.22 book_best_bookmarks — 热门划线

> 来源：`/book/bestbookmarks` | 记录数：0（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| bookmark_id | VARCHAR(64) | 否 | NULL | 划线唯一 ID |
| chapter_uid | INT UNSIGNED | 否 | NULL | 所在章节 UID |
| range_text | VARCHAR(64) | 否 | NULL | 划线位置范围 (如 "393-401") |
| mark_text | LONGTEXT | 否 | NULL | 划线原文文本 |
| total_count | INT UNSIGNED | 否 | 0 | 划线人数 |
| user_vid | VARCHAR(64) | 否 | NULL | 代表用户 VID |
| simplified_range | VARCHAR(64) | 否 | NULL | 简体书籍的 range (繁简体书专属) |
| traditional_range | VARCHAR(64) | 否 | NULL | 繁体书籍的 range (繁简体书专属) |
| synckey | INT UNSIGNED | 否 | NULL | 同步 key (数据版本号) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), uk_best_bm_book_bookmark(book_id, bookmark_id), idx_best_bm_book_id(book_id), idx_best_bm_total_count(total_count DESC)

---

### 3.23 book_underlines — 划线热度统计

> 来源：`/book/underlines` | 记录数：0（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| chapter_uid | INT UNSIGNED | 是 | - | 章节 UID |
| range_text | VARCHAR(64) | 否 | NULL | 划线位置范围 (如 "393-401") |
| count | INT UNSIGNED | 否 | 0 | 划线人数 |
| score | DOUBLE | 否 | 0 | 热度分数 |
| type | TINYINT | 否 | NULL | 划线类型 |
| synckey | INT UNSIGNED | 否 | NULL | 同步 key |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), uk_underlines_book_ch_range(book_id, chapter_uid, range_text), idx_underlines_book_chapter(book_id, chapter_uid)

---

### 3.24 public_reviews — 公开点评

> 来源：`/review/list` | 记录数：0（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| review_id | VARCHAR(64) | 否 | NULL | 点评唯一 ID |
| content | LONGTEXT | 否 | NULL | 点评文本内容 |
| html_content | LONGTEXT | 否 | NULL | 点评 HTML 富文本内容 |
| star | TINYINT | 否 | -1 | 评分 (20=一星, 40=二星, 60=三星, 80=四星, 100=五星) |
| is_finish | TINYINT(1) | 否 | 0 | 是否读完此书 (1=读完) |
| create_time | INT UNSIGNED | 否 | NULL | 创建时间 (Unix 时间戳) |
| create_time_dt | TIMESTAMP | 否 | NULL | 创建时间 (可读格式) |
| chapter_name | VARCHAR(255) | 否 | NULL | 所在章节名 |
| author_vid | VARCHAR(64) | 否 | NULL | 评论者用户 VID |
| author_name | VARCHAR(255) | 否 | NULL | 评论者昵称 |
| author_avatar | VARCHAR(512) | 否 | NULL | 评论者头像 URL |
| review_list_type | TINYINT | 否 | 0 | 筛选类型 (0=全部, 1=推荐, 2=不行, 3=最新, 4=一般) |
| idx | INT UNSIGNED | 否 | NULL | 序号 (用于翻页) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), uk_public_reviews_review_id(review_id), idx_public_reviews_book_id(book_id), idx_public_reviews_star(star), idx_public_reviews_create_time(create_time DESC)

---

### 3.25 book_details — 书籍详细信息

> 来源：`/book/info` | 记录数：1（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| book_id | VARCHAR(64) | 是 (PK) | - | 书籍 ID |
| title | VARCHAR(255) | 否 | NULL | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| translator | VARCHAR(255) | 否 | NULL | 译者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| intro | LONGTEXT | 否 | NULL | 简介 |
| category | VARCHAR(128) | 否 | NULL | 分类 |
| publisher | VARCHAR(255) | 否 | NULL | 出版社 |
| publish_time | VARCHAR(32) | 否 | NULL | 出版时间 |
| isbn | VARCHAR(32) | 否 | NULL | ISBN 号 |
| word_count | INT UNSIGNED | 否 | 0 | 总字数 |
| new_rating | DECIMAL(5,1) | 否 | 0 | 评分 (百分制) |
| new_rating_count | INT UNSIGNED | 否 | 0 | 评分人数 |
| new_rating_detail | TEXT | 否 | NULL | 评分分布详情 (JSON) |
| deep_link | VARCHAR(512) | 否 | NULL | 跳转链接 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(book_id), idx_book_details_isbn(isbn), idx_book_details_category(category), idx_book_details_publisher(publisher)

---

### 3.26 book_progress — 阅读进度

> 来源：`/book/getprogress` | 记录数：1（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| book_id | VARCHAR(64) | 是 (PK) | - | 书籍 ID |
| progress | TINYINT UNSIGNED | 是 | 0 | 阅读进度百分比 (0-100) |
| chapter_uid | INT UNSIGNED | 否 | NULL | 当前阅读章节 UID |
| chapter_offset | INT UNSIGNED | 否 | NULL | 当前章节内偏移量 |
| update_time | INT UNSIGNED | 否 | NULL | 最后阅读时间 (Unix 时间戳) |
| update_time_dt | TIMESTAMP | 否 | NULL | 最后阅读时间 (可读格式) |
| record_reading_time | INT UNSIGNED | 否 | 0 | 累计阅读时长 (秒) |
| finish_time | INT UNSIGNED | 否 | NULL | 读完时间 (Unix 时间戳) |
| finish_time_dt | TIMESTAMP | 否 | NULL | 读完时间 (可读格式) |
| is_start_reading | TINYINT(1) | 是 | 0 | 是否已开始阅读 (1=是) |
| server_timestamp | INT UNSIGNED | 否 | NULL | 服务端时间戳 |
| server_timestamp_dt | TIMESTAMP | 否 | NULL | 服务端时间 (可读格式) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(book_id), idx_progress_finish_time(finish_time DESC), idx_progress_update_time(update_time DESC)

---

### 3.27 recommended_books — 推荐书籍

> 来源：`/book/recommend` | 记录数：12（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| title | VARCHAR(255) | 否 | NULL | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| intro | TEXT | 否 | NULL | 书籍简介 |
| category | VARCHAR(128) | 否 | NULL | 分类 |
| reason | VARCHAR(512) | 否 | NULL | 推荐理由 |
| reading_count | INT UNSIGNED | 否 | 0 | 在读人数 |
| new_rating | DECIMAL(5,1) | 否 | 0 | 评分 (百分制) |
| new_rating_count | INT UNSIGNED | 否 | 0 | 评分人数 |
| rating_title | VARCHAR(32) | 否 | NULL | 评分标签 (神作/力荐等) |
| deep_link | VARCHAR(512) | 否 | NULL | 跳转链接 |
| search_idx | INT UNSIGNED | 否 | 0 | 结果序号 (用于翻页) |
| price | INT UNSIGNED | 否 | NULL | 价格 (分) |
| pay_type | INT UNSIGNED | 否 | NULL | 付费类型 |
| book_type | TINYINT | 否 | 0 | 书籍类型 (0=电子书) |
| batch_id | VARCHAR(32) | 否 | NULL | 推荐批次 ID |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_recommended_book_id(book_id), idx_recommended_batch(batch_id), idx_recommended_rating(new_rating DESC)

---

### 3.28 similar_books — 相似书推荐

> 来源：`/book/similar` | 记录数：0（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| source_book_id | VARCHAR(64) | 是 | - | 源书籍 ID |
| book_id | VARCHAR(64) | 是 | - | 推荐书籍 ID |
| title | VARCHAR(255) | 否 | NULL | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| deep_link | VARCHAR(512) | 否 | NULL | 跳转链接 |
| idx | INT UNSIGNED | 否 | NULL | 结果序号 (用于翻页) |
| session_id | VARCHAR(64) | 否 | NULL | 翻页会话 ID |
| book_json | TEXT | 否 | NULL | 书籍完整信息 (JSON) |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_similar_source(source_book_id), idx_similar_book_id(book_id)

---

### 3.29 search_sessions — 搜索会话

> 来源：`/store/search` 的元数据 | 记录数：1（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| sid | VARCHAR(64) | 否 | NULL | 搜索会话 ID |
| keyword | VARCHAR(255) | 是 | - | 搜索关键词 |
| scope | INT UNSIGNED | 否 | NULL | 搜索类型 (0=全部, 10=电子书, 14=听书等) |
| has_more | TINYINT(1) | 是 | 0 | 是否有更多 (1=有) |
| max_idx | INT UNSIGNED | 否 | 0 | 当前翻页偏移 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_search_sessions_keyword(keyword), idx_search_sessions_sid(sid)

---

### 3.30 search_results — 搜索结果

> 来源：`/store/search` 的 `results[].books[]` | 记录数：20（按需获取）

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
| session_id | BIGINT | 否 | NULL | 关联搜索会话 ID |
| keyword | VARCHAR(255) | 是 | - | 搜索关键词 |
| book_id | VARCHAR(64) | 是 | - | 书籍 ID |
| title | VARCHAR(255) | 否 | NULL | 书名 |
| author | VARCHAR(255) | 否 | NULL | 作者 |
| cover | VARCHAR(512) | 否 | NULL | 封面图 URL |
| intro | TEXT | 否 | NULL | 书籍简介 |
| publisher | VARCHAR(255) | 否 | NULL | 出版社 |
| category | VARCHAR(128) | 否 | NULL | 分类 |
| reading_count | INT UNSIGNED | 否 | 0 | 在读人数 |
| new_rating | DECIMAL(5,1) | 否 | 0 | 评分 (百分制) |
| new_rating_count | INT UNSIGNED | 否 | 0 | 评分人数 |
| rating_title | VARCHAR(32) | 否 | NULL | 评分标签 |
| deep_link | VARCHAR(512) | 否 | NULL | 跳转链接 |
| pay_type | INT UNSIGNED | 否 | NULL | 付费类型 |
| price | INT UNSIGNED | 否 | NULL | 价格 (分) |
| soldout | TINYINT(1) | 是 | 0 | 是否下架 (1=下架) |
| search_idx | INT UNSIGNED | 否 | 0 | 搜索序号 (用于翻页) |
| result_scope | INT UNSIGNED | 否 | NULL | 回包分组类型 |
| result_title | VARCHAR(64) | 否 | NULL | 回包分组标题 (如 "电子书") |
| scope_count | INT UNSIGNED | 否 | NULL | 该分组总结果数 |
| current_count | INT UNSIGNED | 否 | NULL | 本次返回数量 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(id), idx_search_results_keyword(keyword), idx_search_results_book_id(book_id), idx_search_results_session(session_id)

---

### 3.31 fetch_meta — 数据采集元信息

> 系统表 | 记录数：3

| 字段名 | 数据类型 | 必填 | 默认值 | 说明 |
|--------|----------|------|--------|------|
| key | VARCHAR(64) | 是 (PK) | - | 元信息键名 |
| value | TEXT | 否 | NULL | 元信息值 |
| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 |

**索引**：PK(key)

---

## 4. 表关系说明

### 4.1 实体关系

```
books (书架)
  ├── book_id ──── book_details (书籍详情)        [1:1 按需]
  ├── book_id ──── book_progress (阅读进度)        [1:1 按需]
  ├── book_id ──── book_highlights (划线)         [1:N 按需]
  ├── book_id ──── book_chapters (章节)           [1:N 按需]
  ├── book_id ──── book_reviews (个人想法)         [1:N 按需]
  ├── book_id ──── book_best_bookmarks (热门划线)  [1:N 按需]
  ├── book_id ──── book_underlines (划线热度)      [1:N 按需]
  ├── book_id ──── public_reviews (公开点评)      [1:N 按需]
  ├── book_id ──── notebooks (笔记本概览)          [1:1 有笔记的书]
  └── book_id ──── similar_books (相似书)          [1:N 按需, source_book_id]

read_longest (阅读排行)
  └── book_id ──── books (书架)                   [N:1 关联]

prefer_books (偏好书籍卡片)
  └── book_id ──── books (书架)                   [N:1 关联]

recommended_books (推荐)
  └── book_id (独立，不关联 books)

search_sessions (搜索会话)
  └── id ──── search_results (搜索结果)           [1:N 关联]

search_results (搜索)
  └── book_id (独立，不关联 books)

archives (书单)
  └── book_ids (JSON 数组，逻辑关联 books)
```

### 4.2 逻辑分组

| 分组 | 表名 | 说明 |
|------|------|------|
| **静态数据组**（采集时全量写入） | books, shelf_albums, shelf_meta, archives, reading_stats, read_times, read_longest, read_stat_items, prefer_categories, prefer_authors, prefer_publishers, prefer_cps, prefer_books, prefer_time, read_rank, medals, year_reports, notebooks, fetch_meta | 共 19 张表 |
| **动态数据组**（用户操作时按需写入） | book_details, book_progress, book_highlights, book_chapters, book_reviews, book_best_bookmarks, book_underlines, public_reviews, recommended_books, similar_books, search_sessions, search_results | 共 12 张表 |

---

## 5. 数据类型规范

| MySQL 类型 | 用途 | 对应 SQLite 类型 |
|------------|------|------------------|
| VARCHAR(n) | 变长字符串（书名、作者等） | TEXT |
| LONGTEXT | 长文本（简介、划线内容） | TEXT |
| TEXT | 中等文本（JSON、简介等） | TEXT |
| INT UNSIGNED | 无符号整数（时间戳、计数） | INTEGER |
| TINYINT(1) | 布尔值（0/1） | INTEGER |
| TINYINT | 小范围整数（评分、类型） | INTEGER |
| TINYINT UNSIGNED | 小范围无符号整数（小时 0-23、进度 0-100） | INTEGER |
| BIGINT | 自增主键 | INTEGER |
| DECIMAL(5,1) | 精度数值（评分） | REAL |
| DOUBLE | 浮点数（权重、日均时长、热度分数） | REAL |
| TIMESTAMP | 时间戳（自动维护 + _dt 可读列） | TEXT (ISO 格式) |

---

## 6. 字符集与编码

- 数据库字符集：`utf8mb4`（支持完整 Unicode，包括 Emoji）
- 排序规则：`utf8mb4_unicode_ci`（不区分大小写，支持多语言排序）
- 连接字符集：`utf8mb4`（PyMySQL 连接配置中指定）
- 前端编码：`UTF-8`（HTML meta 标签声明）

---

## 7. API 文档覆盖对照

| 官方 API 文档 | 对应数据表 |
|--------------|-----------|
| shelf.md | books, shelf_albums, shelf_meta, archives |
| readdata.md | reading_stats, read_times, read_longest, read_stat_items, prefer_categories, prefer_authors, prefer_publishers, prefer_cps, prefer_books, prefer_time, read_rank, medals, year_reports |
| notes.md | notebooks, book_highlights, book_chapters, book_reviews, book_best_bookmarks, book_underlines, public_reviews |
| book.md | book_details, book_progress |
| discover.md | recommended_books, similar_books |
| search.md | search_sessions, search_results |
| review.md | book_reviews, public_reviews |
| profile.md | (用户信息未入库) |