[开发]FlintHub 附件体系改造方案 v3（最终稿）· 2026-09-19

一、施工范围（你的 7 条要求 → 落地口径）

二、地基一：统一收敛层（60 处 → 1 套 API）

2.1 统一 API（app/Helpers/Upload.php）

/** 相对路径 → 可访问 URL
 *  '2026-09/ab12….png'          → '/assets/uploads/2026-09/ab12….png'
 *  'seed_avatars/2026-09/1.svg' → '/assets/uploads/seed_avatars/2026-09/1.svg'
 *  'covers/2026-09/x.svg'       → '/assets/uploads/covers/2026-09/x.svg'
 *  'ab12….png'                  → '/assets/uploads/ab12….png'   ← 兼容旧值（迁移前/漏网数据）
 *  'http(s)://…'                → 原样返回（外链不动）
 *  ''                           → ''                             ← 便于视图直接输出 */
public static function url(string $rel): string

/** 相对路径 → 绝对文件系统路径
 *  禁止 '..'；白名单正则（可选命名空间 + 可选年月目录 + 安全文件名）+ realpath 前缀校验；
 *  非法或文件不存在 → null。所有 unlink / readfile / file_exists / is_file 一律走它。 */
public static function path(string $rel): ?string

/** 缩略图 URL：存在缩略图文件则返回，否则回退 url()（零 404）
 *  $prefix: 'thumb_' = 400×300（附件卡片）、'md_' = 800×600（正文图） */
public static function thumbUrl(string $rel, string $prefix = 'thumb_'): string

/** 字节数友好格式化：1536 → '1.5 KB'、2516582 → '2.4 MB' */
public static function formatSize(int $bytes): string

/** 生成相对路径（内部）：'2026-09/.' */
private static function makeRelPath(string $ext): string

2.2 视图入口（app/Core/TemplateCompiler.php）

public function uploadUrl(string $rel): string                      // → Upload::url($rel)
public function uploadThumb(string $rel, string $p = 'thumb_'): string

2.3 改造范式（前后对比）

2.4 视图层 31 处清单

2.5 PHP 层 26 处清单

三、地基二：全类型按月分目录

3.1 目录结构

assets/uploads/
├── 2026-09/
│   ├── ab12cd34….png          附件 / 编辑器正文图 / 用户头像 / 博客封面
│   ├── thumb_ab12cd34….png    缩略图 400×300（附件卡片）
│   └── md_ab12cd34….png       中图   800×600（正文内嵌图）
├── covers/
│   └── 2026-09/
│       └── tpl_a1b2c3.svg     模板生成封面（CoverTemplate）
└── seed_avatars/
    └── 2026-09/
        └── 1.svg              默认种子头像（按用户注册月份）

3.2 各类型处理表

3.3 缩略图档位

两档各自独立判定「原图 ≤ 目标尺寸则 skip」→ 小图不产生冗余文件，thumbUrl() 自动回退原图。

3.4 seed_avatars 分月设计

你的要求是「seed 头像也应该进 YYYY-MM/，因为默认注册的就是 seed 头像」。确认它的生成逻辑后，落地口径如下：

四、旧数据一次性彻底迁移

4.1 脚本：cli/migrate_uploads_by_month.php

用法：
  php cli/migrate_uploads_by_month.php --dry-run      # 只出报告，零改动（默认）
  php cli/migrate_uploads_by_month.php --yes          # 真正执行
  php cli/migrate_uploads_by_month.php --only=files   # 只移文件不改数据（分阶段用）

