mirror of
https://github.com/KingHWJ/WeReadBoard.git
synced 2026-11-03 18:24:58 +08:00
109 lines
6.6 KiB
Markdown
109 lines
6.6 KiB
Markdown
# 阅间设计 Demo 使用说明
|
|
|
|
## 范围与启动
|
|
|
|
这是独立的静态设计 Demo，不调用微信读书接口，不需要 API Key，也不修改现有 Flask 服务、数据采集脚本和 8080 页面。功能与接口的后续实现进度统一维护在 [功能目标清单](feature-checklist.md)。
|
|
|
|
该 Demo 定位为 2.0 设计探索。当前提交用于保存探索成果，不代表 2.0 正式发布，也不创建 `v2.0` 标签。
|
|
|
|
在项目根目录执行：
|
|
|
|
```sh
|
|
python3 -m http.server 8765 --bind 127.0.0.1 --directory web-demo
|
|
```
|
|
|
|
访问 `http://127.0.0.1:8765`。也可以直接打开 `web-demo/index.html`；推荐通过本地服务器使用，以便浏览器稳定保存目标数据。
|
|
|
|
无需安装前端依赖。页面由以下文件构成：
|
|
|
|
| 文件 | 内容 |
|
|
|---|---|
|
|
| `web-demo/index.html` | 页面外壳、导航、详情与目标编辑弹窗 |
|
|
| `web-demo/styles.css` | 暗亮主题、书封示意、响应式排版 |
|
|
| `web-demo/demo-data.js` | 书籍、书单、初始目标、笔记与点评样例 |
|
|
| `web-demo/app.js` | 页面渲染、目标操作、搜索筛选、导出 |
|
|
|
|
## 保存与数据边界
|
|
|
|
目标使用当前来源的 `localStorage` 键 `weread-demo-goals-v2`，主题使用 `weread-demo-theme`。刷新后保留；更换浏览器、地址或端口不会自动迁移；清除网站数据会清除本地目标。
|
|
|
|
书单加入目标时保存当前书籍集合，后续不自动跟随书单变化。同一目标内书籍去重，已读完直接计为完成。新增目标必须有名称、有效时间范围和至少一本书。
|
|
|
|
本地存储读取失败时显示示例目标并提示，不自动覆盖原存储；保存失败时保留编辑表单并提示重试。
|
|
|
|
所有阅读数据、书单成员、封面、目录、笔记和点评都是示例。用户编辑的目标只保存在本机，不会写回微信读书。公开书单完整成员获取方式仍需接口验证。
|
|
|
|
## 使用入口
|
|
|
|
- 阅读目标：新建目标，填写日期，勾选书籍或点击书单快捷加入，保存后可再编辑。
|
|
- 我的书架：切换我的书单、有声书、文章收藏与阅读状态。
|
|
- 发现好书：选择搜索类型；右侧预览状态可查看加载、空结果、失败及重试效果。
|
|
- 书籍详情：从卡片进入，切换目录、个人笔记、热门划线、点评、相似推荐。
|
|
- 笔记：按书目和类型筛选，导出当前书目的划线与想法，书签仅显示数量。
|
|
|
|
## 验证
|
|
|
|
语法检查：
|
|
|
|
```sh
|
|
node --check web-demo/app.js
|
|
node --check web-demo/demo-data.js
|
|
```
|
|
|
|
交互验收记录见 [功能目标清单](feature-checklist.md)。真实 API、鉴权、分页和服务器持久化尚未验证。
|
|
|
|
## 与 1.0 的关系
|
|
|
|
1.0 继续由根目录的 `app.py`、`fetch_data.py`、`templates/` 和 `static/` 提供，运行在 8080 端口。2.0 探索 Demo 位于 `web-demo/`，两者可以独立预览。
|
|
|
|
## 正式看板的紧凑样式
|
|
|
|
正式看板由 `templates/index.html` 和 `static/css/styles.css` 提供，使用现有启动方式，不新增依赖、配置或环境变量。上文的 `web-demo/` 是独立的历史设计 Demo，本次样式调整仅应用于正式看板。
|
|
|
|
刷新正式看板即可加载样式；若浏览器仍显示旧间距，强制刷新页面。检查阅读概览、我的书架、阅读目标在桌面和手机宽度下的展示，并切换暗色主题。目标数据的保存方式由当前应用逻辑决定，样式不参与存储。
|
|
|
|
## 正式看板的阅读目标数据库
|
|
|
|
正式页面的目标通过 `/api/v2/goals` 保存到 MySQL。浏览器只保留编辑草稿和页面状态，刷新或换浏览器后从同一服务读取目标。上文 `web-demo/` 的本地存储说明仅适用于静态 Demo。
|
|
|
|
沿用 `api_v2.py` 的 `WEREAD_DB_HOST`、`WEREAD_DB_PORT`、`WEREAD_DB_USER`、`WEREAD_DB_PASSWORD` 和 `WEREAD_DB_NAME` 配置，不新增依赖。服务仍使用当前个人账号的数据；多个浏览器连接同一服务时共享目标，没有新增多用户隔离。
|
|
|
|
部署新代码前，在项目根目录执行一次迁移。下面的命令复用服务配置，只创建两张目标表，不修改已有业务表：
|
|
|
|
```sh
|
|
python3 - <<'PY'
|
|
from pathlib import Path
|
|
import pymysql
|
|
from api_v2 import MYSQL_CONFIG
|
|
|
|
with pymysql.connect(**MYSQL_CONFIG) as conn:
|
|
with conn.cursor() as cur:
|
|
for sql in Path('migrations/001_reading_goals.sql').read_text().split(';'):
|
|
if sql.strip():
|
|
cur.execute(sql)
|
|
print('阅读目标表已就绪')
|
|
PY
|
|
PORT=8080 python3 app.py
|
|
```
|
|
|
|
使用已安装 `requirements.txt` 的 Python 环境。若 8080 已有本项目实例，先停止旧实例再启动，使 Flask 加载新接口。迁移可重复执行；运行账户需要目标表的读写权限。目标表不参与 `fetch_data.py` 的采集覆盖。
|
|
|
|
浏览器旧目标不会自动覆盖数据库。在原访问地址打开“阅读目标”，点击“导入已有目标”；数据库已有同一 ID 时跳过，整批成功才标记导入完成。`weread-goals-v2` 原数据保留，`weread-goals-v2-imported` 只记录已导入。不同浏览器、域名和端口的旧存储需要分别在原地址导入。
|
|
|
|
保存失败会保留表单并提示重试；读取失败显示错误和重试按钮，不冒充空列表。若新建提示 ID 已存在，刷新目标列表确认上次请求是否已经保存。数据库不可用或尚未执行迁移时，目标接口返回 503，不退回浏览器保存。
|
|
|
|
验证命令：
|
|
|
|
```sh
|
|
python3 -m unittest discover -s tests -p 'test_reading_goals*.py' -v
|
|
node --test tests/goals_frontend.test.cjs
|
|
node --check static/js/app.js
|
|
node --check static/js/weapi.js
|
|
```
|
|
|
|
真实数据库验证需先执行迁移，再显式运行 `WEREAD_TEST_MYSQL=1 python3 -m unittest discover -s tests -p 'test_reading_goals_mysql.py' -v`。测试创建唯一测试目标并清理，只操作本次生成的 ID。
|
|
|
|
本次样式收紧覆盖正式看板的概览、书架和阅读目标页。顶栏、标题区、筛选区、统计卡、书架网格、右侧目标摘要、目标介绍区和目标卡片均使用覆盖规则压缩占位；书架在窄屏固定两列，避免横向溢出。本地真实数据验收覆盖 1280 px 桌面和 390 px 手机宽度：桌面顶栏 58 px，统计卡从约 200 px 开始，书架一行 7 本，目标页介绍区约 67 px 高，目标卡约 317 px 宽；手机顶栏 56 px，书架两列，目标卡约 298 px 宽，概览、书架和目标页均未出现横向溢出。
|
|
|
|
本次数据库验收已在 8080 正式看板完成：页面新建目标后刷新仍可读取，编辑后再次刷新仍可读取，并已清理临时验收目标。读取目标列表未完成时，新建和编辑入口只显示目标页的加载或错误状态，不会打开保存表单。
|