[公告] 附件（统一收敛层 + 分月目录 + 缩略图双档 + 卡片/灯箱）与列表、正文图展示改造

一、变更文件清单

一之一、A 线 · 附件体系改造（21 个文件：3 新增 / 18 修改）

一之二、B 线 · 列表与正文图展示改造（26 个文件：2 新增 / 24 修改）

未触碰：app/Controllers/ThreadController.php、app/Controllers/PostController.php（其上传调用点 Upload::file($file) 已走收敛层，file() 内部自行决定分月目录，无需改动）；assets/js/editor.js（方案 §2 明确「无需改」）；plugins/task_center/Plugin.php（方案明确「零改动」；其 strpos($av, 'seed_avatars/') !== 0 前缀判定对 seed_avatars/YYYY-MM/x.svg 依然成立）；data/ 下任何数据。

二、改动前现状与根因

2.1 上传路径散落、无收敛层

上传文件的落盘目录、URL 拼接、缩略图命名分散在 60 余处：视图里手写 '/assets/uploads/' . $row['avatar']、控制器里各自 move_uploaded_file()、插件里再抄一份。后果有三：

1. 口径漂移：附件卡原先自带一份 7 项扩展名白名单，而 Upload::file() 是 5 项 → 同一文件「能上传但不能显示缩略图」；
2. 改一处要改 60 处：本次要改成按月分目录，若不做收敛层，就得在 60 处同时改，漏一处即产生 404；
3. 缩略图与派生文件清理困难：删除原图时无法可靠地连带清掉 thumb_ / md_（历史遗留即由此产生）。

2.2 全类型平铺在同一目录

assets/uploads/ 下单层平铺，随站点运行文件数线性增长（本机实测原图 334 个 / 12.5 MB）。目录项过多会拖慢目录遍历与备份；且不同类型（头像 / 封面 / 正文图 / 附件）混在一起，无法按类型单独做保留策略。

2.3 缩略图只有一档，列表与正文都用原图

makeThumbnail() 只产 thumb_（400×300）一档。于是：

• 列表页摘要图直接输出原图 URL（4 处渲染点：forum/index.php 置顶区与普通区、home/index_default.php、forum/category.php）；
• 正文图在详情页也用原图，一张 462 KB 的截图就是全量传输。

2.4 灯箱关闭按钮点击无反应

根因：右上角 × 的点击处理绑在容器上，而容器在图片加载完成后被重新定位/重建，× 的新节点上没有监听器；同时 × 缺少独立的 data-action 标识，事件委托选择器匹配不到。修法：灯箱整体重写，所有操作统一走 data-action 事件委托（lb-close / lb-prev / lb-next / lb-stage），并在 Esc / 遮罩 / 点击图片三处同时提供关闭路径。

2.5 正文图无分组，多图竖排占满整屏

实测正文结构：多图帖是 <div><img><img><img><img><br></div>，单图帖是裸 <img>。浏览器按默认流式排版 → 每张图独占一行，4 张图要滚 4 屏。

2.6 modern.css 存在未定义变量（静默失效）

var(--mn-bg-hover) 被引用 3 处（导航语言下拉、应用下拉、移动端「我的」菜单的 a:hover），但该变量从未定义且无 fallback → 整条 background 声明失效，三处 hover 背景无反馈。同类规则（紧邻的导航项）统一使用 --mn-bg-nav-hover（定义在 :root 兜底块），本意明确。

三、逐项改动细则

3.1 统一收敛层（Upload + TemplateCompiler）

⚠️ path() 与 absPath() 的分工是硬约定：thumbPath() 是「存在才返回」，不能用来算「待写入」的目标路径（否则目标缺失时恒为 null，会把成功误判为失败）。cli/backfill_md_thumbs.php 即按 thumbPath() 的同一口径自己拼相对路径、再用 absPath() 取绝对路径。

3.2 全类型按月分目录

月份判定优先级：记录里的显式时间字段 → 文件 mtime → 当前月。

3.3 缩略图双档

Upload::THUMB_SIZES = ['thumb_' => [400,300], 'md_' => [800,600]]；makeThumbnail() 在原图 ≤ 目标尺寸时返回 'skip'（不做放大，故小图天然无需缩略图）。

• thumb_ —— 列表摘要图 / 附件卡；
• md_ —— 正文图（Content::sanitizeHtml() 在渲染期把 src 换成 md_，同时把原图 URL 写入 data-fullurl 供灯箱取高清）。

