mirror of
https://github.com/KingHWJ/WeReadBoard.git
synced 2026-11-03 18:24:58 +08:00
41 KiB
41 KiB
微信读书数据展示网站 - 元数据文档
更新时间：2026-07-17 | 数据库：MySQL weread_dashboard | 数据模型：完整阅读数据表
1. 数据库概览
| 属性 | 值 |
|---|---|
| 数据库名称 | weread_dashboard |
| 字符集 | utf8mb4 |
| 排序规则 | utf8mb4_unicode_ci |
| 存储引擎 | InnoDB |
| 表数量 | 31 |
| 数据总量 | 685 行 |
设计规范
- 双列时间戳：所有
INT UNSIGNED时间戳字段均伴随_dt TIMESTAMP列，便于直接查询展示 - 审计列：每张表统一维护
created_at（创建时间）和updated_at（更新时间），自动维护 - 中文注释：每个字段均带
COMMENT中文注释 - 索引设计：主键、唯一约束、复合索引按实际查询模式设计
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 | (用户信息未入库) |