WeReadBoard/docs/technical-guide.md

阅间设计 Demo 使用说明

范围与启动

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

该 Demo 定位为 2.0 设计探索。当前提交用于保存探索成果，不代表 2.0 正式发布，也不创建 v2.0 标签。

在项目根目录执行：

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

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

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

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

使用入口

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

验证

语法检查：

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

交互验收记录见 功能目标清单。真实 API、鉴权、分页和服务器持久化尚未验证。

与 1.0 的关系

1.0 继续由根目录的 app.py、fetch_data.py、templates/ 和 static/ 提供，运行在 8080 端口。2.0 探索 Demo 位于 web-demo/，两者可以独立预览。