# 阅间 Demo 设计与数据流

## 页面分工

统计并入阅读概览；导航保留阅读概览、我的书架、阅读目标、笔记与划线、发现好书。概览展示阅读统计和目标摘要，目标页管理多份具体阅读清单。

完整功能、业务规则、接口落点与状态见 [功能目标清单](feature-checklist.md)。该清单先于本轮实现建立，后续代码开发继续追加和更新。

该设计探索已归档，当前正式看板由根目录 Flask 服务提供。

## 数据流

`demo-data.js` 提供样例书籍、书单及初始目标。`app.js` 根据当前页面和筛选条件渲染内容；用户输入写入目标草稿，验证通过后保存到浏览器，再更新目标列表。现有 Flask 服务和数据采集代码不参与本轮 Demo。

书籍卡片打开详情；详情页可选目录、个人笔记、热门划线、点评、相似书。个人笔记与公开点评使用不同数据集合。热门划线中的想法继续打开单条详情。

书籍、书单详情均可加入已有目标，也可带着已选内容创建新目标。

## 阅读目标口径与例子

目标字段：`id`、`name`、`start`、`end`、`ids`、`sources`。`ids` 存放去重后的书籍 ID；`sources` 记录曾加入的书单名称，作为来源说明，不表示持续关联。

例：单独选择已读完的《活着》，再加入包含《活着》《人生海海》《悉达多》的书单。保存后总数为 3 本、已读完为 1 本，进度为 33%。从目标中移除《人生海海》后，进度为 1 / 2，即 50%。

完成状态取书籍当前已读状态，不受目标起止日期约束。同一本书可计入多个目标。同一目标内不重复计数。

状态判断先检查是否全部读完，再检查日期。例如目标时间为未来一周，但其中两本书都已读完，直接显示已完成；尚未全部完成时，按日期显示未开始、进行中、已到期。

书单采用加入时的书目，不自动跟随外部增删。移除目标内一本书，只影响这个目标，不改变书架或其他目标。

## 实现位置

| 职责 | 位置 |
|---|---|
| 去重与完成率、状态 | `app.js`：`uniqueIds`、`goalMetrics` |
| 新建、编辑、书单混选 | `app.js`：`openGoalEditor`、`renderPicker`、`saveGoal` |
| 加入已有目标 | `app.js`：`chooseTarget`、`appendGoal` |
| 本地持久化与异常恢复 | `app.js`：初始加载、`persistGoals` |
| 页面与详情导航 | `app.js`：`navigate`、`renderPage`、`handleAction` |
| 笔记导出 | `app.js`：`exportNotes` |

用户输入的目标名称和来源在 HTML 渲染前转义。日期和内容在保存前校验；原生对话框提供焦点管理和 Escape 关闭。

## 部署流程

GitHub Actions 的 `.github/workflows/deploy.yml` 只做验证，不登录服务器。`master` push 后由 GitHub Webhook 向 `https://laohang.space/github/webhook` 发送 JSON，服务器上的 `deploy_webhook.py` 校验 HMAC-SHA256、仓库和 `master` 分支，再在固定目录调用 `deploy.sh`。Webhook 不接受请求体中的命令，部署脚本路径由服务器环境变量固定。

`deploy.sh` 固定拉取 `master`，收到其他部署分支参数时直接退出，再检查项目 `.venv`。如果 `.venv/bin/python` 不存在，脚本使用服务器上的 `python3` 或 `python` 创建虚拟环境；随后用 `.venv/bin/python -m pip install -r requirements.txt` 安装依赖，按文件名顺序执行 `migrations/*.sql`，最后重启 `weread.service`。

例：用户将已验收代码合并并推送到 `master`，GitHub 发送签名请求；服务器确认仓库为 `KingHWJ/WeReadBoard` 且 ref 为 `refs/heads/master` 后，在 `/opt/weread-board/WeReadBoard/.venv` 创建环境，安装 Flask 和 PyMySQL，确认阅读目标表存在，再让 systemd 重新用 `.venv/bin/python app.py` 启动服务。仅推送 `dev` 不会触发部署，错误签名也不会执行脚本。