PNG 出口无损优化（writePng()）：旧实现无条件 imagesavealpha(true) 写 32 位 RGBA，而站内图像素全不透明，alpha 平面纯浪费。新实现逐像素扫透明（762×600 实测约 67 ms）——含透明则退回旧行为（绝不丢透明），全不透明才降为 24 位 RGB，并用 q9 分别以 PNG_FILTER_NONE / PNG_ALL_FILTERS 编到内存、只落盘较小者。像素数据与旧实现完全一致，只改容器编码。实测真实源图合计 1,914,285 → 1,587,145 B（省 17.1%，逐像素零差异）。

⚠️ 不能用「读源 PNG 的 IHDR 色彩类型」代替扫描：实测 14 张源图里 11 张是色彩类型 6（带 alpha 通道）但像素全不透明，按 IHDR 判断会漏掉绝大多数优化机会。 ⚠️ 此优化只作用于 GD 分支；装了 Imagick 的环境走 makeThumbnailImagick()，不受益。

3.4 非图片附件下载计数

• 表结构：attachments.download_count INTEGER NOT NULL DEFAULT 0（CREATE TABLE 与 ensureColumnPatches 清单同改）；
• 语义：仅「非图片附件的实际下载」+1；图片原图查看与 ?s=thumb 缩略图不计；
• 自增：单条原子 UPDATE attachments SET download_count = download_count + 1 WHERE id = ?，不做 read-modify-write；失败只记 error_log，不影响下载本身。

3.5 附件卡公共组件

原先 2 处（帖子详情 / 博客详情）各写一份，本次收敛为 app/Views/_components/attachment_card.php：

• 图片卡：?s=thumb 缩略图 + 点击进灯箱；扩展名白名单与 Upload::file() 同源（消除 7 项 vs 5 项的口径漂移）；
• 文件卡：图标 + 文件名 + 体积（Upload::formatSize()）+ 下载次数；
• 移动端断点 @media (max-width:768px) 下改为单列；
• 主题范围：只依赖 modern.css 的 mn-* 工具类与 --mn-* 变量，模板主题（assets/<Name>/）下自然降级为无样式块，不报错。

3.6 灯箱重写

assets/js/lightbox.js（新增）+ app/Views/_components/image_lightbox.php（新增容器），仅在详情页加载：

• 全页连读：按 DOM 顺序收集本页所有 [data-fullurl]（正文图由净化层在渲染期写入），故 htmx 翻页 / 新渲染的回复图自动进入阅读序列，页面无需声明图片列表；无 data-fullurl 时回退取 src（兼容历史的 .post-text-content img）；
• 多图切换：左右箭头 / 键盘 ←→ / 移动端左右滑动；单图时箭头自动隐藏；
• 预载相邻图；计数器显示 i / n；
• PC 滚轮缩放、双指捏合缩放、拖拽 / 单指平移；
• 关闭：Esc / 遮罩 / × / 点击图片 —— 四路齐备（修掉原先「× 无反应」）；
• 兼容导出 window.viewImage(el) / window.closeLightbox(e)，既有内联 onclick 无需改。

3.7 列表摘要图改读缩略图

TemplateCompiler::uploadThumb() 在 4 处摘要渲染点替换原图 URL：forum/index.php（置顶区 + 普通区）、home/index_default.php、forum/category.php。缩略图不存在时自动回退原图 → 零 404。

3.8 摘要图网格规范化（决策：每行 3 个 / 单图与多图同尺寸 / 超出不显示）

• 每行 3 个（grid-template-columns: repeat(3, minmax(0, 1fr))）；
• 单图与多图同尺寸（统一 aspect-ratio + object-fit: cover，不再「单图占一格半」）；
• 最多显示 3 张，超出不显示；
• min-width: 0 防超宽图撑破网格列。

3.9 正文图渲染期分组（P8-D）

在 Content::sanitizeHtml() 的白名单循环之后插入 groupPostImages($dom, $xpath)（容器与 class 由我们自己生成，不应再被白名单过滤）：

1. 先按 nearestBlockAncestor()（只认 div / p）把图归拢到块，再按块批处理；
2. 块内子节点只有「带 data-fullurl 的 img」/ br / 空白 → 该块加 post-img-grid，每图包 post-img-cell；count($imgs) <= 1 再加 --single；
3. 图片混在文字里，或图在顶层裸挂 → 就地新建容器包住单图。

四条实现红线（均已写入回归用例）：

样式（modern.css）：

