From 4c1a66ea6a1d8fbbd260a3493af840b95a8bbcc6 Mon Sep 17 00:00:00 2001 From: kinghwj Date: Fri, 17 Jul 2026 10:40:33 +0800 Subject: [PATCH] docs: update technical and metadata docs for v2.0 (31 tables) --- docs/METADATA_DOC.md | 878 +++++++++++++++++++++++++++++------------- docs/TECHNICAL_DOC.md | 31 +- 2 files changed, 638 insertions(+), 271 deletions(-) diff --git a/docs/METADATA_DOC.md b/docs/METADATA_DOC.md index 8906487..93f2b8d 100644 --- a/docs/METADATA_DOC.md +++ b/docs/METADATA_DOC.md @@ -1,6 +1,6 @@ # 微信读书数据展示网站 - 元数据文档 -> 版本：1.2.0 | 更新时间：2026-07-17 | 数据库：MySQL weread_dashboard +> 版本：2.0.0 | 更新时间：2026-07-17 | 数据库：MySQL weread_dashboard | 数据模型版本：v2.0 --- @@ -12,8 +12,15 @@ | 字符集 | utf8mb4 | | 排序规则 | utf8mb4_unicode_ci | | 存储引擎 | InnoDB | -| 表数量 | 18 | -| 数据总量 | 862 行 | +| 表数量 | 31 | +| 数据总量 | 685 行 | + +### 设计规范 + +1. **双列时间戳**：所有 `INT UNSIGNED` 时间戳字段均伴随 `_dt TIMESTAMP` 列，便于直接查询展示 +2. **审计列**：每张表统一维护 `created_at`（创建时间）和 `updated_at`（更新时间），自动维护 +3. **中文注释**：每个字段均带 `COMMENT` 中文注释 +4. **索引设计**：主键、唯一约束、复合索引按实际查询模式设计 --- @@ -21,108 +28,193 @@ | 分类 | 表名 | 说明 | 数据来源 | |------|------|------|----------| -| **基础数据** | books | 书架书籍 | 采集脚本 | -| **基础数据** | reading_stats | 阅读统计概要 | 采集脚本 | -| **基础数据** | read_times | 阅读时长时间序列 | 采集脚本 | -| **基础数据** | read_longest | 阅读时长排行 | 采集脚本 | -| **基础数据** | prefer_categories | 偏好分类 | 采集脚本 | -| **基础数据** | prefer_authors | 偏好作者 | 采集脚本 | -| **基础数据** | prefer_time | 24h 时段分布 | 采集脚本 | -| **基础数据** | notebooks | 笔记本概览 | 采集脚本 | -| **基础数据** | read_stat_items | 统计摘要项 | 采集脚本 | -| **基础数据** | archives | 书单归档 | 采集脚本 | -| **基础数据** | fetch_meta | 采集元信息 | 采集脚本 | -| **按需数据** | book_details | 书籍详情 | 用户点击时获取 | -| **按需数据** | book_progress | 阅读进度 | 用户点击时获取 | -| **按需数据** | book_highlights | 划线内容 | 用户点击时获取 | -| **按需数据** | book_chapters | 章节信息 | 用户点击时获取 | -| **按需数据** | book_reviews | 想法/点评 | 用户点击时获取 | -| **按需数据** | recommended_books | 推荐书籍 | 用户浏览推荐时获取 | -| **按需数据** | search_results | 搜索结果 | 用户搜索时获取 | +| **书架数据** | 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 - 书架书籍表 +### 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 | 分类（如"文学-古代诗词"） | +| 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 时间戳) | -| deep_link | VARCHAR(512) | 否 | NULL | 微信读书深度链接 | +| update_time_dt | TIMESTAMP | 否 | NULL | 书籍更新时间 (可读格式) | +| deep_link | VARCHAR(512) | 否 | NULL | 微信读书 App 深度链接 | +| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 | +| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 | -**索引**： -- PRIMARY KEY (book_id) -- idx_books_category (category) -- idx_books_finish_reading (finish_reading) -- idx_books_read_update_time (read_update_time DESC) - -**记录数**：404 +**索引**：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 reading_stats - 阅读统计概要表 +### 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 | 自增主键 | -| mode | VARCHAR(20) | 是 | - | 统计维度: overall/annually | -| period | VARCHAR(20) | 是 | '' | 周期标识: "overall" 或 "2026" | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_reading_stats_mode (mode, period) - -**记录数**：2 +**索引**：PK(id), uk_reading_stats_mode_period(mode, period), idx_reading_stats_mode(mode) --- -### 3.3 read_times - 阅读时长时间序列表 +### 3.6 read_times — 阅读时长时间序列 -> 按年/月/日分桶的阅读时长数据 +> 来源：`/readdata/detail` 的 `readTimes` 和 `dailyReadTimes` | 记录数：21 -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| +| 字段名 | 数据类型 | 必填 | 默认值 | 说明 | +|--------|----------|------|--------|------| | id | BIGINT | 是 (PK) | AUTO | 自增主键 | -| mode | VARCHAR(30) | 是 | - | 统计维度 (含 _daily 后缀) | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_read_times_mode_period (mode, period) -- idx_read_times_bucket (bucket_timestamp) - -**记录数**：21 +**索引**：PK(id), idx_read_times_mode_period(mode, period), idx_read_times_bucket(bucket_timestamp) --- -### 3.4 read_longest - 阅读时长排行表 +### 3.7 read_longest — 阅读时长排行 -> 阅读时间最久的书籍排名 +> 来源：`/readdata/detail` 的 `readLongest[]` | 记录数：20 -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| +| 字段名 | 数据类型 | 必填 | 默认值 | 说明 | +|--------|----------|------|--------|------| | id | BIGINT | 是 (PK) | AUTO | 自增主键 | | mode | VARCHAR(20) | 是 | - | 统计维度 | | period | VARCHAR(20) | 是 | '' | 周期标识 | @@ -131,88 +223,220 @@ | author | VARCHAR(255) | 否 | NULL | 作者 | | cover | VARCHAR(512) | 否 | NULL | 封面图 URL | | read_time | INT UNSIGNED | 是 | 0 | 阅读时长 (秒) | -| tags | VARCHAR(512) | 否 | NULL | 标签 (JSON 数组) | +| record_reading_time | INT UNSIGNED | 否 | NULL | 朗读/记录类阅读时长 (秒) | +| tags | VARCHAR(512) | 否 | NULL | 标签 (JSON 数组，如 ["笔记最多"]) | +| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 | +| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_read_longest_mode (mode, period) - -**记录数**：20 +**索引**：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.5 prefer_categories - 偏好分类表 +### 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_title | VARCHAR(128) | 否 | NULL | 父分类名称 | -| val | DOUBLE | 否 | 0 | 偏好权重 | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_prefer_cat_mode (mode, period) - -**记录数**：16 +**索引**：PK(id), idx_prefer_cat_mode_period(mode, period), idx_prefer_cat_category_id(category_id) --- -### 3.6 prefer_authors - 偏好作者表 +### 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 | 阅读时长 (格式化字符串) | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_prefer_author_mode (mode, period) - -**记录数**：20 +**索引**：PK(id), idx_prefer_author_mode_period(mode, period), idx_prefer_author_name(name) --- -### 3.7 prefer_time - 24小时时段分布表 +### 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_prefer_time_mode (mode, period) - -**记录数**：24 +**索引**：PK(id), idx_prefer_time_mode_period(mode, period) --- -### 3.8 notebooks - 笔记本概览表 +### 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 | 作者 | @@ -220,83 +444,179 @@ | 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 | 排序值 | +| sort | BIGINT | 否 | NULL | 排序值 (最近笔记时间) | +| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 | +| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 | -**索引**： -- PRIMARY KEY (book_id) - -**记录数**：32 +**索引**：PK(book_id), idx_notebooks_marked_status(marked_status), idx_notebooks_sort(sort DESC) --- -### 3.9 read_stat_items - 统计摘要项表 +### 3.19 book_highlights — 划线内容 -> App 首页展示的阅读统计摘要 +> 来源：`/book/bookmarklist` 的 `updated[]` | 记录数：0（按需获取） -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| +| 字段名 | 数据类型 | 必填 | 默认值 | 说明 | +|--------|----------|------|--------|------| | 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 跳转链接 | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_read_stat_items_mode (mode, period) - -**记录数**：8 +**索引**：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.10 archives - 书单归档表 +### 3.20 book_chapters — 章节信息 -> 用户创建的书单 +> 来源：`/book/chapterinfo` 和 `/book/bookmarklist` 的 `chapters` | 记录数：0（按需获取） -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| +| 字段名 | 数据类型 | 必填 | 默认值 | 说明 | +|--------|----------|------|--------|------| | id | BIGINT | 是 (PK) | AUTO | 自增主键 | -| name | VARCHAR(255) | 否 | NULL | 书单名称 | -| book_ids | LONGTEXT | 否 | NULL | 书籍 ID 列表 (JSON 数组) | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) - -**记录数**：6 +**索引**：PK(id), uk_book_chapter(book_id, chapter_uid), idx_chapters_book_idx(book_id, chapter_idx) --- -### 3.11 fetch_meta - 采集元信息表 +### 3.21 book_reviews — 个人想法/点评 -> 记录数据采集的元信息 +> 来源：`/review/list/mine` | 记录数：0（按需获取） -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| -| key | VARCHAR(64) | 是 (PK) | - | 元信息键名 | -| value | TEXT | 否 | NULL | 元信息值 | +| 字段名 | 数据类型 | 必填 | 默认值 | 说明 | +|--------|----------|------|--------|------| +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (key) - -**记录数**：1 +**索引**：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.12 book_details - 书籍详细信息表 +### 3.22 book_best_bookmarks — 热门划线 -> 来自微信读书 /book/info 接口，用户点击书籍时按需获取 +> 来源：`/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 | 书籍简介 | +| intro | LONGTEXT | 否 | NULL | 简介 | | category | VARCHAR(128) | 否 | NULL | 分类 | | publisher | VARCHAR(255) | 否 | NULL | 出版社 | | publish_time | VARCHAR(32) | 否 | NULL | 出版时间 | @@ -304,114 +624,46 @@ | word_count | INT UNSIGNED | 否 | 0 | 总字数 | | new_rating | DECIMAL(5,1) | 否 | 0 | 评分 (百分制) | | new_rating_count | INT UNSIGNED | 否 | 0 | 评分人数 | -| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 | +| new_rating_detail | TEXT | 否 | NULL | 评分分布详情 (JSON) | +| deep_link | VARCHAR(512) | 否 | NULL | 跳转链接 | +| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 | +| updated_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP ON UPDATE | 记录更新时间 | -**索引**： -- PRIMARY KEY (book_id) - -**记录数**：1 +**索引**：PK(book_id), idx_book_details_isbn(isbn), idx_book_details_category(category), idx_book_details_publisher(publisher) --- -### 3.13 book_progress - 阅读进度表 +### 3.26 book_progress — 阅读进度 -> 来自微信读书 /book/getprogress 接口 +> 来源：`/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 时间戳) | -| is_start_reading | TINYINT(1) | 是 | 0 | 是否已开始阅读 | -| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (book_id) - -**记录数**：1 +**索引**：PK(book_id), idx_progress_finish_time(finish_time DESC), idx_progress_update_time(update_time DESC) --- -### 3.14 book_highlights - 划线内容表 +### 3.27 recommended_books — 推荐书籍 -> 来自微信读书 /book/bookmarklist 接口 +> 来源：`/book/recommend` | 记录数：12（按需获取） -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| -| 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 时间戳) | -| type | TINYINT | 否 | NULL | 划线类型 | -| range_text | VARCHAR(64) | 否 | NULL | 位置范围 | -| color_style | TINYINT | 否 | NULL | 划线颜色样式 | -| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 | - -**索引**： -- PRIMARY KEY (id) -- idx_highlights_book_id (book_id) -- idx_highlights_chapter (book_id, chapter_uid) - -**记录数**：142 - ---- - -### 3.15 book_chapters - 章节信息表 - -> 来自微信读书 /book/bookmarklist 接口的 chapters 字段 - -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| -| id | BIGINT | 是 (PK) | AUTO | 自增主键 | -| book_id | VARCHAR(64) | 是 | - | 书籍 ID | -| chapter_uid | INT UNSIGNED | 是 | - | 章节 UID | -| chapter_idx | INT UNSIGNED | 否 | NULL | 章节序号 | -| title | VARCHAR(255) | 否 | NULL | 章节标题 | - -**索引**： -- PRIMARY KEY (id) -- UNIQUE KEY uk_book_chapter (book_id, chapter_uid) - -**记录数**：77 - ---- - -### 3.16 book_reviews - 个人想法/点评表 - -> 来自微信读书 /review/list/mine 接口 - -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| -| id | BIGINT | 是 (PK) | AUTO | 自增主键 | -| book_id | VARCHAR(64) | 是 | - | 书籍 ID | -| review_id | VARCHAR(64) | 否 | NULL | 想法唯一 ID | -| content | LONGTEXT | 否 | NULL | 想法内容文本 | -| create_time | INT UNSIGNED | 否 | NULL | 创建时间 (Unix 时间戳) | -| star | TINYINT | 否 | -1 | 评分 (0-5, -1=无评分) | -| chapter_name | VARCHAR(255) | 否 | NULL | 所在章节名称 | -| is_finish | TINYINT(1) | 否 | 0 | 是否书评 (1=书评) | -| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 | - -**索引**： -- PRIMARY KEY (id) -- idx_reviews_book_id (book_id) - -**记录数**：19 - ---- - -### 3.17 recommended_books - 推荐书籍表 - -> 来自微信读书 /book/recommend 接口 - -| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 | -|--------|----------|----------|--------|------| +| 字段名 | 数据类型 | 必填 | 默认值 | 说明 | +|--------|----------|------|--------|------| | id | BIGINT | 是 (PK) | AUTO | 自增主键 | | book_id | VARCHAR(64) | 是 | - | 书籍 ID | | title | VARCHAR(255) | 否 | NULL | 书名 | @@ -424,24 +676,69 @@ | new_rating | DECIMAL(5,1) | 否 | 0 | 评分 (百分制) | | new_rating_count | INT UNSIGNED | 否 | 0 | 评分人数 | | rating_title | VARCHAR(32) | 否 | NULL | 评分标签 (神作/力荐等) | -| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_recommended_book_id (book_id) -- idx_recommended_fetched (fetched_at DESC) - -**记录数**：48 +**索引**：PK(id), idx_recommended_book_id(book_id), idx_recommended_batch(batch_id), idx_recommended_rating(new_rating DESC) --- -### 3.18 search_results - 搜索结果表 +### 3.28 similar_books — 相似书推荐 -> 来自微信读书 /store/search 接口 +> 来源：`/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 | 书名 | @@ -454,15 +751,34 @@ | new_rating | DECIMAL(5,1) | 否 | 0 | 评分 (百分制) | | new_rating_count | INT UNSIGNED | 否 | 0 | 评分人数 | | rating_title | VARCHAR(32) | 否 | NULL | 评分标签 | -| search_idx | INT UNSIGNED | 否 | 0 | 搜索序号 | -| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 | +| 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 | 记录更新时间 | -**索引**： -- PRIMARY KEY (id) -- idx_search_keyword (keyword) -- idx_search_book_id (book_id) +**索引**：PK(id), idx_search_results_keyword(keyword), idx_search_results_book_id(book_id), idx_search_results_session(session_id) -**记录数**：20 +--- + +### 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) --- @@ -472,19 +788,29 @@ ``` 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 ──── notebooks (笔记本概览) [1:1 有笔记的书] + ├── 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 关联] + └── 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) @@ -494,8 +820,10 @@ archives (书单) ### 4.2 逻辑分组 -- **静态数据组**（采集时全量写入）：books, reading_stats, read_times, read_longest, prefer_categories, prefer_authors, prefer_time, notebooks, read_stat_items, archives, fetch_meta -- **动态数据组**（用户操作时按需写入）：book_details, book_progress, book_highlights, book_chapters, book_reviews, recommended_books, search_results +| 分组 | 表名 | 说明 | +|------|------|------| +| **静态数据组**（采集时全量写入） | 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 张表 | --- @@ -505,14 +833,15 @@ archives (书单) |------------|------|------------------| | VARCHAR(n) | 变长字符串（书名、作者等） | TEXT | | LONGTEXT | 长文本（简介、划线内容） | TEXT | -| TEXT | 中等文本 | TEXT | +| TEXT | 中等文本（JSON、简介等） | TEXT | | INT UNSIGNED | 无符号整数（时间戳、计数） | INTEGER | | TINYINT(1) | 布尔值（0/1） | INTEGER | -| TINYINT UNSIGNED | 小范围整数（小时 0-23、进度 0-100） | INTEGER | +| TINYINT | 小范围整数（评分、类型） | INTEGER | +| TINYINT UNSIGNED | 小范围无符号整数（小时 0-23、进度 0-100） | INTEGER | | BIGINT | 自增主键 | INTEGER | | DECIMAL(5,1) | 精度数值（评分） | REAL | -| DOUBLE | 浮点数（权重、日均时长） | REAL | -| TIMESTAMP | 时间戳（自动维护） | INTEGER (Unix 时间戳) | +| DOUBLE | 浮点数（权重、日均时长、热度分数） | REAL | +| TIMESTAMP | 时间戳（自动维护 + _dt 可读列） | TEXT (ISO 格式) | --- @@ -522,3 +851,18 @@ archives (书单) - 排序规则：`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 | (用户信息未入库) | diff --git a/docs/TECHNICAL_DOC.md b/docs/TECHNICAL_DOC.md index 4b02e65..ba7c4e8 100644 --- a/docs/TECHNICAL_DOC.md +++ b/docs/TECHNICAL_DOC.md @@ -1,6 +1,6 @@ # 微信读书数据展示网站 - 技术文档 -> 版本：1.2.0 | 更新时间：2026-07-17 | 作者：WorkBuddy +> 版本：2.0.0 | 更新时间：2026-07-17 | 作者：WorkBuddy | 数据模型版本：v2.0（31 表） --- @@ -31,8 +31,8 @@ | 前端 | HTML5 + CSS3 + 原生 JavaScript | 无框架依赖，轻量高效 | | 图表 | ECharts 5.5.0 | 年度趋势、时段分布、分类饼图、作者排行 | | 后端 | Python Flask | 轻量级 Web 框架，提供 RESTful API | -| 数据库 | MySQL 5.7+（主）/ SQLite（采集） | MySQL 为生产数据库，SQLite 用于数据采集中间存储 | -| 数据采集 | 微信读书 Agent Gateway API | 通过 weread-skills 技能提供的 API 接口 | +| 数据库 | MySQL 5.7+（主）/ SQLite（采集） | MySQL 为生产数据库，31 张表完整覆盖官方 API，SQLite 用于数据采集中间存储 | +| 数据采集 | 微信读书 Agent Gateway API | 通过 weread-skills 技能提供的 API 接口，覆盖 8 份官方 API 文档 | | 版本控制 | Git | dev 分支开发，master 分支发布，遵循 Conventional Commits | --- @@ -278,7 +278,30 @@ HTTP 503 Service Unavailable - 连接失败时显示固定告警横幅，阻止后续数据加载 - 使用 `db_required` 装饰器统一处理数据库连接异常 -### 4.4 Git 分支策略 +### 4.4 数据模型 v2.0 设计规范 + +基于微信读书官方 8 份 API 文档的完整字段分析，数据模型 v2.0 遵循以下设计规范： + +**双列时间戳模式**：所有整型 Unix 时间戳字段（`INT UNSIGNED`）均伴随一个 `_dt TIMESTAMP` 列，例如 `update_time` ↔ `update_time_dt`。便于直接查询展示，同时保留原始时间戳用于排序和计算。 + +**审计列**：每张表统一维护 `created_at`（创建时间）和 `updated_at`（更新时间），使用 MySQL `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` 自动维护。 + +**索引设计原则**： +- 主键：业务主键优先（如 `book_id`），无自然主键时使用 `BIGINT AUTO_INCREMENT` +- 唯一约束：防止重复数据（如 `uk_highlights_bookmark(book_id, bookmark_id)`） +- 复合索引：按实际查询模式设计（如 `idx_highlights_chapter(book_id, chapter_uid)`） +- 排序索引：常用排序字段加 `DESC`（如 `idx_books_read_update_time(read_update_time DESC)`） + +**表覆盖范围**：31 张表完整覆盖 8 份官方 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 +- fetch_meta → 系统元信息 + +### 4.5 Git 分支策略 - **dev 分支**：日常开发，功能迭代 - **master 分支**：稳定发布版本，通过 `--no-ff` 合并 dev