mirror of
https://github.com/KingHWJ/WeReadBoard.git
synced 2026-11-03 18:24:58 +08:00
156 lines
9.4 KiB
Markdown
156 lines
9.4 KiB
Markdown
# 阅间设计 Demo 使用说明
|
||
|
||
## 范围与启动
|
||
|
||
这是独立的静态设计 Demo，不调用微信读书接口，不需要 API Key，也不修改现有 Flask 服务、数据采集脚本和 8080 页面。功能与接口的后续实现进度统一维护在 [功能目标清单](feature-checklist.md)。
|
||
|
||
该 Demo 是历史设计探索，用于保留早期交互样例，不代表当前正式入口。
|
||
|
||
在项目根目录执行：
|
||
|
||
```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`，主题使用 `weread-demo-theme`。刷新后保留；更换浏览器、地址或端口不会自动迁移；清除网站数据会清除本地目标。
|
||
|
||
书单加入目标时保存当前书籍集合，后续不自动跟随书单变化。同一目标内书籍去重，已读完直接计为完成。新增目标必须有名称、有效时间范围和至少一本书。
|
||
|
||
本地存储读取失败时显示示例目标并提示，不自动覆盖原存储；保存失败时保留编辑表单并提示重试。
|
||
|
||
所有阅读数据、书单成员、封面、目录、笔记和点评都是示例。用户编辑的目标只保存在本机，不会写回微信读书。公开书单完整成员获取方式仍需接口验证。
|
||
|
||
## 使用入口
|
||
|
||
- 阅读目标：新建目标，填写日期，勾选书籍或点击书单快捷加入，保存后可再编辑。
|
||
- 我的书架：切换我的书单、有声书、文章收藏与阅读状态。
|
||
- 发现好书：选择搜索类型；右侧预览状态可查看加载、空结果、失败及重试效果。
|
||
- 书籍详情：从卡片进入，切换目录、个人笔记、热门划线、点评、相似推荐。
|
||
- 笔记：按书目和类型筛选，导出当前书目的划线与想法，书签仅显示数量。
|
||
|
||
## 验证
|
||
|
||
语法检查：
|
||
|
||
```sh
|
||
node --check web-demo/app.js
|
||
node --check web-demo/demo-data.js
|
||
```
|
||
|
||
交互验收记录见 [功能目标清单](feature-checklist.md)。真实 API、鉴权、分页和服务器持久化尚未验证。
|
||
|
||
## 与旧版的关系
|
||
|
||
旧版仪表盘已归档到 `legacy/classic/`。当前正式看板由根目录的 `app.py`、`fetch_data.py`、`templates/` 和 `static/` 提供；历史设计 Demo 位于 `web-demo/`，两者可以独立预览。
|
||
|
||
## 正式看板的紧凑样式
|
||
|
||
正式看板由 `templates/index.html` 和 `static/css/styles.css` 提供，使用现有启动方式，不新增依赖、配置或环境变量。上文的 `web-demo/` 是独立的历史设计 Demo，本次样式调整仅应用于正式看板。
|
||
|
||
刷新正式看板即可加载样式；若浏览器仍显示旧间距，强制刷新页面。检查阅读概览、我的书架、阅读目标在桌面和手机宽度下的展示，并切换暗色主题。目标数据的保存方式由当前应用逻辑决定，样式不参与存储。
|
||
|
||
## 正式看板的阅读目标数据库
|
||
|
||
正式页面的目标通过 `/api/reading/goals` 保存到 MySQL。浏览器只保留编辑草稿和页面状态，刷新或换浏览器后从同一服务读取目标。上文 `web-demo/` 的本地存储说明仅适用于静态 Demo。
|
||
|
||
沿用 `reading_api.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 reading_api 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` 的采集覆盖。
|
||
|
||
## GitHub 自动部署
|
||
|
||
服务器部署使用根目录的 `deploy.sh`。脚本会先拉取指定分支，再检测 Python 环境；若项目 `.venv` 不存在，会自动用系统 `python3` 或 `python` 创建 `.venv`，随后安装 `requirements.txt`、执行阅读目标迁移，并重启 systemd 服务。
|
||
|
||
当前服务器配置可按下列默认值使用：
|
||
|
||
```sh
|
||
PROJECT_DIR=/opt/weread-board/WeReadBoard
|
||
SERVICE_NAME=weread.service
|
||
VENV_DIR=/opt/weread-board/WeReadBoard/.venv
|
||
```
|
||
|
||
GitHub Actions 文件位于 `.github/workflows/deploy.yml`，只在 `master` 分支 push 后触发，也支持手动触发；手动触发同样固定部署 `master`。仓库需要在 `Settings -> Secrets and variables -> Actions -> Secrets` 配置：
|
||
|
||
| Secret | 说明 |
|
||
|---|---|
|
||
| `SERVER_HOST` | 服务器 IP |
|
||
| `SERVER_PORT` | SSH 端口，未配置时按 22 处理 |
|
||
| `SERVER_USER` | SSH 登录用户 |
|
||
| `SERVER_SSH_KEY` | GitHub Actions 登录服务器用的私钥 |
|
||
|
||
可选配置放在 `Settings -> Secrets and variables -> Actions -> Variables`：
|
||
|
||
| Variable | 说明 |
|
||
|---|---|
|
||
| `DEPLOY_PATH` | 可选，默认 `/opt/weread-board/WeReadBoard` |
|
||
| `SERVICE_NAME` | 可选，默认 `weread.service` |
|
||
|
||
如果在服务器手动部署，可执行：
|
||
|
||
```sh
|
||
cd /opt/weread-board/WeReadBoard
|
||
DEPLOY_BRANCH=master ./deploy.sh
|
||
```
|
||
|
||
`deploy.sh` 会优先读取项目根目录 `.env`；没有 `.env` 时，会读取 `weread.service` 当前 `Environment=` 配置。按截图中的 service 写法也能拿到端口、API Key 和数据库配置。若以后改用普通部署用户，需要允许该用户免密执行 `systemctl restart weread.service`。
|
||
|
||
浏览器旧目标不会自动覆盖数据库。在原访问地址打开“阅读目标”，点击“导入已有目标”；数据库已有同一 ID 时跳过，整批成功才标记导入完成。`weread-goals` 原数据保留，`weread-goals-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。
|
||
|
||
## 日常维护与故障排查
|
||
|
||
端口冲突、请求失败、Python 环境、HTTPS 证书和 systemd 服务的诊断步骤统一维护在 [日常维护与故障排查](troubleshooting.md)。接口路径、监听端口、Python 或 `.venv` 选择、启动脚本、systemd 配置以及部署流程发生变化时，必须同步更新该文档的运行基线；新故障按日期追加记录并保留历史结论。
|
||
|
||
正式服务只保留一个监听端口。首页可以打开但 API 失败时，应分别检查 `/api/reading/status`、`/api/reading/shelf` 和 `/api/reading/dashboard`，根据 404、502 或超时定位到路由、上游服务或 TLS 环境，不能只用首页 200 作为启动成功标准。
|
||
|
||
本次样式收紧覆盖正式看板的概览、书架和阅读目标页。顶栏、标题区、筛选区、统计卡、书架网格、右侧目标摘要、目标介绍区和目标卡片均使用覆盖规则压缩占位；书架在窄屏固定两列，避免横向溢出。本地真实数据验收覆盖 1280 px 桌面和 390 px 手机宽度：桌面顶栏 58 px，统计卡从约 200 px 开始，书架一行 7 本，目标页介绍区约 67 px 高，目标卡约 317 px 宽；手机顶栏 56 px，书架两列，目标卡约 298 px 宽，概览、书架和目标页均未出现横向溢出。
|
||
|
||
## master 自动部署
|
||
|
||
`master` 分支 push 后由 `.github/workflows/deploy.yml` 触发部署。Actions 通过仓库 Secrets 登录服务器，在 `DEPLOY_PATH` 指定的目录先拉取 `origin/master`，再执行根目录 `deploy.sh`，完成加载可选 `.env`、安装 Python 依赖、执行阅读目标表迁移和重启 systemd 服务。`dev` 和其他分支不会触发部署，部署脚本也会拒绝非 `master` 分支。详细配置见 [master 自动部署](deploy-master.md)。
|
||
|
||
本次数据库验收已在 8080 正式看板完成：页面新建目标后刷新仍可读取，编辑后再次刷新仍可读取，并已清理临时验收目标。读取目标列表未完成时，新建和编辑入口只显示目标页的加载或错误状态，不会打开保存表单。
|