PersonalWebApplication/docs/superpowers/specs/2026-06-29-special-folder-video-media-design.md

设计：特殊文件夹视频媒体（上传后服务器压缩）

在特殊文件夹共享照片墙（#<文件夹名>）里支持视频作为墙上媒体元素。 视频上传后先显示处理中占位卡，服务器用 ffmpeg 压缩为低带宽 MP4，完成后在墙上播放。 本设计只开放给特殊文件夹；个人 #photo 暂不开放视频入口。

状态：规划中，当前代码尚未实现 /media* 接口、视频上传、转码和视频卡片渲染。

前置阅读：

• photo-wall.md
• 2026-06-24-special-folders-design.md
• 2026-06-24-photo-wall-server-storage-design.md

1. 目标与范围

目标：

• 特殊文件夹支持图片和视频混合展示。
• 视频像照片一样可以上传、拖拽、缩放、置顶/置底、删除。
• 视频上传后不阻塞页面等待转码；墙上立即出现“thinking”风格的处理中卡片。
• 服务器将常见视频格式统一压缩为适合 3M 带宽播放的 MP4。
• 不提供显式视频下载入口，不添加下载按钮；这不是防下载安全边界。

非目标：

• 个人 #photo 视频上传。
• 多清晰度转码、自适应码率、HLS/DASH。
• 视频封面生成、时间轴截图、在线播放统计。
• 大视频断点续传。

2. 总体架构

前端把 PhotoWallPage 从“照片元素”扩展为“媒体元素”，新增 video 类型。特殊文件夹使用新的媒体 API 加载图片和视频；图片仍按现有视觉展示，视频按状态渲染为处理中卡片、失败卡片或 <video controls preload="metadata"> 播放器。

后端把特殊文件夹存储从“图片列表”升级为“媒体列表”。图片可以同步保存并立即进入 ready 状态。视频上传后先写入临时文件，创建状态文件，后台调用 ffmpeg 转码；转码完成后只保留压缩后的 .mp4 和状态文件，删除原始临时文件。

ffmpeg -movflags +faststart 只用于优化浏览器在线播放体验：把 MP4 索引移动到文件开头，让 <video> 不必等完整文件下载完才开始播放。UI 不提供显式下载按钮；浏览器原生视频控件仍需加 controlsList="nodownload" 降低下载入口暴露，但这不构成防下载或防复制安全边界。

3. 媒体模型

特殊文件夹媒体项：

type MediaType = 'image' | 'video'
type MediaStatus = 'ready' | 'processing' | 'failed'

interface FolderMediaItem {
  id: string
  type: MediaType
  status: MediaStatus
}

服务器为视频维护状态文件，建议路径为 SPECIAL_DIR/<folder>/media/<id>.json：

{
  "id": "a1b2c3d4e5f60708",
  "type": "video",
  "status": "processing",
  "originalName": "trip.mov",
  "createdAt": "2026-06-29T12:34:56Z",
  "outputFile": "a1b2c3d4e5f60708.mp4",
  "error": null
}

状态语义：

• processing：原视频已接收，后台正在转码。前端显示处理中占位卡并轮询状态。
• ready：媒体可通过 GET /media/{id} 读取。图片返回原图，视频返回压缩后的 MP4。
• failed：转码失败。前端显示失败卡片，允许删除后重传。

4. 后端接口

新增特殊文件夹媒体接口，旧 /photos* 接口先保留，前端特殊文件夹切到 /media*：

方法	路径	鉴权	行为
GET	/api/web/folder/{name}/media	AuthUser + 白名单	列出图片和视频，返回 { items, max, totalBytes, overQuota }
POST	/api/web/folder/{name}/media	AuthUser + 白名单	multipart 上传一个图片或视频
GET	/api/web/folder/{name}/media/{id}	AuthUser + 白名单	读取 ready 媒体字节
GET	/api/web/folder/{name}/media/{id}/status	AuthUser + 白名单	读取单个媒体状态
DELETE	/api/web/folder/{name}/media/{id}	AuthUser + 白名单	删除媒体文件、临时文件和状态文件

上传响应：

{
  "id": "a1b2c3d4e5f60708",
  "type": "video",
  "status": "processing"
}

错误码：

• 403：用户无权访问该特殊文件夹。
• 404：文件夹或媒体不存在。
• 409：达到特殊文件夹元素上限。
• 413：上传体或文件过大。
• 415：不支持的媒体格式。
• 500：IO 或转码任务启动失败。

5. 上传与格式

视频上传使用 multipart，而不是 data URL。原因是视频文件可能很大，data URL 会额外增加约三分之一体积，并迫使前后端把大文件整体放进内存。multipart 更适合 500MB 级文件。

支持的输入：

• 图片：沿用现有 jpg/png/gif/webp。
• 视频：支持常见格式，至少包括 mp4/mov/m4v/webm/avi/mkv。

约束：

• 单个原始视频最大 500MB。
• 单个图片仍沿用 8MiB 上限。
• 同一个特殊文件夹仍受总元素上限约束，图片、视频、装饰合计不超过当前 MAX_ITEMS。
• 视频上传不限制时长。

6. 视频转码

运行时依赖：服务器必须安装 ffmpeg，并保证 Rust 服务进程可以调用。

转码目标适配 3M 服务器带宽：

• 容器：MP4。
• 视频编码：H.264。
• 音频编码：AAC。
• 输出限制到 720p 档：横屏最大 1280x720，竖屏最大 720x1280，保持原方向，不放大小视频。
• 帧率限制到 24fps。
• 视频码率目标约 900kbps，缓冲 1800kbps。
• 音频码率 96kbps。
• +faststart 优化在线播放。

