WeReadBoard/docs/technical-guide.md

阅间设计 Demo 使用说明

范围与启动

这是独立的静态设计 Demo，不调用微信读书接口，不需要 API Key，也不修改现有 Flask 服务、数据采集脚本和 8080 页面。功能与接口的后续实现进度统一维护在 功能目标清单。

该 Demo 是历史设计探索，用于保留早期交互样例，不代表当前正式入口。

在项目根目录执行：

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。刷新后保留；更换浏览器、地址或端口不会自动迁移；清除网站数据会清除本地目标。

书单加入目标时保存当前书籍集合，后续不自动跟随书单变化。同一目标内书籍去重，已读完直接计为完成。新增目标必须有名称、有效时间范围和至少一本书。

本地存储读取失败时显示示例目标并提示，不自动覆盖原存储；保存失败时保留编辑表单并提示重试。

所有阅读数据、书单成员、封面、目录、笔记和点评都是示例。用户编辑的目标只保存在本机，不会写回微信读书。公开书单完整成员获取方式仍需接口验证。

使用入口

• 阅读目标：新建目标，填写日期，勾选书籍或点击书单快捷加入，保存后可再编辑。
• 我的书架：切换我的书单、有声书、文章收藏与阅读状态。
• 发现好书：选择搜索类型；右侧预览状态可查看加载、空结果、失败及重试效果。
• 书籍详情：从卡片进入，切换目录、个人笔记、热门划线、点评、相似推荐。
• 笔记：按书目和类型筛选，导出当前书目的划线与想法，书签仅显示数量。

验证

语法检查：

node --check web-demo/app.js
node --check web-demo/demo-data.js

交互验收记录见 功能目标清单。真实 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 配置，不新增依赖。服务仍使用当前个人账号的数据；多个浏览器连接同一服务时共享目标，没有新增多用户隔离。

部署新代码前，在项目根目录执行一次迁移。下面的命令复用服务配置，只创建两张目标表，不修改已有业务表：

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 服务。

当前服务器配置可按下列默认值使用：

PROJECT_DIR=/opt/weread-board/WeReadBoard
SERVICE_NAME=weread.service
VENV_DIR=/opt/weread-board/WeReadBoard/.venv

GitHub Actions 文件位于 .github/workflows/deploy.yml，默认在 dev 分支 push 后触发，也支持手动触发。仓库需要在 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

如果在服务器手动部署，可执行：

cd /opt/weread-board/WeReadBoard
DEPLOY_BRANCH=dev ./deploy.sh

deploy.sh 会优先读取项目根目录 .env；没有 .env 时，会读取 weread.service 当前 Environment= 配置。按截图中的 service 写法也能拿到端口、API Key 和数据库配置。若以后改用普通部署用户，需要允许该用户免密执行 systemctl restart weread.service。

浏览器旧目标不会自动覆盖数据库。在原访问地址打开“阅读目标”，点击“导入已有目标”；数据库已有同一 ID 时跳过，整批成功才标记导入完成。weread-goals 原数据保留，weread-goals-imported 只记录已导入。不同浏览器、域名和端口的旧存储需要分别在原地址导入。

保存失败会保留表单并提示重试；读取失败显示错误和重试按钮，不冒充空列表。若新建提示 ID 已存在，刷新目标列表确认上次请求是否已经保存。数据库不可用或尚未执行迁移时，目标接口返回 503，不退回浏览器保存。

验证命令：

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 宽，概览、书架和目标页均未出现横向溢出。

dev 自动部署

dev 分支 push 后由 .github/workflows/deploy.yml 触发部署。Actions 通过仓库 Secrets 登录服务器，在 DEPLOY_PATH 指定的目录先拉取 origin/dev，再执行根目录 deploy.sh，完成加载可选 .env、安装 Python 依赖、执行阅读目标表迁移和重启 systemd 服务。详细配置见 docs/deploy-dev.md。

本次数据库验收已在 8080 正式看板完成：页面新建目标后刷新仍可读取，编辑后再次刷新仍可读取，并已清理临时验收目标。读取目标列表未完成时，新建和编辑入口只显示目标页的加载或错误状态，不会打开保存表单。