迁移范围（7 类）：
  ① assets/uploads/*.ext              → assets/uploads/YYYY-MM/
     （thumb_ / md_ 前缀文件跟随其原图所在月份）
  ② assets/uploads/covers/*.svg       → covers/YYYY-MM/
  ③ assets/uploads/seed_avatars/*.svg → seed_avatars/YYYY-MM/（按用户 created_at）
  ④ attachments.filename              纯文件名 → 'YYYY-MM/文件名'
  ⑤ users.avatar                      同上；seed 头像 → 'seed_avatars/YYYY-MM/{id}.svg'
  ⑥ blogs.cover_image                 同上；模板封面 → 'covers/YYYY-MM/x.svg'
  ⑦ 正文 / 内容中的 URL（6 个位置）：
       topic_index.excerpt_images        （逗号分隔完整 URL）
       extern/ 下 topic 正文 txt          （按 topic.extern_path 定位）
       extern/ 下 reply 正文 txt          （按 reply.extern_path 定位）
       blogs.content
       blog_comments.content
       settings 表所有值（custom_css 等可能引用图片）
  输出日志 data/runtime/migrate_uploads_<时间戳>.log（逐条 src → dst）

月份判定优先级

1. 有库记录 → 用记录时间（attachments.created_at / users.created_at / blogs.created_at）
2. 无记录（编辑器图、孤儿文件） → 文件 mtime
3. thumb_ / md_ 前缀 → 跟随原图月份（保证同组文件同目录）

4.2 安全设计（缺一不可）

• 默认 dry-run，必须显式 --yes 才动文件
• 幂等：路径已含 YYYY-MM/ 的跳过，重复执行结果一致
• 精确替换：正文 URL 按「迁移清单中的文件名」逐个 preg_quote 匹配，不用宽泛正则（防 ab12.png 误伤 ab12.png.bak）
• 先备份：脚本启动即检查当日备份是否存在，无则拒绝执行并打印备份命令
• 失败即停：单个文件移动失败（跨盘 / 占用）立即中止，打印已完成条数便于人工回滚
• 只移不删：任何情况下不删除文件

4.3 操作步骤（等你把生产数据覆盖到本地后）

1. 你把服务器的 assets/uploads/ 与 data/ 覆盖到本地。注意 main_index.sqlite 是 WAL → 必须连 -wal / -shm 一起拷，否则读不到表。
2. 停站（或确认无人访问）。迁移期间不接受写入。
3. 全量备份到 .workbuddy-ai/backup/20260919_附件迁移/：assets/uploads/ + data/meta/ + data/bucket/ + data/extern/。
4. 我先在备份副本上完整演练一遍（dry-run → 实际执行 → 抽样验证），确认无误。
5. 对正式数据跑 --dry-run，把报告给你确认（重点看「无法判定月份的文件」数量与抽样）。
6. 你确认后执行 --yes，完成后输出对账（文件数 / 目录数 / DB 改动行数）。
7. 回归验证：抽 10 个附件下载、10 张正文图、5 个头像、5 个 seed 头像、5 个封面；跑孤儿清理确认不误删。

4.4 「迁移后无新旧并存」的口径

五、正文图缩略图（渲染期）

落点：app/Helpers/Content.php:121-126 的 if ($tag === 'img') 分支（净化循环内）。

if ($tag === 'img') {
    $node->removeAttribute('srcset');
    $node->removeAttribute('sizes');
    $node->setAttribute('loading', 'lazy');
    $node->setAttribute('decoding', 'async');

    // 站内上传图 → 换中图 + 记录原图供灯箱使用
    $src = $node->getAttribute('src');
    if (preg_match('#^/assets/uploads/(.+)$#', $src, $m)) {
        $rel = $m[1];
        $md  = Upload::thumbUrl($rel, 'md_');       // 无 md_ 则回退原图
        if ($md !== Upload::url($rel)) {            // 确认确实换了图才写 data-fullurl
            $node->setAttribute('data-fullurl', $src);
            $node->setAttribute('src', $md);
        }
    }
}

正文图不包 <a>：thread.js 已有 .post-text-content img 全局点击委托；且 data-action 不在净化白名单里，加了也会被删。

六、非图片附件下载次数

6.1 表结构（必须走补丁清单）

ALTER TABLE attachments ADD COLUMN download_count INTEGER NOT NULL DEFAULT 0

6.2 计数语义

UPDATE attachments SET download_count = download_count + 1 WHERE id = :id   -- 原子自增，不做 read-modify-write

6.3 i18n

• 新增键 attachment.download_count / attachment.download，三语同步（lang/{zh,en,zh_tw}.php，基线各 1224 键）
• I18n::get() 缺键是 return $key; → 不报错，只在页面把键名当文案吐出来，必须跑全量比对

七、附件卡片 UI（公共组件 + Modern 样式）

7.1 组件收敛：2 处渲染 → 1 份代码

新增 app/Views/_components/attachment_card.php（模板引擎已支持 {include} → $this->include($tpl, $extra)）， 入参 att / variant（main | post）/ showDownloads。

调用点：app/Views/thread/show.php（2 处：主楼 + 回帖）→ 收敛为 1 份逻辑。 组件只输出语义类 .fh-attach-*，样式由 modern.css 提供。

7.2 视觉设计（Modern）

图片卡

• 栅格：display:grid; grid-template-columns:repeat(auto-fill,minmax(120px,1fr)); gap:8px
• 缩略图：width:100%; aspect-ratio:4/3; object-fit:cover（去掉 200×150 硬编码）
• hover：scale(1.03) + 主色描边；prefers-reduced-motion 下禁用
• 文件名单行省略；src="/attachment/{id}?s=thumb"

文件卡

┌────────────────────────────────────────────────┐
│ ┌────┐  project-spec-2026.pdf                 │
│ │PDF │  2.4 MB · 下载 37 次                    │
│ └────┘                        [ ↓ 下载 ]      │
└────────────────────────────────────────────────┘

• 类型图标（复用系统内置图标，不新增资源）： pdf→file-pdf、zip/rar/7z→file-archive、doc/docx→file-word、 xls/xlsx→file-excel、txt/md→file-alt、其他 →file
• 大小走 Upload::formatSize()，替代现有 2048.0 KB
• 下载按钮复用 .mn-btn.mn-btn-sm + download 图标

7.3 移动端（@media (max-width:768px)）

• 图片栅格降为 minmax(100px,1fr)，480 以下 2 列
• 文件卡：图标 + 文件名占满，按钮不压缩；文件名 word-break:break-all（已有 .thread-file-name 可复用）
• 触控目标高度 ≥ 40px

7.4 主题范围

八、灯箱（全页连读 + 预载，仅详情页）

8.1 加载范围（按你的要求）

8.2 多图切换设计（全页连读）

九、改动文件汇总

十、施工顺序（P0 → P7，逐段可验证）

十一、风险与应对

十二、开工前最后确认