## 正式看板登录认证

`auth.py` 注册全站请求拦截和登录路由。`/` 与所有 `/api/*` 数据接口都需要 `session["auth_user"]`；静态资源、`/login`、`/auth/login` 和首次初始化路由是唯一公开入口。页面请求未认证时重定向到登录页，API 返回 401，避免前端遮罩之外仍可直接读取数据。旧 `/api/v2/*` 路由同样由 Flask 全局拦截。

账号表 `weread_auth` 固定使用 `id=1` 保存单管理员的用户名和 Werkzeug 密码哈希。数据库无账号时，只有提交服务端 `WEREAD_AUTH_SETUP_TOKEN` 才能插入首个账号；例如提交用户名 `reader`、一次性口令正确、密码 `a-long-private-password`，数据库保存的是哈希而不是密码。插入成功后创建永久 Flask 会话，并清空当前进程中的初始化口令。后续登录从 MySQL 取哈希校验；用户名或密码错误统一返回“账号或密码不正确”。

会话签名密钥从 `WEREAD_SESSION_SECRET` 读取且必须稳定配置；缺失时服务对动态页面和 API 以 503 失败关闭。永久会话时长是固定 5 天，不因每次请求续期。Cookie 为 HttpOnly、SameSite=Lax，并默认 Secure；仅本机 HTTP 预览可以关闭 Secure。生产站点须使用 HTTPS。前端 JSON 写请求从页面 meta 标签读取 CSRF token 并放入 `X-CSRF-Token` 请求头，表单请求使用隐藏字段。

## 网站备案页脚

正式看板页脚保留数据状态，并展示可点击的 ICP 备案号，链接至工信部备案查询平台。窄屏时隐藏次要的数据快照，备案号仍可见。

例：正式域名为 `laohang.space`、备案号为 `浙ICP备202607916号-1`，首页页脚显示该备案号；点击后打开 `https://beian.miit.gov.cn/`。截图里的公安联网备案数据码不是公安备案号，不作为备案号码展示。

## 应用版本显示

根目录 `VERSION` 保存面向用户的版本号，例如输入 `v0.1`，Flask 在启动时读取并通过模板上下文注入 `app_version`。首页页脚和登录页显示“版本 v0.1”。版本号不包含分支名或提交号；发布新版本时修改 `VERSION` 后随 `master` 一起部署。

应用未内置登录尝试限流；公网部署应在可信反向代理上为 `POST /auth/login` 设置频率限制，且不要直接信任未校验的 `X-Forwarded-For`。

## 示例与真实接口的边界

概览图表使用固定样例；目标日期状态使用浏览器当前本地日期。笔记导出包含当前选中书目的划线和个人想法全集，不受内容类型筛选影响，不包含书签内容及公开点评。

书架的有声内容完结不等于用户读完，所以未用其完结状态计算阅读目标。文章收藏是入口，不假装能直接列出内部文章。缺失资料显示暂无，不补造 ISBN 等字段。

正式接口接入单独推进，必须核对实时可用接口、鉴权、分页、错误、升级提示及字段口径；本轮 Demo 的完成状态不得用于宣称这些能力已真实接入。

## 正式看板的紧凑布局

正式看板在 `static/css/styles.css` 中统一调整页面密度。顶栏高度为桌面 58 px、手机 56 px；标题区采用更短的上下间距，隐藏页面标题前的英文装饰文字。标题、说明、筛选、内容依次展示，操作按钮在桌面与标题并排，手机上自然换行。

书架按可用宽度自动排列书籍，每列约 116 px 起步；手机固定两列。真实封面维持原比例，并受所在列宽度约束。例如，书架网格可用宽度为 900 px 时显示多列紧凑排布，手机宽度为 390 px 时显示 2 列，长书名仍使用已有省略规则。

