[shiningsprk-arch]

对应 fork 仓库的审查 PR：shiningsprk-arch/mybooks#22。Sourcery / CodeQL 的意见已在该 PR 里逐条消化，逐条回复见该 PR 的评论。

背景

动态封面目前只有随机渐变 / 纯色底 + 白色书名。希望让管理员上传自己的图片作为底图，书名仍沿用现有排版逻辑绘制。

实现

1. 只改 generate_cover() 一处，8 条生成路径自动全部生效

ImageGenerator.generate_cover() 原本已有一个 bk_img_path 背景图参数，但从它被引入的那次提交起，全仓库没有任何调用方传入过。本次把它接到背景图库，于是 static_files.py、book.py（4 处）、scan_service.py、batch_generate_cover.py 的调用点一行都不用改。

2. 背景图库 webserver/base/cover_background.py

• 目录 /data/books/resources/cover_backgrounds/，与现成的 resources/author_avatar/ 同族，已在 /data 卷内，无需改 Dockerfile。刻意不放 upload_path——那里会被 TrashManager.clear_trashs() 清空。
• 上传即：按 EXIF Orientation 转正 → 居中裁成 1200×1600（3:4）→ JPEG 入库；文件名取内容 md5，重复上传天然去重。
• 逐张勾选：每张图可勾选是否参与生成；选择状态存在同目录的 selection.json，线程锁内原子写入。没有该文件时默认全选。上传自动选中，删除自动移出，已被删掉的旧名字读取时自动忽略。
• 内置「默认彩色封面」：候选池固定多一个内置选项（默认勾选），和上传图一起参与按书名分配；命中它时走原来的渐变/纯色生成。这样不删光图库也能让部分书保留原样式。
• 选图用 md5(书名) % 候选数，同一书名永远命中同一张。因此不需要为每本书记录「用了哪张背景」，也不新增 Calibre 自定义列。
• 文件列表 1 秒短缓存，避免逐本书生成封面时反复 listdir。
• 校验：≤10MB、≤5000 万像素、仅 JPEG/PNG/WEBP、库上限 50 张。

3. 两处底图相关的行为修正

• 尺寸：原 bk_img_path 分支的输出尺寸等于背景图原始尺寸，用户传横图就会生成横版封面。现在统一 ImageOps.fit 到请求尺寸。
• 可读性：仅在照片底图上给书名加描边，stroke = max(1, 字号 ÷ 24) 随字号等比（1200×1600 上 5px、240×320 缩略图上 1px），行距同步加 stroke × 2 防止多行文字贴挤。渐变 / 纯色底完全不描边——stroke_width = 0 时绘制调用与行距计算和改动前逐字符一致。

4. 不改变任何「是否覆盖封面」的既有语义

逐条核对了 8 条生成路径：

路径	触发条件
无 cover.jpg 实时生成 / 重置元数据 / 网页上传 / 分片上传 / 扫描导入	仅当书籍无封面
改书名重生成 / 管理员批量更新	仅当 #dynamic_cover = 1
手动点「生成封面」	无条件（唯一的手动覆盖入口）

已有真实封面（#dynamic_cover = 0）的书不会被任何自动路径换成背景图封面。上传 / 删除背景图也不触发任何重生成，要生效需管理员主动点「更新所有动态封面」。

5. 管理接口与设置页

• 6 个路由注册在 main.py 的 static_files.routes()（含 catch-all r"/(.*)"）之前。
• 图库并入「启用动态封面」下方：勾选该开关后才展开，与图章上传同一套路；不再单独占一张「封面背景图」卡片。
• 移除原 USE_COVER_BACKGROUND 总开关（前端字段与后端默认值 / 持久化白名单一并删除）：是否使用背景图完全由勾选集合决定，清空候选即回退渐变 / 纯色。
• 上传、缩略图网格、删除、逐张勾选、按书名试生成；内置默认项用 library=0 生成一张原彩色封面作为预览。
• 图库增删与勾选即时生效（与图章一致），只有「启用动态封面」跟随页面「保存」。

测试

