docs: update technical and metadata docs for v2.0 (31 tables)

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 用于数据采集中间存储 |
+| 数据库 | MySQL 5.7+（主）/ SQLite（采集） | MySQL 为生产数据库，31 张表完整覆盖官方 API，SQLite 用于数据采集中间存储 |
-| 数据采集 | 微信读书 Agent Gateway API | 通过 weread-skills 技能提供的 API 接口 |
+| 数据采集 | 微信读书 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