目标介绍区在宽屏上把说明与统计并排，窄屏上改为上下排列；目标卡按可用宽度自动排列，每张卡约 280 px 起步，并缩小封面预览和上下间距。例如，一个包含 6 本书、已读完 2 本的月度目标仍展示原有完成数和进度，只减少卡片占位。页面渲染、筛选、目标计算和数据流保持由现有 JavaScript 实现，CSS 不改变业务口径。

## 正式看板书架排序与分页

正式看板从 `/api/reading/shelf` 读取电子书列表。前端按当前书架状态筛选后排序，每页展示 48 本；用户切换状态或排序时回到第 1 页，点击底部页码时只替换当前书籍网格。排序框右对齐显示在页码列表上方。

排序默认按最近阅读时间倒序；还可按书名升序、书名降序或作者升序。四种方式都先将 `is_top` 置顶书籍排在前面。接口把微信读书的 `isTop` 映射为 `is_top`，前端排序只使用筛选结果的副本，避免改变其他页面共享的书架顺序。

例：筛选“全部电子书”共 101 本，选择“书名升序”并打开第 2 页。页面只显示排序后第 49 至 96 本，在网格下方显示第 1、2、3 页；切换到“最近阅读”后回到第 1 页，并按最近阅读日期倒序显示前 48 本，置顶书籍仍排在该页最前面。

## 正式看板的阅读目标持久化

正式看板使用 `static/js/app.js`、`static/js/weapi.js` 和 `reading_api.py`。本节覆盖正式页面；前文的 Demo 存储方式不适用于正式目标。

`reading_goals` 保存 `id`、`name`、`start_date`、`end_date`、来源书单名称 `sources` 和创建、修改时间。`reading_goal_books` 保存 `goal_id`、`book_id`，联合主键防止同一目标重复计书。目标 ID 沿用前端生成值，便于导入旧目标。来源名称保存为 JSON 数组，不表示持续关联书单。

目标成员只通过外键关联目标。删除目标时级联删除成员，书架不受影响；书籍移出书架时也不删除目标成员。迁移位于 `migrations/001_reading_goals.sql`，只需部署时执行，不在请求中自动建表。

页面加载时 GET 目标列表，新建时 POST，编辑及追加书籍时 PUT，删除时 DELETE。表单先校验名称、日期和书目，服务端再次校验。目标与成员在同一事务中提交，编辑时锁定目标父记录并整体替换成员，避免并发请求混入两份书目。多个浏览器同时编辑同一目标时，以最后成功保存的完整内容为准。

前端收到提交成功响应后更新内存并关闭表单。保存中阻止重复提交；目标列表未从数据库读取完成前，不打开新建或编辑窗口，避免初始读取失败状态覆盖刚保存的目标。新建重试保持原 ID。数据库错误转换为 503，回滚事务并让前端保留草稿。目标列表不使用进程缓存，刷新即读取数据库。

例：创建“秋季阅读”，日期为 `2026-09-01` 至 `2026-09-30`，输入书籍 `["A", "A", "B"]` 和来源 `["文学书单"]`。数据库生成 1 条目标、2 条成员。若 A 已读完而 B 未读完，页面显示 `1 / 2，50%`；B 暂时不在书架中时仍显示 `1 / 2，50%`，B 的资料占位显示“状态待同步”，可在编辑器移除。若用户明确移除 B，则显示 `1 / 1，100%`。

完成率和状态不写入目标表。当前已知已读状态用于计算，不要求在目标日期内读完；全部已读完优先显示“已完成”，否则按浏览器本地日期显示未开始、进行中或已到期，起止当天均属于进行中。未知状态不计为已完成，但仍计入分母。

旧数据仅在用户点击导入时发送给 `/api/reading/goals/import`。先校验整批，再在事务中逐项插入；相同 ID 已存在时保留数据库内容，批次内重复 ID 只处理第一条。例如库中已有 G1，导入 `[G1, G2, G2]` 返回 `{"imported":1}`，再次导入返回 `{"imported":0}`。任何写入失败均回滚整批；成功后保留原浏览器备份并记录导入标记。