.post-img-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; margin: 12px 0; }
.post-img-grid--single { grid-template-columns: 1fr; max-width: 480px; }   /* 决策 D-a：单图整行限宽 480px */
.post-img-grid > br { display: none; }
.post-img-cell { display: block; min-width: 0; overflow: hidden; border-radius: 8px; cursor: zoom-in; background: var(--mn-bg-row-hover); }
.post-img-grid:not(.post-img-grid--single) .post-img-cell { aspect-ratio: 4 / 3; }
.post-img-grid .post-img-cell img { display: block; width: 100%; height: 100%; max-height: none; object-fit: cover; }
.post-img-grid--single .post-img-cell img { width: auto; height: auto; max-width: 100%; max-height: 500px; object-fit: contain; }

点击看大图零 JS 改动：data-fullurl + .post-text-content img 兜底选择器都在，灯箱自动接管。

3.10 正文图 md_ 回填（cli/backfill_md_thumbs.php）

• 扫全部 32 个桶的 topic + reply 的 extern_path 正文；必须先 Content::decode() 再抽 URL（正文存在 base64 态）；
• 正则 #/assets/uploads/([^"\'\s>)\\\\]+)#i + Upload::isImageName() 过滤 → 去重；
• 幂等、只增不删（除下述回退）；--dry-run 只演练、--force 重编已存在的 md_；
• 回退策略：生成后比对 filesize()，若 md_ ≥ 原图（GD 真彩重编码 vs 外部工具优化过的原图，像素更少字节反而更多）就 unlink() 它，让渲染层回退原图出口。用 PHP unlink() 而非 shell rm，避开沙箱「安全删除守卫」的拦截。

本机实测：候选 14 个 → 保留 9 / 回退 5 / 失败 0，出口 3.6 MB → 1.2 MB（省 67%）；二次运行文件清单逐字节一致（回退图无状态可记，会「重新生成再删」，但净结果不变）。

3.11 顺带修正

四、验证方式与结果

4.1 自动化回归（全部通过）

4.2 静态门禁（本包 47 个文件）

1. 语法：44 个 PHP 全部 php -l 通过（No syntax errors detected）；
2. 编码：0 个带 BOM、0 个含 CRLF、0 个非 UTF-8 —— 全部 UTF-8 无 BOM + LF，符合项目约定；
3. 调试残留：var_dump / print_r / [DBG] / TODO / FIXME / console.log / debugger 扫描 0 命中。

4.3 数据与文件完整性

1. 上传目录：原图 334 个（12.5 MB）｜ thumb_ 22 个 ｜ md_ 9 个（1.0 MB）—— md_ 全部为有效图片、0 空壳、0 非图片，且全部小于对应原图；
2. 只增不删证明：md_ 回填前后对 assets/uploads 做全量清单对比 → 删除的恰好是 5 个被回退的 md_，无任何非 md_ 删除，thumb_ 22 → 22、原图 334 → 334 未动；
3. 零 404：T8 走的是「md_ 已回退 → src 保持原图」分支并通过，回退路径已被 HTTP 端到端直接验证；另加「src 指向的文件真实存在」与「体积 > 1KB（防空壳）」两条保险断言。

4.4 体积收益

五、部署与回滚

5.1 ⚠️ 先明确：本次要上传什么

服务器是 IIS、没有命令行 → 缩略图必须在本地生成好、跟着一起传上去，不能在服务器上跑 CLI。

⚠️ 传 data/ 的唯一真实风险：会用「下载那一刻」的库覆盖服务器 —— 下载之后服务器上产生的 新用户 / 新帖 / 新回复会全部丢失。本次升级不需要传库，所以别传，风险为零。

旧的上传文件（平铺在 assets/uploads/ 根目录的）不需要动：Upload::REL_PATTERN 里年月段是可选的 （#^(?:(?:seed_avatars|covers)/)?(?:[0-9]{4}-[0-9]{2}/)?[A-Za-z0-9_.\-]+$#）， 所以 ab12cd.png / seed_avatars/1.svg / covers/tpl_x.svg 这些旧路径依然能正常解析； 净化层的 img 分支也只在 md_ 确实存在时才改写 src，否则保持原图 → 零 404。 即：按月迁移是整理优化，不是升级必需项。

5.2 部署步骤（5 步）

