docs: 补充 v2 接口文档与验证截图，更新 README

- docs/V2_API.md 说明 /api/v2/* 各接口参数与回包结构
- docs/screenshots/ 归档概览/书架/笔记/详情/发现/暗色主题验证截图
- README 说明 v2 为默认前端、启动方式与 v1 归档位置

README.md

@@ -1,20 +1,29 @@
 # 微信读书数据展示网站
 
-基于微信读书 API 的个人读书数据展示网站，数据存储在本地 SQLite 数据库中。
+基于微信读书 API 的个人读书数据展示网站。
+
+- **v2「阅间」看板（当前默认前端）**：沿用设计稿的视觉与交互，数据来自 `/api/v2/*` 实时聚合接口，见 `docs/V2_API.md`。
+- **v1 仪表盘（已归档）**：原 ECharts 单页仪表盘，完整备份在 `legacy/v1/`。
 
 ## 项目结构
 
 ```
 .
 ├── fetch_data.py          # 数据采集脚本（从微信读书 API 拉取数据到 SQLite）
-├── app.py                 # Flask 后端服务
+├── app.py                 # Flask 后端服务（v1 接口 + 注册 v2 Blueprint）
+├── api_v2.py              # v2 数据接口层（/api/v2/*，供「阅间」前端使用）
+├── start_dashboard.sh     # 启动脚本（端口可用 PORT 覆盖）
+├── legacy/v1/             # v1 前端备份（index.html / style.css / app.js）
 ├── weread.db              # SQLite 数据库（运行 fetch_data.py 后生成）
 ├── requirements.txt       # Python 依赖
 ├── templates/
-│   └── index.html         # 前端页面
+│   └── index.html         # 「阅间」前端页面（v2 设计稿）
 └── static/
-    ├── css/style.css      # 样式文件
+    ├── css/styles.css     # v2 样式（设计稿原样）
-    └── js/app.js          # 前端逻辑
+    ├── css/style.css      # v1 样式（保留）
+    └── js/
+        ├── weapi.js       # v2 数据层（封装 /api/v2/*）
+        └── app.js         # v2 交互逻辑
 ```
 
 ## 快速开始
@@ -42,10 +51,15 @@ python fetch_data.py
 ### 4. 启动网站
 
 ```bash
-python app.py
+./start_dashboard.sh          # 默认 8770 端口
+PORT=8080 ./start_dashboard.sh # 或指定端口
 ```
 
-访问 http://127.0.0.1:8080 即可查看读书数据展示。
+也可以直接 `python app.py`（默认 8080，可用环境变量 `PORT` 覆盖），
+然后访问 http://127.0.0.1:8770 查看「阅间」看板。
+
+> v2 的书架、统计、推荐、搜索等数据实时来自微信读书接口；
+> 未运行 `fetch_data.py` 时也能使用，只有进度/笔记等局部数据会缺少缓存加速。
 
 ## 功能模块
 

docs/V2_API.md

@@ -0,0 +1,45 @@
+# v2 数据接口（/api/v2/*）
+
+「阅间」新版前端的数据来源。实现在 `api_v2.py`（Flask Blueprint，注册于 `app.py`），
+v1 的 `/api/*` 接口保持不变，两套接口可同时使用。
+
+## 数据来源与优先级
+
+| 数据 | 来源 | 说明 |
+|------|------|------|
+| 书架、书目 | 微信读书 `/shelf/sync`（实时，进程内缓存 10 分钟） | 字段含书名、作者、分类、封面、读完标记、最近阅读时间 |
+| 阅读统计（周/月/年/总） | 微信读书 `/readdata/detail`（实时，缓存 5 分钟） | 时长趋势、阅读天数、读得最多、偏好分类/作者/出版社/时段/勋章/好友排行 |
+| 阅读进度 | 本地 `notebooks` / `book_progress` 缓存优先，缺失时并发调用 `/book/getprogress` 补齐（缓存 10 分钟） | 用于书架卡片与详情页进度 |
+| 笔记本与笔记 | 本地 `notebooks` 表 + 实时 `/book/bookmarklist`、`/review/list/mine` | 划线与想法正文实时获取 |
+| 书籍详情 | 实时 `/book/info`、`/book/getprogress`、`/book/chapterinfo`、`/book/bestbookmarks`、`/review/list`、`/book/similar` | 逐项降级，单项失败不影响整页 |
+| 搜索 / 推荐 | 实时 `/store/search`（按 scope 切换类型）、`/book/recommend` | |
+| 阅读目标 | 浏览器 localStorage（key `weread-goals-v2`） | 与设计稿一致，不落库 |
+
+MySQL 不可用时接口仍可用（返回 `degraded: true`），依赖本地缓存的字段会退化为实时接口结果。
+
+## 接口清单
+
+| 方法 | 路径 | 参数 | 说明 |
+|------|------|------|------|
+| GET | `/api/v2/status` | — | 连接状态、书架规模、数据快照时间 |
+| GET | `/api/v2/shelf` | `tab=all\|reading\|done\|wish`、`keyword`、`limit`、`offset`、`progress=1` | 书架列表 + 书单 + 有声书 + 文章收藏入口（`progress=1` 为首屏书籍实时补拉进度） |
+| GET | `/api/v2/dashboard` | `period=week\|month\|year\|overall` | 整页概览：趋势柱状图、四张统计卡、读得最多、偏好方向、时段分布、阅读画像、年度小结 |
+| GET | `/api/v2/notebooks` | — | 笔记本概览（有笔记的书 + 划线/想法/书签数量） |
+| GET | `/api/v2/notes` | `book_id`（`all` 表示聚合笔记最多的前 N 本）、`limit` | 划线与想法正文，按时间倒序 |
+| GET | `/api/v2/book/<book_id>` | — | 书籍详情聚合：简介 + 进度 + 目录 + 我的笔记 + 热门划线 + 点评 + 相似推荐 |
+| GET | `/api/v2/book/<book_id>/reviews` | `type=0\|1\|2\|3\|4`（全部/推荐/不行/最新/一般）、`count` | 公开点评（按类型筛选） |
+| GET | `/api/v2/book/<book_id>/highlights` | `chapter_uid`（0=全书） | 热门划线（人数、章节、位置、跳转链接） |
+| GET | `/api/v2/book/<book_id>/underline-thoughts` | `chapter_uid`、`range` | 某条划线下的他人想法 |
+| GET | `/api/v2/thought/<review_id>` | — | 单条想法详情：正文、划线原文、点赞、评论 |
+| GET | `/api/v2/archives` | — | 书架书单及成员书籍 |
+| GET | `/api/v2/recommend` | `maxIdx` | 个性化推荐 |
+| GET | `/api/v2/search` | `keyword`、`scope=all\|books\|author\|lists\|audio\|fulltext\|novel\|account\|article` | 书城检索（按分组归一为书籍/作者/书单） |
+| POST | `/api/sync` | — | v1 已有：重新采集数据并迁移到 MySQL |
+
+## 与微信读书接口的字段口径
+
+- 评分：接口 `newRating` 为 0~1000，接口层换算成 `score = newRating / 100`（前端按设计稿公式展示为 `评分 XX/100`），详情页展示 `rating = newRating / 10`。
+- 封面：设计稿使用 4 种示意底色（`c1`~`c4`），由 `book_id` 哈希稳定映射；真实封面 URL 保留在 `cover_url`。
+- 进度：统一到 0~100 整数；`status` 口径为「读完=done、有最近阅读=reading、从未读过=wish」。
+- 周/月维度的统计接口不回偏好画像字段，接口层用「总计」口径补齐，并在 `preference_source` 中标注来源。
+- 「文章收藏」按接口规范计为 1 个书架条目（`books + albums + mp`）。