建议 ffmpeg 参数方向：

ffmpeg -y -i input \
  -vf "scale='min(iw,if(gte(iw,ih),1280,720))':'min(ih,if(gte(iw,ih),720,1280))':force_original_aspect_ratio=decrease:force_divisible_by=2,fps=24" \
  -c:v libx264 -preset veryfast -crf 30 -maxrate 900k -bufsize 1800k \
  -c:a aac -b:a 96k \
  -movflags +faststart output.mp4

实现计划必须用横屏、竖屏和近正方形视频测试该 filter，确认不会放大小视频，且输出不会超过 1280x720 或 720x1280 的目标边界。

并发策略：

• Rust 进程内视频转码并发限制为 1。
• 上传请求只负责接收文件、创建状态、启动后台任务，然后立即返回。
• 后台任务成功后把状态改为 ready，删除临时原视频。
• 后台任务失败后把状态改为 failed，删除临时原视频，保留短错误摘要。

7. 前端交互

特殊文件夹工具栏把“上传照片”改为“上传媒体”。选择文件、拖拽文件都支持图片和视频；剪贴板仍只要求保持图片粘贴可用，视频粘贴不是本期目标。

渲染规则：

• image + ready：沿用当前照片卡片。
• video + processing：显示软木板风格占位卡，文案为“thinking”。
• video + ready：显示带控件的 <video controls preload="metadata">，不自动播放。
• video + failed：显示“视频处理失败”，允许右键删除。

视频卡片行为：

• 支持拖拽、缩放、旋转、置顶/置底、删除。
• 双击编辑说明文字，逻辑与照片 caption 一致。
• 用户主动点击才播放，避免多个视频同时消耗 3M 带宽。
• 不显示显式下载按钮；<video> 使用 controlsList="nodownload"。该属性只是 UI 降噪， 不能当成安全控制。

轮询：

• 上传视频返回 processing 后，前端创建本地元素并开始轮询 /status。
• 轮询间隔建议 3 秒。
• 状态变为 ready 后获取 object URL 并替换播放器。
• 状态变为 failed 后停止轮询并显示失败卡。
• 组件卸载时停止轮询并释放 object URL。

8. 布局与状态兼容

当前特殊文件夹共享状态使用 photoLayout。本功能升级为通用 mediaLayout：

interface MediaLayout {
  x: number
  y: number
  rot: number
  scale: number
  z: number
  w: number
  caption: string
}

interface WallState {
  bgIndex: number
  decorations: El[]
  mediaLayout: Record<string, MediaLayout>
}

兼容策略：

• 前端读取状态时，如果存在 mediaLayout，优先使用。
• 如果只有旧的 photoLayout，前端把它当作 mediaLayout 读取。
• 保存状态时写 mediaLayout；可以同时保留 photoLayout 一段时间以兼容旧前端，但新前端不再依赖它。
• 后端 state 接口必须同步迁移：PUT /api/web/folder/{name}/state 需要接受 mediaLayout 和旧 photoLayout；GET 返回 mediaLayout，并在兼容期同时返回 photoLayout。仅改前端类型不够。
• 已有图片布局不丢失；新视频布局按同一媒体 id 保存。

9. 删除与清理

删除媒体时：

• ready image：删除图片文件。
• ready video：删除压缩后的 .mp4 和状态文件。
• processing video：写入删除标记或直接删除状态文件；后台任务结束后发现状态不存在即清理输出。
• failed video：删除状态文件和可能残留的临时文件。

列表接口不返回孤儿临时文件。启动时不要求恢复未完成任务；若服务重启导致任务中断，残留 processing 可以在下一次列表时标记为 failed 或由清理逻辑处理。

10. 测试策略

后端：

• 媒体 MIME/扩展名识别。
• 视频 id 与图片 id 的路径安全校验。
• 状态文件 processing -> ready -> failed 读写。
• 特殊文件夹权限：未注册 404、无权 403、有权通过。
• 删除会清理成品、状态和临时文件。
• ffmpeg 命令构造包含 720p、24fps、900k、96k、+faststart。
• ffmpeg 缩放测试覆盖横屏、竖屏、正方形/近正方形和小尺寸输入，确认不超过目标尺寸且不放大。

前端：

• 特殊文件夹图片上传和显示仍可用。
• 上传视频后立即出现“thinking”占位。
• 轮询到 ready 后替换为播放器。
• failed 状态显示失败卡并可删除。
• 视频拖拽、缩放、删除、caption、保存布局不破坏图片和装饰。
• <video> 渲染包含 controlsList="nodownload"，且产品文案只承诺不提供下载入口， 不承诺防下载。

端到端：

• 在本地安装 ffmpeg 后上传一个小视频，确认转码完成、播放不卡、刷新后布局保留。
• 生产部署后用特殊文件夹验证上传视频、等待处理、播放、删除。

11. 部署与文档

这是后端改动，需要全量重部署：重编 Rust、上传二进制和前端静态文件、重启 Rust 服务。

服务器新增运行时依赖：

• ffmpeg。

文档需要更新：

• docs/photo-wall.md：说明特殊文件夹支持视频媒体，个人墙暂不支持。
• docs/superpowers/plans/2026-06-18-deploy.md：补充安装 ffmpeg 和视频转码部署注意事项。
• docs/superpowers/specs/2026-06-24-special-folders-design.md：标注媒体接口和视频扩展已由本设计接续。