Reading Library（阅读记录分析 + 图书馆书架）
Overview
把一份 Excel 阅读记录（每年一个 sheet，列名可能逐年略有差异）清洗、去重、分类，产出两份单文件 HTML：
阅读分析报告.html—— 图表化阅读统计（年度/月度节奏、热力图、主题构成、作者 TOP、来源地演化、口味转向、深度洞察）我的图书馆.html—— 豆瓣实拍封面的书架陈列页（封面 base64 内嵌、离线可用；豆瓣无条目的书自动降级为手绘封面）
整条流水线只用 Python 标准库（无第三方依赖），豆瓣封面可增量缓存复用。
何时使用
- 用户要求基于 Excel 阅读记录做「数据分析 / 可视化」
- 用户想把书单「落地」成书架、图书馆、封面墙之类的展示页
- 用户已有一份阅读记录表，想补充新记录后刷新报告与书架
快速开始
# 一次性全量重建（解析 → 分类 → 抓豆瓣封面 → 生成两份 HTML → 数据对账 → 无头验证）
python scripts/rebuild.py "E:/书籍记录.xlsx"
# 指定输出目录（默认输出到源表同目录）
python scripts/rebuild.py "E:/书籍记录.xlsx" "C:/my-reading"
产物（在输出目录）：阅读分析报告.html、我的图书馆.html，以及中间文件 books.json、library_data.json、dashboard_data.json、douban_covers.json、covers_s/、covers_inline.json、qa.txt、verify 日志。
增量更新流程（用户补充新记录后的核心用法）
用户往源表追加新行（新书、或某本书的重读记录）后，直接重跑 rebuild.py 即可，脚本会自动复用缓存、只补抓新增书目：
build_data.py—— 重新解析全部 sheet，书名去重合并、保留重读的每一次日期build_library_data.py—— 生成library_data.json（每本书 19 个短键 + meta）- 豆瓣封面三段抓取（
fetch_douban.py→retry_missing.py→fill_search.py）—— 只处理douban_covers.json里还没有的新书名 download_small.py+make_inline.py—— 下载小图（270×391）并 base64 内嵌aggregate.py+build_html.py—— 生成分析数据与报告build_library.py—— 生成内嵌封面的图书馆单文件verify_library_data.py—— 源表逐行对账 + 输出完整性校验- 无头浏览器实渲染截图验证（Windows 下自动用 Edge/Chrome）
常用选项：
python scripts/rebuild.py "E:/书籍记录.xlsx" --skip-covers # 只刷数据与图表，不动封面（快）
python scripts/rebuild.py "E:/书籍记录.xlsx" --no-fetch # 不抓新封面，仅用已有缓存下载
python scripts/rebuild.py "E:/书籍记录.xlsx" --no-verify # 跳过无头浏览器验证
数据格式约定
源表结构（三种格式，脚本会自动识别）、日期解析规则、字段映射、分类规则（作者/地区/主题）详见 references/数据格式.md。
关键约定：
- 每个 sheet 名 = 年份（如
2015、2024） - 支持「简表」（书名/作者/阅毕时间/一句话短评）与「富表」（含字数/时长/出版社/评分/起止日期等）两种列结构，脚本按表头动态映射
- 日期兼容
15.7.、20.01.04、Excel 序列号、2015-07-01等多种写法 - 按书名去重；同一本书跨年/同年重读会合并为一本，多次阅读日期保留在
rt字段
踩坑提示（务必先读）
豆瓣封面链路与单文件 HTML 交付有几个反复踩过的坑（防盗链 418、营销后缀匹配、data-p 真值、DOM 桩测试不可靠等），详见 references/常见问题.md。核心三条：
- 豆瓣 CDN 对无 Referer 请求返回 418，所以封面必须下载到本地再 base64 内嵌，不能只放远程 URL。
- 源表书名常带营销后缀（如
素食者【2024诺贝尔文学奖得主】），比对豆瓣标题时必须用清理后的查询变体作基准。 - 交付给用户在预览面板/附件里看的单文件 HTML，可见资源不要放在外部相对路径，要么同目录验证过，要么 base64 内嵌。
补充数据后必须做的事（叙事文案更新）
两份 HTML 里的图表数据全部动态生成，会随新数据自动刷新。但报告 template.html 里的「叙事洞察段」是针对初始数据写死的示例结论（如 kicker 年份、insights 里的"双主线/口味转向/日本比重"、两段时期 的分界年、数据说明 里的漏记备注），这些不会自动更新，可能在新数据下过时或失真。
重跑后应：打开生成的 阅读分析报告.html，对照 qa.txt 与 dashboard_data.json，用最新数据重写这些叙事文案（定位关键词：.kicker、insights、nPhase、nRegionYear、nInsight、数据说明）。标题年份范围与页脚已自动跟随数据，无需手改。
Resources
scripts/
整条流水线的可执行脚本，rebuild.py 是唯一入口，其余脚本也可单独运行（通过 RL_XLSX / RL_OUT 环境变量指定源表与输出目录）：
rebuild.py—— 一键编排入口xlsx_util.py—— 纯标准库 xlsx 解析（zipfile + XML）classify.py—— 作者/地区/主题分类规则build_data.py/build_library_data.py/aggregate.py—— 数据清洗与聚合build_html.py/build_library.py—— 模板注入生成两份 HTMLfetch_douban.py/retry_missing.py/fill_search.py—— 豆瓣封面三段抓取download_small.py/make_inline.py—— 小图下载与 base64 内嵌verify_library_data.py—— 数据对账校验
assets/
template.html—— 阅读分析报告模板（含__DATA__占位）library_template.html—— 图书馆书架模板（含__DATA__/__COVERS__占位，封面生成 JS 已内联）
references/
数据格式.md—— 源表结构、日期解析、字段映射、分类规则常见问题.md—— 历次踩坑记录与规避方法
