Merge pull request 'Move repository images and embedded template bitmaps to S3' (#23) from codex/s3-media into main

docs/learning-series.md

@@ -10,7 +10,7 @@
 
 内容位于 `src/content/learning-skills/data.ts`，版式位于 `Series.tsx` 和 `src/styles/learning-series.css`。每篇依次为共同封面、索引、五张双工具介绍、使用路线与来源；支持分页、索引跳转、连续阅读与同系列跳转。所有小样标注为排版示意；GitHub 来源已于 2026-10-23 核对，尚未逐项安装实测。
 
-`public/learning-skills/cover.svg` 是封面设计源稿，`cover.png` 是部署与素材库实际使用的图片，不依赖服务器安装中文字体重新渲染。
+`public/learning-skills/cover.svg` 是封面设计源稿，PNG 成品保存在 S3，路径及校验值登记于 `managed-media.json`，旧 `/learning-skills/cover.png` 路径通过媒体 API 提供，不依赖服务器安装中文字体重新渲染。
 
 ## 实际发布
 

docs/s3-media.md

@@ -0,0 +1,43 @@
+# 内容图片存储与本次迁移
+
+内容图片存放于现有 RustFS（S3 兼容）`prompt` bucket；PostgreSQL `assets` 保存媒体 ID、对象键、SHA-256、大小与尺寸。代码只保留引用及必要的矢量设计源稿。
+
+## 迁移结果（2026-10-29）
+
+- 从 Git 工作树移除 603 个 PNG 路径，共 38,085,328 字节（约 36.3 MiB）。全部路径及逐文件校验信息见 `apps/waterfall-wiki/src/content/managed-media.json`。
+- 内容寻址去重后为 572 个 S3 对象，键为 `repository-media/sha256/<sha256>.png`。全部上传后逐个 GET 读回并校验原始字节，再在数据库事务中登记元数据；未覆盖或删除现有媒体。
+- 通过现有生产管理员认证包装器，经 `/api/media/{id}` 再次读回全部 572 个对象，内容类型、字节数与 SHA-256 均通过。
+- 清单 SHA-256：`1e13d87e204de5c4483944f381823e539bf194d124a2e5b3e1ac98c08abddb35`。
+- 两份 Studio 模板 JSON 的 334 处 Base64 图片均对应已迁移对象，改为媒体 ID 引用。SVG 导出时从认证媒体 API 读取并临时嵌入，下载的 SVG 仍自包含。
+- 保留 `public/brand-mark.svg`（品牌图形）与 `public/learning-skills/cover.svg`（可编辑设计源稿）；测试中少量合成图片字符串及运行时图片编码逻辑属于必要代码，不是业务素材副本。
+- 本次直接迁移数据；未构建、未部署、未运行 CI/CD，未改写 Git 历史。旧提交仍含图片，当前线上镜像仍有原来的文件，均未破坏性清理。
+
+## 按目录说明移除范围
+
+| 路径 | 文件数 | 用途与替代 |
+| --- | ---: | --- |
+| `apps/waterfall-wiki/seed/characters/reference/*.png` | 15 | 参考人物素材，导入器改从媒体 API 取原图并校验 |
+| `apps/waterfall-wiki/seed/characters/original/*.png` | 4 | 新生成人物素材，同上 |
+| `apps/waterfall-wiki/public/skills/**/*.png` | 4 | 技能参考与示例图，旧路径映射至媒体 API |
+| `apps/waterfall-wiki/public/learning-skills/cover.png` | 1 | 学习系列封面，发布器读取 S3，旧 URL 保留兼容 |
+| `content/layout-reference/assets/**/*.png` | 573 | 版式源图、构件、蒙版、标注和重建图，作者工具读取外部缓存或媒体 API |
+| `docs/wiki-saas/screenshots/*.png` | 6 | 验收截图，文档链接改指向媒体 API |
+
+## 读取与恢复
+
+旧五个公开文件路径在下一次部署此代码时通过 Next rewrites 指向现有媒体 ID；访问权限沿用原有管理员认证。预览接口直接读取 S3。运行镜像只包含人物包 JSON 和媒体清单，不再包含 PNG。
+
+作者工具 `scripts/managed-media.mjs` 从媒体 API 下载并验证图片；可设置 `MEDIA_BASE_URL`（默认现有服务器地址）与进程环境中的 `PROMPT_TOKEN`。不要将令牌写入源码、命令参数或报告；重定向不会携带凭据。运行于服务器的作者脚本可通过现有 `auth-cli.cjs run` 包装器，在同源 `MEDIA_BASE_URL=http://127.0.0.1:3000` 下使用进程内认证。
+
+也可设置 `MEDIA_SOURCE_ROOT` 指向仓库外缓存，目录结构与清单相同。本次原文件备份位于仓库外路径：`/Users/zzyang/ProjectMedia/output/s3-media-migration-20261029/source`。该备份不提交 Git。
+
+`node scripts/managed-media.mjs /absolute/external-cache` 可下载整个清单到外部目录，拒绝写入仓库。版式封面生成器要求 `MEDIA_OUTPUT_FILE` 指向仓库外；分割工具使用仓库外 `MEDIA_AUTHORING_ROOT`。产出新素材后先上传 S3、登记数据库与清单，再更新引用；不要提交 PNG 或把图片转成 Base64 塞回 JSON。
+
+灾难恢复必须同时保留数据库备份和 S3 bucket。清单只保存索引，不替代数据库或对象存储备份。新环境需恢复所需对象及其 `assets` 元数据；隔离集成测试使用合成图片，不读取生产素材。
+
+## 检查结果
+
+- 16 项 Studio 单元测试、3 项清单与缓存测试、2 项人物包校验测试通过；JavaScript 语法及 `git diff --check` 通过。
+- Studio `tsc --noEmit --incremental false` 通过。
+- Wiki 同一类型检查因本地已有依赖未安装完整（`nodemailer` 无法解析）未通过；本次未安装依赖、未运行 Next typegen。
+- 完整集成测试、应用构建和部署未执行。用户要求此次不用 CI/CD；工作分支与 PR 不触发当前仅 main push 的工作流。用户后续手动合并 main 将按现有规则触发 CI/CD，须自行安排合并时机。

docs/wiki-saas/DESIGN.md

@@ -38,9 +38,9 @@
 
 以下为最终生产模式预览截图。社区条目、作者邮箱和编辑器内容均为明确的回归测试夹具，不是生产用户数据；它们只证明 UI 状态，不证明真实邮件投递或持久化发布。
 
-- [桌面目录](screenshots/directory.png)
-- [桌面阅读](screenshots/reader.png)
-- [账户注册](screenshots/account.png)
-- [结构化编辑器](screenshots/editor.png)
-- [手机目录](screenshots/mobile-directory.png)
-- [手机阅读](screenshots/mobile-reader.png)
+- [桌面目录](http://8.211.154.134:18131/api/media/ff134051-5c10-5ccf-a7a1-67c8e7adec04)
+- [桌面阅读](http://8.211.154.134:18131/api/media/c1f67e06-7fe0-520e-9ff6-4a7344163fa1)
+- [账户注册](http://8.211.154.134:18131/api/media/7c0b8374-1f8f-512f-90bc-97cef33c1891)
+- [结构化编辑器](http://8.211.154.134:18131/api/media/63718bd4-3a25-595e-bd45-59f9fbfff1f1)
+- [手机目录](http://8.211.154.134:18131/api/media/3952da7d-5b22-5d03-b3d3-849edcf06fcb)
+- [手机阅读](http://8.211.154.134:18131/api/media/34f6036f-3d5d-5b1b-950b-3fdeac278eb9)