feat: switch to MySQL, add Chinese comments, health check, and technical docs

1. 数据源切换至 MySQL： - app.py 从 SQLite 切换到 PyMySQL，所有 API 读取 MySQL weread_dashboard 数据库 - 新增 db_required 装饰器统一管理数据库连接和异常处理 - 新增 /api/health 健康检查接口，检测 MySQL 连接状态 - MySQL 连接失败时返回 HTTP 503 和告警信息 - 修复 fetched_at 字段 Unix 时间戳到 MySQL TIMESTAMP 的兼容问题 2. 前端数据库连接告警： - 页面加载时优先调用 /api/health 检查 MySQL 连接 - 连接失败时显示固定告警横幅，阻止后续数据加载 - CSS 告警横幅样式（黄色背景、下滑动画） 3. 代码中文注释： - app.py：所有函数、API 接口、工具函数添加完整中文文档注释 - fetch_data.py：所有 SQLite 建表语句添加列级中文注释 - migrate_to_mysql.py：保留已有中文注释 4. 技术文档与元数据文档： - docs/TECHNICAL_DOC.md：项目概述、系统架构、API 设计、部署指南 - docs/METADATA_DOC.md：18 张表完整字段说明、索引、表关系、数据类型规范
2026-11-03 18:24:58 +08:00 · 2026-07-17 10:26:07 +08:00
1 parent 72e9971a69
commit 507b9c5704
@@ -0,0 +1,524 @@
+# 微信读书数据展示网站 - 元数据文档
+
+> 版本：1.2.0 | 更新时间：2026-07-17 | 数据库：MySQL weread_dashboard
+
+---
+
+## 1. 数据库概览
+
+| 属性 | 值 |
+|------|-----|
+| 数据库名称 | weread_dashboard |
+| 字符集 | utf8mb4 |
+| 排序规则 | utf8mb4_unicode_ci |
+| 存储引擎 | InnoDB |
+| 表数量 | 18 |
+| 数据总量 | 862 行 |
+
+---
+
+## 2. 表分类
+
+| 分类 | 表名 | 说明 | 数据来源 |
+|------|------|------|----------|
+| **基础数据** | 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 | 搜索结果 | 用户搜索时获取 |
+
+---
+
+## 3. 表结构详情
+
+### 3.1 books - 书架书籍表
+
+> 存储用户书架中的所有书籍基本信息
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 时间戳) |
+| secret | TINYINT(1) | 是 | 0 | 是否私密 (1=私密) |
+| is_top | TINYINT(1) | 是 | 0 | 是否置顶 (1=置顶) |
+| update_time | INT UNSIGNED | 否 | NULL | 书籍更新时间 (Unix 时间戳) |
+| deep_link | VARCHAR(512) | 否 | NULL | 微信读书深度链接 |
+
+**索引**：
+- PRIMARY KEY (book_id)
+- idx_books_category (category)
+- idx_books_finish_reading (finish_reading)
+- idx_books_read_update_time (read_update_time DESC)
+
+**记录数**：404
+
+---
+
+### 3.2 reading_stats - 阅读统计概要表
+
+> 存储总体和年度的阅读统计数据
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
+| mode | VARCHAR(20) | 是 | - | 统计维度: overall/annually |
+| period | VARCHAR(20) | 是 | '' | 周期标识: "overall" 或 "2026" |
+| total_read_time | INT UNSIGNED | 是 | 0 | 总阅读时长 (秒) |
+| read_days | INT UNSIGNED | 是 | 0 | 有效阅读天数 |
+| day_average_read_time | DOUBLE | 否 | 0 | 日均阅读时长 (秒) |
+| regist_time | INT UNSIGNED | 否 | NULL | 用户注册时间 (Unix 时间戳) |
+| raw_json | LONGTEXT | 否 | NULL | 原始 API 返回 JSON |
+| created_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 记录创建时间 |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_reading_stats_mode (mode, period)
+
+**记录数**：2
+
+---
+
+### 3.3 read_times - 阅读时长时间序列表
+
+> 按年/月/日分桶的阅读时长数据
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
+| mode | VARCHAR(30) | 是 | - | 统计维度 (含 _daily 后缀) |
+| period | VARCHAR(20) | 是 | '' | 周期标识 |
+| bucket_timestamp | INT UNSIGNED | 是 | - | 分桶起始时间戳 |
+| duration | INT UNSIGNED | 是 | 0 | 阅读时长 (秒) |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_read_times_mode_period (mode, period)
+- idx_read_times_bucket (bucket_timestamp)
+
+**记录数**：21
+
+---
+
+### 3.4 read_longest - 阅读时长排行表
+
+> 阅读时间最久的书籍排名
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 | 阅读时长 (秒) |
+| tags | VARCHAR(512) | 否 | NULL | 标签 (JSON 数组) |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_read_longest_mode (mode, period)
+
+**记录数**：20
+
+---
+
+### 3.5 prefer_categories - 偏好分类表
+
+> 用户阅读的书籍分类统计
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 | 偏好权重 |
+| reading_time | INT UNSIGNED | 否 | 0 | 该分类阅读时长 (秒) |
+| reading_count | INT UNSIGNED | 否 | 0 | 该分类阅读本数 |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_prefer_cat_mode (mode, period)
+
+**记录数**：16
+
+---
+
+### 3.6 prefer_authors - 偏好作者表
+
+> 用户阅读最多的作者统计
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 | 阅读时长 (格式化字符串) |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_prefer_author_mode (mode, period)
+
+**记录数**：20
+
+---
+
+### 3.7 prefer_time - 24小时时段分布表
+
+> 一天中每个小时的阅读时长分布
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
+| mode | VARCHAR(20) | 是 | - | 统计维度 |
+| period | VARCHAR(20) | 是 | '' | 周期标识 |
+| hour_index | TINYINT UNSIGNED | 是 | - | 小时 (0-23) |
+| duration | INT UNSIGNED | 是 | 0 | 阅读时长 (秒) |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_prefer_time_mode (mode, period)
+
+**记录数**：24
+
+---
+
+### 3.8 notebooks - 笔记本概览表
+
+> 有笔记的书籍及其笔记统计
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 | 书签数 |
+| reading_progress | INT UNSIGNED | 是 | 0 | 阅读进度 (0-100) |
+| marked_status | TINYINT(1) | 是 | 0 | 标记状态 (1=读完) |
+| sort | BIGINT | 否 | NULL | 排序值 |
+
+**索引**：
+- PRIMARY KEY (book_id)
+
+**记录数**：32
+
+---
+
+### 3.9 read_stat_items - 统计摘要项表
+
+> App 首页展示的阅读统计摘要
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 跳转链接 |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_read_stat_items_mode (mode, period)
+
+**记录数**：8
+
+---
+
+### 3.10 archives - 书单归档表
+
+> 用户创建的书单
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
+| name | VARCHAR(255) | 否 | NULL | 书单名称 |
+| book_ids | LONGTEXT | 否 | NULL | 书籍 ID 列表 (JSON 数组) |
+
+**索引**：
+- PRIMARY KEY (id)
+
+**记录数**：6
+
+---
+
+### 3.11 fetch_meta - 采集元信息表
+
+> 记录数据采集的元信息
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| key | VARCHAR(64) | 是 (PK) | - | 元信息键名 |
+| value | TEXT | 否 | NULL | 元信息值 |
+
+**索引**：
+- PRIMARY KEY (key)
+
+**记录数**：1
+
+---
+
+### 3.12 book_details - 书籍详细信息表
+
+> 来自微信读书 /book/info 接口，用户点击书籍时按需获取
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 | 评分人数 |
+| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 |
+
+**索引**：
+- PRIMARY KEY (book_id)
+
+**记录数**：1
+
+---
+
+### 3.13 book_progress - 阅读进度表
+
+> 来自微信读书 /book/getprogress 接口
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 时间戳) |
+| record_reading_time | INT UNSIGNED | 否 | 0 | 累计阅读时长 (秒) |
+| finish_time | INT UNSIGNED | 否 | NULL | 读完时间 (Unix 时间戳) |
+| is_start_reading | TINYINT(1) | 是 | 0 | 是否已开始阅读 |
+| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 |
+
+**索引**：
+- PRIMARY KEY (book_id)
+
+**记录数**：1
+
+---
+
+### 3.14 book_highlights - 划线内容表
+
+> 来自微信读书 /book/bookmarklist 接口
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| 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 | 书名 |
+| 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 | 评分标签 (神作/力荐等) |
+| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_recommended_book_id (book_id)
+- idx_recommended_fetched (fetched_at DESC)
+
+**记录数**：48
+
+---
+
+### 3.18 search_results - 搜索结果表
+
+> 来自微信读书 /store/search 接口
+
+| 字段名 | 数据类型 | 是否必填 | 默认值 | 说明 |
+|--------|----------|----------|--------|------|
+| id | BIGINT | 是 (PK) | AUTO | 自增主键 |
+| 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 | 评分标签 |
+| search_idx | INT UNSIGNED | 否 | 0 | 搜索序号 |
+| fetched_at | TIMESTAMP | 是 | CURRENT_TIMESTAMP | 获取时间 |
+
+**索引**：
+- PRIMARY KEY (id)
+- idx_search_keyword (keyword)
+- idx_search_book_id (book_id)
+
+**记录数**：20
+
+---
+
+## 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 ──── notebooks (笔记本概览)        [1:1 有笔记的书]
+
+read_longest (阅读排行)
+  └── book_id ──── books (书架)                 [N:1 关联]
+
+recommended_books (推荐)
+  └── book_id (独立，不关联 books)
+
+search_results (搜索)
+  └── book_id (独立，不关联 books)
+
+archives (书单)
+  └── book_ids (JSON 数组，逻辑关联 books)
+```
+
+### 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
+
+---
+
+## 5. 数据类型规范
+
+| MySQL 类型 | 用途 | 对应 SQLite 类型 |
+|------------|------|------------------|
+| VARCHAR(n) | 变长字符串（书名、作者等） | TEXT |
+| LONGTEXT | 长文本（简介、划线内容） | TEXT |
+| TEXT | 中等文本 | TEXT |
+| INT UNSIGNED | 无符号整数（时间戳、计数） | INTEGER |
+| TINYINT(1) | 布尔值（0/1） | INTEGER |
+| TINYINT UNSIGNED | 小范围整数（小时 0-23、进度 0-100） | INTEGER |
+| BIGINT | 自增主键 | INTEGER |
+| DECIMAL(5,1) | 精度数值（评分） | REAL |
+| DOUBLE | 浮点数（权重、日均时长） | REAL |
+| TIMESTAMP | 时间戳（自动维护） | INTEGER (Unix 时间戳) |
+
+---
+
+## 6. 字符集与编码
+
+- 数据库字符集：`utf8mb4`（支持完整 Unicode，包括 Emoji）
+- 排序规则：`utf8mb4_unicode_ci`（不区分大小写，支持多语言排序）
+- 连接字符集：`utf8mb4`（PyMySQL 连接配置中指定）
+- 前端编码：`UTF-8`（HTML meta 标签声明）
@@ -0,0 +1,331 @@
+# 微信读书数据展示网站 - 技术文档
+
+> 版本：1.2.0 | 更新时间：2026-07-17 | 作者：WorkBuddy
+
+---
+
+## 1. 项目概述
+
+### 1.1 项目简介
+
+本项目是一个个人读书数据展示网站，数据来源于微信读书。通过微信读书 API 拉取用户的阅读数据（书架、阅读统计、笔记等），存入本地数据库，并通过 Web 仪表盘进行可视化展示。
+
+### 1.2 核心功能
+
+| 模块 | 功能说明 |
+|------|----------|
+| 数据采集 | 从微信读书 API 拉取书架、阅读统计、笔记本数据，存入本地数据库 |
+| 总览仪表盘 | 累计阅读时长、阅读天数、藏书量、笔记数等核心指标 |
+| 数据图表 | 年度阅读趋势（柱状图）、24h 时段分布（折线图）、偏好分类（饼图）、偏好作者（条形图） |
+| 读书排行 | 阅读时长最久的 20 本书卡片展示 |
+| 书架 | 404 本书的网格展示，支持分类筛选和"仅看已读完" |
+| 笔记概览 | 有笔记的书籍列表，点击查看划线和想法详情 |
+| 书籍详情 | 点击书架书籍弹出详情（书名、作者、出版社、ISBN、评分、阅读进度） |
+| 笔记详情 | 点击笔记书籍查看划线（按章节分组）和想法/点评 |
+| 推荐页面 | 个性化推荐书籍 + 关键词搜索，数据入库 |
+
+### 1.3 技术栈
+
+| 层级 | 技术 | 说明 |
+|------|------|------|
+| 前端 | HTML5 + CSS3 + 原生 JavaScript | 无框架依赖，轻量高效 |
+| 图表 | ECharts 5.5.0 | 年度趋势、时段分布、分类饼图、作者排行 |
+| 后端 | Python Flask | 轻量级 Web 框架，提供 RESTful API |
+| 数据库 | MySQL 5.7+（主）/ SQLite（采集） | MySQL 为生产数据库，SQLite 用于数据采集中间存储 |
+| 数据采集 | 微信读书 Agent Gateway API | 通过 weread-skills 技能提供的 API 接口 |
+| 版本控制 | Git | dev 分支开发，master 分支发布，遵循 Conventional Commits |
+
+---
+
+## 2. 系统架构
+
+### 2.1 整体架构图
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    用户浏览器（前端）                      │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │
+│  │ 总览仪表盘│ │ 数据图表 │ │ 书架列表 │ │ 推荐搜索 │       │
+│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘       │
+│       │           │           │           │              │
+│       └───────────┴─────┬─────┴───────────┘              │
+│                         │                                │
+│                ┌────────▼────────┐                       │
+│                │  健康检查模块    │                       │
+│                │  (MySQL 连接检测) │                       │
+│                └────────┬────────┘                       │
+└─────────────────────────┼───────────────────────────────┘
+                          │ HTTP / RESTful API
+┌─────────────────────────┼───────────────────────────────┐
+│                    Flask 后端服务                         │
+│                         │                                │
+│  ┌──────────────────────▼──────────────────────┐        │
+│  │              API 路由层                        │        │
+│  │  /api/overview  /api/shelf  /api/book/detail │        │
+│  │  /api/recommend /api/search /api/health ...  │        │
+│  └──────────────────────┬──────────────────────┘        │
+│                         │                                │
+│  ┌──────────────────────▼──────────────────────┐        │
+│  │           db_required 装饰器                  │        │
+│  │  (连接管理 + 错误处理 + 503 告警)              │        │
+│  └──────────────────────┬──────────────────────┘        │
+│                         │                                │
+│  ┌──────────────────────▼──────────────────────┐        │
+│  │           PyMySQL 数据访问层                   │        │
+│  └───────────┬──────────────────┬──────────────┘        │
+│              │                  │                        │
+│  ┌───────────▼─────┐  ┌────────▼─────────┐              │
+│  │  MySQL 数据库    │  │ 微信读书 API 代理 │              │
+│  │  weread_dashboard│  │ (按需获取+入库)   │              │
+│  └─────────────────┘  └──────────────────┘              │
+└─────────────────────────────────────────────────────────┘
+                          │
+┌─────────────────────────┼───────────────────────────────┐
+│                 数据采集层（独立运行）                      │
+│  ┌──────────────────────▼──────────────────────┐        │
+│  │           fetch_data.py 采集脚本              │        │
+│  │  拉取书架/统计/笔记 → SQLite → migrate_to_mysql│       │
+│  └──────────────────────────────────────────────┘        │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 2.2 数据流设计
+
+```
+微信读书 API
+    │
+    ▼
+fetch_data.py（采集脚本）
+    │
+    ▼
+weread.db（SQLite 中间存储）
+    │
+    ▼
+migrate_to_mysql.py（迁移脚本）
+    │
+    ▼
+MySQL weread_dashboard（生产数据库）
+    │
+    ▼
+Flask app.py（后端服务，端口 8080）
+    │
+    ▼
+前端页面（ECharts 可视化）
+```
+
+**按需数据流**（用户点击书籍/笔记时）：
+
+```
+用户点击 → Flask API → 微信读书 API（实时获取）→ 入库 MySQL → 返回前端
+                          ↓（API 失败时）
+                     从 MySQL 读取缓存数据 → 返回前端
+```
+
+### 2.3 目录结构
+
+```
+weread-dashboard/
+├── app.py                  # Flask 后端服务（MySQL 数据源）
+├── fetch_data.py           # 数据采集脚本（SQLite）
+├── migrate_to_mysql.py     # SQLite → MySQL 数据迁移脚本
+├── schema_mysql.sql        # MySQL 建表语句（含中文注释）
+├── requirements.txt        # Python 依赖
+├── weread.db               # SQLite 数据库文件（采集中间存储）
+├── README.md               # 项目说明
+├── docs/                   # 文档目录
+│   ├── TECHNICAL_DOC.md    # 技术文档（本文件）
+│   └── METADATA_DOC.md     # 元数据文档
+├── templates/
+│   └── index.html          # 前端页面
+└── static/
+    ├── css/
+    │   └── style.css       # 样式文件
+    └── js/
+        └── app.js          # 前端逻辑
+```
+
+---
+
+## 3. 后端 API 设计
+
+### 3.1 API 接口列表
+
+| 接口 | 方法 | 说明 | 数据来源 |
+|------|------|------|----------|
+| `/api/health` | GET | 健康检查（MySQL 连接状态） | MySQL |
+| `/api/overview` | GET | 总览数据（核心指标） | MySQL |
+| `/api/yearly-trend` | GET | 年度阅读时长时间序列 | MySQL |
+| `/api/top-books` | GET | 阅读时长排行 TOP 20 | MySQL |
+| `/api/categories` | GET | 偏好分类 | MySQL |
+| `/api/authors` | GET | 偏好作者 TOP 20 | MySQL |
+| `/api/time-distribution` | GET | 24 小时时段分布 | MySQL |
+| `/api/shelf` | GET | 书架列表（分页） | MySQL |
+| `/api/notebooks` | GET | 笔记本概览 | MySQL |
+| `/api/read-stats` | GET | 阅读统计摘要 | MySQL |
+| `/api/archives` | GET | 书单列表 | MySQL |
+| `/api/book/detail` | GET | 书籍详情（按需） | 微信读书 API + MySQL |
+| `/api/book/notes` | GET | 笔记详情（按需） | 微信读书 API + MySQL |
+| `/api/recommend` | GET | 个性化推荐（按需） | 微信读书 API + MySQL |
+| `/api/search` | GET | 搜索书籍（按需） | 微信读书 API + MySQL |
+
+### 3.2 接口详情
+
+#### 3.2.1 健康检查
+
+```
+GET /api/health
+```
+
+**响应（正常）**：
+```json
+{
+    "status": "ok",
+    "database": "connected",
+    "message": "MySQL 连接正常"
+}
+```
+
+**响应（异常，HTTP 503）**：
+```json
+{
+    "status": "error",
+    "database": "disconnected",
+    "message": "MySQL 连接失败: ..."
+}
+```
+
+#### 3.2.2 总览数据
+
+```
+GET /api/overview
+```
+
+**响应**：
+```json
+{
+    "total_read_time": 1223850,
+    "total_read_time_str": "339小时57分钟",
+    "read_days": 304,
+    "year_read_time": 849029,
+    "year_read_time_str": "235小时50分钟",
+    "year_read_days": 198,
+    "shelf_count": 404,
+    "finished_count": 12,
+    "notebook_count": 32,
+    "total_notes": 1709,
+    "regist_time": "2024-03-15",
+    "last_read_time": "2026-07-17",
+    "fetch_time": "2026-07-17 09:50:00"
+}
+```
+
+#### 3.2.3 书架列表（分页）
+
+```
+GET /api/shelf?page=1&per_page=60&category=文学&finished=1
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| page | int | 1 | 页码 |
+| per_page | int | 60 | 每页数量 |
+| category | string | "" | 分类筛选（模糊匹配） |
+| finished | string | "0" | "1"=只看已读完 |
+
+#### 3.2.4 书籍详情（按需）
+
+```
+GET /api/book/detail?book_id=34615967
+```
+
+实时调用微信读书 `/book/info` + `/book/getprogress` API，入库后返回。API 失败时回退到数据库缓存。
+
+#### 3.2.5 错误处理
+
+所有 API 接口在 MySQL 连接失败时统一返回：
+
+```
+HTTP 503 Service Unavailable
+{
+    "error": "数据库连接失败",
+    "detail": "具体错误信息",
+    "alert": "MySQL 数据库无法连接，请检查 MySQL 服务是否已启动。"
+}
+```
+
+---
+
+## 4. 关键设计决策
+
+### 4.1 数据库选择
+
+- **生产环境使用 MySQL**：支持并发访问、事务管理、完善的权限体系
+- **采集层使用 SQLite**：轻量级，无需额外服务，适合单机数据采集
+- **迁移脚本桥接**：`migrate_to_mysql.py` 负责 SQLite → MySQL 的数据同步
+
+### 4.2 按需获取策略
+
+书籍详情、笔记详情、推荐、搜索等数据采用**按需获取**策略：
+- 用户点击时实时调用微信读书 API
+- 获取成功后入库 MySQL 缓存
+- API 调用失败时自动回退到数据库缓存
+- 避免初始化时大量 API 调用，提升用户体验
+
+### 4.3 健康检查与告警机制
+
+- 后端提供 `/api/health` 接口检测 MySQL 连接状态
+- 前端页面加载时首先调用健康检查
+- 连接失败时显示固定告警横幅，阻止后续数据加载
+- 使用 `db_required` 装饰器统一处理数据库连接异常
+
+### 4.4 Git 分支策略
+
+- **dev 分支**：日常开发，功能迭代
+- **master 分支**：稳定发布版本，通过 `--no-ff` 合并 dev
+- 提交信息遵循 **Conventional Commits** 规范（`feat:` / `fix:` / `merge:`）
+
+---
+
+## 5. 部署与运行
+
+### 5.1 环境要求
+
+- Python 3.13+
+- MySQL 5.7+
+- 微信读书 API Key（通过 `WEREAD_API_KEY` 环境变量配置）
+
+### 5.2 启动步骤
+
+```bash
+# 1. 设置微信读书 API Key
+export WEREAD_API_KEY=wrk-xxxxxxxx
+
+# 2. 安装 Python 依赖
+pip install flask pymysql
+
+# 3. 启动 MySQL 服务
+sudo /usr/local/mysql/support-files/mysql.server start
+
+# 4. 创建数据库并建表
+mysql -u root -p < schema_mysql.sql
+
+# 5. 采集数据（首次）
+python fetch_data.py
+
+# 6. 迁移数据到 MySQL
+python migrate_to_mysql.py
+
+# 7. 启动 Web 服务
+python app.py
+# 访问 http://127.0.0.1:8080
+```
+
+### 5.3 数据更新
+
+```bash
+# 重新采集最新数据
+python fetch_data.py
+
+# 同步到 MySQL
+python migrate_to_mysql.py
+```