1. 备份：把服务器的 data/ 与 assets/uploads/ 各整目录复制一份（出了任何问题都能整回去）。
2. 覆盖代码：把本包内的 46 个代码文件 + version.php 按相同相对路径覆盖到站点根（清单见 5.3）。 ⚠️ assets/js/lightbox.js 是新增文件，必须上传（漏了灯箱就不工作）。
3. 上传 9 个 md_ 缩略图：把本机 assets/uploads/2026-09/md_*.{png,jpg} 传到服务器同一目录 assets/uploads/2026-09/。这 9 个是新增文件，直接丢进去即可，不需要删除或覆盖任何东西。
4. 清缓存（⚠️ 不要省这一步）：登录后台 → 维护 → 清理缓存（/admin/maintenance 的「清理缓存」按钮）。 原因：游客的列表页静态缓存是永久缓存、不按 TTL 过期（只在发帖 / 回帖 / 改设置 / 改主题时主动失效）， 不清的话老访客会继续看到升级前的列表页 HTML（图片仍是原图、没有三列网格），而且不会自己恢复。 服务器没有命令行也没关系 —— 这个按钮是网页操作。
5. 验证：帖子详情页 → 图片两列排布、点击出灯箱、右上角 × 能关、多图可用 ←/→ 切换； /forum 列表页 → 摘要图是 3 列网格。

5.3 要覆盖的代码文件清单（46 个）

app/Controllers/{Api,Attachment,Auth,Blog,Profile}Controller.php
app/Core/TemplateCompiler.php
app/Helpers/{Content,CoverTemplate,Settings,Upload}.php
app/Models/{Thread,User}.php
app/SplitDB/Schema.php
app/Views/_components/{attachment_card,image_lightbox,right_sidebar}.php
app/Views/{blog/{detail,edit,index},forum/{category,index},home/index_default,post/edit,profile/index,search/index,tags/show,thread/{edit,show}}.php
assets/css/modern.css
assets/js/{lightbox.js,thread.js}          ← lightbox.js 为新增文件（必须上传）
cli/{backfill_md_thumbs,migrate_uploads_by_month,seed_content}.php
lang/{zh,en,zh_tw}.php
plugins/content_review/Plugin.php
plugins/dice/hook/right_sidebar_after.php
plugins/dice/views/index.php
plugins/floor_reply/views/list.php
plugins/points_mall/FrontController.php
plugins/quiz_duel/views/index.php
plugins/red_packet/views/detail.php
plugins/user_level/views/like_list.php
plugins/user_profile/views/front.php
version.php

无需：数据库迁移脚本、配置项修改、访问升级 URL、清理 sw.js（CACHE_VERSION 随版本号自动变化）。

自动发生：首次请求时 ensureColumnPatches 自动为 attachments 补 download_count 列（并发重复 ALTER 已捕获忽略）。

5.4 关于 md_ 缩略图（服务器无命令行时的长期做法）

• 本次的 9 个 md_ 已在本地生成好，直接上传即可（见 5.2 第 3 步）。它们是历史正文图的缩略图 —— 那批图是在「正文图缩略图」功能上线之前上传的，所以需要一次性回填。
• ✅ 以后新发的正文图不需要任何手工操作：编辑器插图走 ApiController::upload()， 它调 Upload::file($_FILES['file'], null, ['thumb' => 'md_']) → 上传时自动生成 md_。 （附件上传走 ThreadController 默认档位 thumb_；头像走 ['thumb' => ''] 不生成 —— 均为有意设计。）
• 万一以后确实要给历史图补 md_（例如换了图片存储）：在本地把 data/ + assets/uploads/ 下载下来， 跑 php cli/backfill_md_thumbs.php（幂等、只增不删），再把新出现的 md_* 传上去即可。 该脚本生成后会比对 filesize()，md_ 比原图大就自动删掉、让页面回退原图，不会浪费流量。
• php cli/migrate_uploads_by_month.php（旧文件按月归档）本次不需要跑 —— 服务器上的路径已经是 2026-09/xxx 形式（数据库里 13 条附件记录全部已是新格式）。

5.5 两个 CLI 工具（⚠️ 只能在本地跑，服务器无命令行）

两个工具不执行也能正常升级（渲染层对缺失缩略图自动回退原图，零 404）。 它们是给「在本地维护数据」用的，不要在服务器上找命令行：

# 1) 正文图 md_ 回填（幂等、只增不删）
php cli/backfill_md_thumbs.php --dry-run     # 先演练，看清单
php cli/backfill_md_thumbs.php               # 执行

# 2) 旧上传文件按月迁移（会写盘、会改写数据库中的路径 → 先备份！）
php cli/migrate_uploads_by_month.php --dry-run   # 必须
php cli/migrate_uploads_by_month.php             # 确认无误后执行

⚠️ migrate_uploads_by_month.php 会改写正文与 settings 里的路径，执行前请整库 + assets/uploads/ 一起备份（脚本自带备份步骤与日志）。 ⚠️ 详情页 /thread/{id} 不走 PageCache（PageCache 仅列表页 + 仅游客），故回填后无需清页面缓存； 列表页若需立即生效，走后台 维护 → 清理缓存（服务器无命令行，不要指望手工删文件）。