3.4 KiB
阅间 Demo 设计与数据流
页面分工
统计并入阅读概览；导航保留阅读概览、我的书架、阅读目标、笔记与划线、发现好书。概览展示阅读统计和目标摘要，目标页管理多份具体阅读清单。
完整功能、业务规则、接口落点与状态见 功能目标清单。该清单先于本轮实现建立，后续代码开发继续追加和更新。
此版本属于 2.0 设计探索。正式版本需要接入真实接口、完成验收并合并到正式 Web 项目的 master，随后再创建 v2.0 标签。
数据流
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 关闭。
示例与真实接口的边界
概览图表使用固定样例；目标日期状态使用浏览器当前本地日期。笔记导出包含当前选中书目的划线和个人想法全集，不受内容类型筛选影响，不包含书签内容及公开点评。
书架的有声内容完结不等于用户读完，所以未用其完结状态计算阅读目标。文章收藏是入口，不假装能直接列出内部文章。缺失资料显示暂无，不补造 ISBN 等字段。
正式接口接入单独推进，必须核对实时可用接口、鉴权、分页、错误、升级提示及字段口径；本轮 Demo 的完成状态不得用于宣称这些能力已真实接入。