tests/test_cover_background.py 覆盖：空库回退、3:4 居中裁剪、同内容去重、选图稳定性、仅勾选项参与、内置默认项参与分配、取消全部候选回退、勾选持久化 / 缓存失效、上传自动选中、删除移出选择、非法 / 损坏选择状态、selection.json 不被列表 / 读取接口暴露、状态写入失败时上传仍成功、非图片 / 超大字节 / 超像素 / 不支持格式拒绝、库满与并发不超限、透明 PNG 垫白、EXIF 转正、带路径成分的名字整条拒绝（../、./、sub/、..\）、输出尺寸不受原图影响、白底描边可见性、显式 bk_img_path 优先于图库、use_library=False 跳过图库、_payload 字段、两个二进制接口的权限必须走 is_admin()。

• WSL ~/mbvenv（calibre 7.6）：test_cover_background.py + test_thumbnail.py + test_locale_i18n_keys.py + test_perf_settings.py + test_scan_p0.py 共 134 passed；唯一 warning 来自 social_sqlalchemy 的既有 identity-map 提示，与本次改动无关
• 基线既有失败（与本改动无关）：test_setting_saver.py::test_no_duplicate_admin_keys（MYNEXUS 键重复）、test_sidebar_items_migration.py::TestSidebarItemsServedToInfo（主克隆 develop 同样失败）
• flake8 对改动文件零新增违规
• eslint 0 error；两个改动 Vue 模板 vue-template-compiler 编译通过；npm run build-spa 通过。构建重写的 mdi 子集已还原，不夹带无关的 mdi-stop-circle-outline 缺口

审查过程中发现并修掉的问题

1. 阻断：两个二进制接口用 self.admin_user 判权限，而该属性只在 get_current_user() 里赋值，默认 REQUIRE_LOGIN=False 时 prepare() 不会触发解析 → 管理员也恒 403。改用 self.is_admin() 并加测试防回退。
2. 路径穿越：read/delete 原本用原始请求名拼路径，../x/bg_<16hex>.jpg 可命中库外同名文件。现在带路径成分的输入整条拒绝。
3. MAX_BACKGROUNDS 是模块常量却被当类属性读取，列表与上传接口全部 500。
4. mdi-image-refresh 不在已提交的图标子集内，按钮图标会渲染成空白。改用子集内已有的 mdi-image-sync-outline。
5. 并发上传可突破库上限（计数检查在锁外且走 1 秒缓存）→ 计数复查与写入并入同一把锁。
6. 上传时同步解码阻塞 Tornado IOLoop → 下放线程池。
7. Cache-Control 从 public 改 private（admin-only 资源）；背景图解码加 Image.draft() 预降采样。

二次 review 修复

• 勾选回退：Vuetify 2 的 inputValue watcher 只在 prop 变化时回写。现在勾选先乐观更新本地，请求期间禁用其它勾选；失败或网络异常时把本地值改回旧值，勾选框才会跟着回退。
• 缓存竞态：selection() 增加代次校验。封面生成在 executor 线程，写操作的 invalidate_cache() 可能与读缓存交错；旧读不再把状态回写缓存，避免最长 1 秒的脏读。
• 状态写入失败：包成 CoverBackgroundError，避免 @js 把裸 OSError 的整段 traceback 回给前端；上传 / 删除路径只记日志，图片操作不因勾选状态写失败而整体失败。
• 文案：明确上传图按书名稳定分配；内置「默认彩色封面」沿用原来的渐变 / 纯色生成。

已知取舍

• 图库增删或改变勾选后，% len(pool) 会让多数书名换图。这是「全局候选池」的固有特征——重生成时重新分配即可，不引入一致性哈希的复杂度。
• 内置默认项占候选池 1 份：例如勾选 3 张上传图 + 默认项时，约 1/4 的书沿用原彩色封面；不想要它可直接取消勾选。
• 内置默认项命中时沿用原有随机渐变（每次生成的颜色 / 角度可能不同）。这是改动前动态封面本来的行为；本次不为了让默认项稳定而改动渐变算法。
• 选图种子是书名而非 book_id：新书入库生成封面时 book_id 还不存在，书名是唯一无状态可用的种子。代价是改书名会换背景。
• 无封面书每次请求实时生成，加背景后单次多约 10–20ms 解码。沿用现有的无缓存行为（渐变生成同样每次都算，且原本就有 ENABLE_GRADIENT 自动降级机制）。
• 管理接口沿用全站约定，未单独加 CSRF token（项目 xsrf_cookies 默认关闭，所有管理接口一致只依赖会话 cookie）。如需要可作为全站改造单独进行。

未包含

BookCover.post() 至今没有书籍归属校验（任何登录用户可改任意书籍的封面），属既有问题，本 PR 未触碰，如需要可单独提。