let5see/to-live-photo
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 文档生命周期管理规范化

Browse Source 
CLAUDE.md:
- 新增「文档管理」章节，明确文档分类和更新策略
- 核心原则：不创建需要手工同步的文档

删除过时文档:
- PROJECT_STRUCTURE.md（代码即结构）
- docs_index.md（直接浏览目录）

归档历史设计文档:
- PRD/TECHSPEC/IXSPEC 移入 docs/archive/

统一应用名称:
- 所有文档中 "Live Photo Maker" → "Live Photo Studio"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
empty
2025-12-16 10:55:18 +08:00
parent d97152b5df
commit cc6e137994
9 changed files with 30 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
docs/archive/IXSPEC_LivePhoto_App_V0.2_2025-12-13.md Normal file
View File

@@ -0,0 +1,136 @@
# 交互规格书｜Live Photo 制作与动态壁纸引导 App（V0.2-IX）
- 适用平台：iPhone / iPad（iOS / iPadOS）
- 日期：2025-12-13（Asia/Manila）
- 用途：用于 AI 生成 UI / 交互实现 / QA 对照
## 1. 设计原则
- 一条主线：导入 → 编辑 → 生成 → 保存 → 引导设置。
- 减少认知：默认 3 秒、默认锁屏比例模板、默认智能封面。
- 失败可行动：每个错误必须给“下一步”。
- 强预期管理：明确“通常仅锁屏动效”，以及系统版本差异。
## 2. 全局交互规范
### 2.1 导航与按钮
- 主按钮（Primary）：导入、生成、保存、去设置壁纸。
- 次按钮（Secondary）：再次编辑、重试、了解原因。
- 危险操作：清理缓存/删除作品需二次确认。
### 2.2 Loading / Empty / Error 规范
| 状态 | 表现 | 必备元素 |
|---|---|---|
| Loading | 进度条 + 阶段文案 | 取消/后台继续（可选）、预计步骤而非时间 |
| Empty | 插画/图标 + 1句解释 | 主按钮引导下一步 |
| Error | 标题 + 原因 + 建议 | 重试按钮 + 反馈入口（可选） |
## 3. 页面级交互规格
### 3.1 首页（HomeView）
| 区域 | 组件 | 交互 | 状态/校验 |
|---|---|---|---|
| 顶部 | App 标题 + 设置入口 | 点击设置进入 Settings（可选） | 无 |
| 主区 | 按钮：从相册导入视频 | 打开 PHPicker（视频过滤） | 无权限→解释页 |
| 主区 | 入口：高级合成（照片+视频） | 打开 PHPicker（照片+视频） | MVP可隐藏 |
| 主区 | 入口：教程/FAQ | 打开 Guide/FAQ | 版本检测提示 |
| 列表 | 最近作品（0~10） | 点击进入 Result；长按删除缓存（可选） | 空态展示提示 |
- 空态文案示例：**“导入一段 2–3 秒视频，做成可以长按播放的实况照片。”**
- 首次进入：可展示 2~3 页 onboarding（可选）。
### 3.2 编辑页（EditorView）
| 模块 | 组件 | 交互细节 | 默认值 |
|---|---|---|---|
| 预览 | 视频播放器（静音预览可选） | 支持播放/暂停；拖动时间轴预览 | 自动播放关闭 |
| 比例 | 比例选择器（模板chips） | 切换模板时保持主体居中；允许用户再拖拽微调 | iPhone锁屏模板 |
| 裁剪 | 画面裁剪手势 | 双指缩放、单指拖动；显示安全区参考线（可选） | scale=1 |
| 时长 | 时间裁剪条（range slider） | 限制 1.5~5s；默认 0~3s；自动吸附到整帧点 | 3秒 |
| 封面 | 封面帧滑杆 + 预览帧 | 滑动实时更新封面预览；提供“推荐封面”按钮 | 中间帧 |
| 操作 | 按钮：生成 Live Photo | 点击后进入 Processing；参数校验不通过则提示 | 可用 |
- 校验提示：时长过长→建议缩短；分辨率过高→建议开启兼容模式。
- iPad 适配：左侧预览、右侧参数面板；或上下布局（横屏）。
### 3.3 生成进度页（ProcessingView）
| 元素 | 说明 | 交互 |
|---|---|---|
| 进度条 | 0~100%；按阶段推进 | 不可拖动 |
| 阶段文案 | 例如：处理视频 / 写入实况信息 / 准备保存 | 随阶段自动切换 |
| 取消 | 终止任务并回到编辑 | 二次确认；取消后清理缓存 |
| 失败态 | 展示错误码+原因+建议 | 按钮：重试 / 返回编辑 |
### 3.4 结果页（ResultView）
| 区域 | 组件 | 交互 | 成功条件 |
|---|---|---|---|
| 顶部 | 缩略图 + Live 标识（模拟） | 长按预览动效（App内） | 预览流畅 |
| 主按钮 | 保存到相册 | 触发相册写入；成功弹 toast | 相册可见Live |
| 主按钮 | 去设置壁纸 | 进入 WallpaperGuide | 版本差异提示 |
| 次按钮 | 再次编辑 | 回到 Editor（保留参数） | 参数不丢 |
| 信息 | 作品参数摘要 | 展开查看细节（可选） | 无 |
### 3.5 壁纸引导页（WallpaperGuideView）
| 模块 | 内容 | 交互 | 备注 |
|---|---|---|---|
| 版本检测 | 显示：当前系统版本/是否支持Live锁屏动效 | 点击“了解原因”展开说明 | 必须明确限制 |
| 步骤卡片 | 步骤1~5（图文） | 每步可折叠；支持复制路径文案 | iPhone/iPad分支 |
| 常见问题 | Motion not available、低电量、找不到Live按钮等 | 点击展开答案 | MVP用静态文案 |
| 跳转设置 | 按钮：打开设置 | 打开 Settings（到首页即可） | 不承诺深链成功 |
| 完成确认 | 按钮：我已设置完成 | 记录引导完成埋点 | 用于漏斗统计 |
## 4. 文案与提示（统一模板）
### 4.1 错误提示模板
- 标题：一句话告诉用户发生了什么（例如：**“视频处理失败”**）
- 原因：给 1~2 条最可能原因（不要超过 3 条）
- 建议：给可点击动作（例如：**“切换到兼容模式（H.264）”**、**“缩短到 3 秒以内”**）
- 附加：可显示错误码（长按复制）与反馈入口（可选）
### 4.2 兼容模式说明（示例）
- 兼容模式会：降低分辨率、降帧率到 30fps、转码到 H.264（如需要）、将 HDR 转为 SDR。
- 目的：提升生成成功率与壁纸/分享兼容性。
## 5. 埋点事件字典（Event Dictionary）
### 5.1 事件命名规范
- 动词_对象_结果：例如 `import_video_success`
- 所有事件带公共属性：`app_version`, `os_version`, `device_model`, `locale`
### 5.2 核心事件表
| 事件名 | 触发时机 | 关键属性（properties） | 用途 |
|---|---|---|---|
| home_import_video_click | 点击“导入视频” | entry=home | 漏斗起点 |
| import_video_success | 完成导入并进入编辑 | duration,resolution,fps,codec,hdr | 素材分布 |
| editor_generate_click | 点击生成 | ratio,trim,has_cover,compat_mode | 转化与参数 |
| build_livephoto_start | 开始生成 | work_id,stage=normalize | 性能监控 |
| build_livephoto_fail | 生成失败 | error_code,stage,codec_policy,hdr_policy | 失败归因 |
| save_album_success | 写入相册成功 | asset_id,elapsed_ms | 闭环成功 |
| save_album_fail | 写入相册失败 | error_code,permission_state | 权限问题 |
| guide_open | 进入壁纸引导页 | from=result,os_support=true/false | 引导覆盖 |
| guide_complete | 点击“已设置完成” | time_spent_s | 引导成效 |
| cache_clear | 清理缓存 | freed_mb | 存储与留存 |
## 6. iPhone / iPad 适配规则
- iPhone：编辑页优先竖屏；底部工具栏；预览占上半屏。
- iPad：横屏优先；左右分栏（预览/参数）；支持拖拽文件导入（可选）。
- 安全区：裁剪预览提供参考线（可选）以减少锁屏 UI 遮挡主体。
## 7. QA 对照清单（交互）
1. 所有主按钮在不可用状态必须有原因提示（例如未选视频）。
2. 生成中返回/退出：必须提示风险（任务取消/后台）。
3. 权限拒绝：必须有解释页与“去设置开启”按钮。
4. iOS 16：引导页必须出现“不支持锁屏Live动效”的明确文案。
5. 所有错误页必须包含：重试与返回编辑两个行动。

557
docs/archive/PRD_LivePhoto_App_V0.2_2025-12-13.md Normal file
View File

@@ -0,0 +1,557 @@
PRD｜Live Photo 制作与动态壁纸引导 App
适用平台：iPhone / iPad（iOS / iPadOS）
文档版本：V0.2（草案）
日期：2025-12-13（Asia/Manila）
作者：——（待填）
# 1. 文档信息与变更记录
# 2. 背景与机会
用户希望把自拍视频/短片制作成“像苹果实况照片（Live Photo）一样”的内容，用于相册浏览、分享（例如发微信）、并在支持的系统版本上设置为锁屏动态壁纸。
痛点 1：现有转换工具分散，流程复杂（导入、裁剪、转码、导出、再去相册设置）。
痛点 2：很多用户不知道 iOS/iPadOS 不同版本对 Live Photo 壁纸的支持差异，导致“做出来不能动”。
痛点 3：对尺寸/时长/关键帧（封面）选择缺乏指导，成品效果不稳定。
本 App 提供一站式：导入视频 → 生成系统可识别的 Live Photo → 保存到相册 → 分步骤引导设置壁纸。
# 3. 产品目标与非目标
## 3.1 目标（Goals）
G1：用户可从“视频/照片素材”快速生成“系统相册识别的 Live Photo”，并保存到相册。
G2：提供清晰的“设置为锁屏动态壁纸”引导，降低因系统版本/设置项导致的失败率。
G3：通过模板与提示，帮助用户得到高成功率的“可播放、可分享、封面好看”的作品。
G4：适配 iPhone 与 iPad，不同屏幕与比例下提供合理裁剪与预览。
## 3.2 非目标（Non-goals）
不使用任何私有 API 直接替用户设置系统壁纸（App Store 会拒）。
不做云端素材社区/版权图库（可在后续版本作为增长模块另立项）。
不保证所有历史系统版本都能播放 Live Photo 壁纸动画（受系统能力限制）。
# 4. 目标用户与使用场景
## 4.1 目标用户（Personas）
P1：普通用户——想把自拍视频做成动态壁纸，但不懂格式/设置路径。
P2：内容创作者——需要批量把短视频转 Live Photo 进行分享与展示。
P3：设计/审美用户——关注裁剪、封面帧、色彩与动效节奏。
## 4.2 核心场景（Scenarios）
S1：用户选择一段 2-5 秒视频，生成 Live Photo，保存并设置为锁屏动态壁纸。
S2：用户选择“照片 + 视频”合成（照片做封面），并指定关键帧。
S3：用户生成后想发微信：需要在相册里保持 Live Photo 形态并可被微信识别。
S4：用户在 iPad 上制作，导出后在 iPhone 上设置壁纸（跨设备）。
# 5. 兼容性与约束
## 5.1 系统与功能可用性（建议写在 App 内）
Live Photo 生成与保存：iOS/iPadOS 14+（建议 15+）可实现（依赖 Photos / AVFoundation）。
“Live Photo 作为锁屏动态壁纸播放”：iOS 17 或更高版本支持在锁屏唤醒时播放（iPhone 官方说明）。
iPadOS 锁屏支持 Live Photo 的动效选项（官方 iPad 用户指南包含 Live Photo 动效按钮说明）。
注意：Live Photo 动效通常只作用于锁屏；主屏一般显示静态图（以系统版本为准）。
低电量模式等系统状态可能导致动效不可用（需在引导里提示）。
## 5.2 平台约束（必须写清）
iOS/iPadOS 没有公开 API 允许第三方 App 直接设置系统壁纸：只能引导用户在系统界面完成设置。
禁止使用私有 API、越狱方案或企业签名绕过（不符合 App Store 上架）。
# 6. 需求范围（MVP）
## 6.1 MVP 功能列表
导入：从相册选择视频；可选：选择封面照片（可不选，默认从视频自动取帧）。
编辑：裁剪比例（适配 iPhone/iPad 锁屏常见比例）、裁剪时长（建议 2-3 秒）、选择封面帧（关键帧）。
生成：将素材合成为系统可识别 Live Photo（照片 + pairedVideo + 元数据）。
保存：保存到系统相册（Live Photos 相簿 / 最近项目）。
引导：分步骤引导用户把 Live Photo 设置为锁屏动态壁纸（按系统版本展示不同路径）。
质量检测：生成后做一次本地校验（能否被系统识别为 Live Photo；失败原因提示）。
## 6.2 后续版本（Backlog）
模板：预设“人物/风景/文字”裁剪模板、调速/慢动作适配。
批量生成：一次导入多段视频，批量导出 Live Photo。
小组件/主题包：壁纸合集管理（订阅制/一次性购买）。
分享：一键分享（注意平台对实况/视频的支持差异）。
# 7. 用户流程
## 7.1 主流程：视频 → Live Photo → 设置锁屏
进入首页，点击【从相册导入视频】。
选择视频后进入编辑页：裁剪比例、裁剪时长、选择封面帧。
点击【生成 Live Photo】；显示进度与阶段文案（处理视频 / 写入元数据 / 保存准备）。
生成成功 → 点击【保存到相册】；提示“已保存，可在 Live Photos 相簿查看”。
进入【设置壁纸引导】：按步骤提示用户在系统【设置 > 墙纸】选择 Live Photo 并开启 Live 动效。
## 7.2 失败/异常流程
用户拒绝相册权限：展示解释页，并引导去系统设置开启。
生成失败（编码/元数据写入失败）：提示原因 + 建议（更换视频编码、缩短时长、降低分辨率）。
保存成功但系统未识别为 Live Photo：提示“请在相册查看是否有 Live 标识”，并提供重新生成按钮。
# 8. 功能需求详述
## 8.1 首页
入口 1：导入视频（必选）。
入口 2：导入照片 + 视频（可选，作为高级模式）。
入口 3：教程/引导（包含系统版本差异、常见问题）。
展示最近生成的作品列表（MVP 可只展示最近 10 条）。
## 8.2 编辑页
裁剪比例：常用预设（iPhone 锁屏 / 全面屏 / 4:3 等），支持手动缩放与拖拽。
时长：默认 3 秒；可选范围 1.5-5 秒（过长降低成功率与体积）。
封面帧：滑杆选择时间点；支持“智能推荐封面”（清晰、有人脸、少抖动）。
预览：静态预览 + 动效预览（模拟锁屏唤醒播放方式）。
## 8.3 生成引擎（核心）
输入：视频（必选） + 可选封面照片。
输出：照片文件（建议 HEIC）+ 视频文件（MOV，H.264/HEVC）+ 绑定元数据（identifier、still-image-time 等）。
关键规则：照片与视频共享同一 content/asset identifier；视频包含 still-image-time 标记关键帧。
对视频进行重封装（re-mux）以写入元数据；必要时重新编码（可配置：优先保留编码，失败则转码）。
导出参数建议：分辨率/比特率上限以保证速度与成功率；音频可选保留/移除。
本地校验：生成后尝试用系统方式加载校验（如 PHLivePhoto 请求加载）并输出可读错误。
## 8.4 保存到相册
使用 Photos 写入：photo 资源 + pairedVideo 资源。
成功回调：提示“已保存”；失败回调：展示错误与建议。
相册归类：系统会自动归类到 Live Photos；App 内保存最近作品列表。
## 8.5 动态壁纸设置引导
按系统版本展示不同文案与截图示意。
iOS/iPadOS 17+：引导用户进入【设置 > 墙纸 > 添加新墙纸 > 照片 > Live Photo】并开启 Live 播放选项。
iOS/iPadOS 16：明确提示系统限制；提供替代方案（设置静态壁纸/升级系统建议）。
常见失败提示：低电量模式、‘Motion not available’、素材参数不兼容等。
提供按钮：打开系统设置（尽量深链；无法深链则打开设置首页）。
# 9. 非功能需求
## 9.1 性能与体验
生成过程需有可见进度与阶段提示；失败可重试。
中间文件自动清理；不占用过多存储。
错误提示要“可行动”：给出下一步（缩短时长、降低分辨率、重新选择素材）。
## 9.2 隐私与合规
默认本地处理：不上传用户照片/视频。
权限最小化：仅在需要时请求相册/相机/麦克风权限，并提供用途说明。
如接入统计：匿名化、可关闭，并在隐私政策中说明。
# 10. 数据埋点与指标
## 10.1 核心漏斗
导入视频 → 进入编辑 → 点击生成 → 生成成功 → 保存成功 → 进入壁纸引导 → 引导完成（点击“完成/已设置”）。
## 10.2 关键指标（KPIs）
生成成功率（按机型/系统版本/视频参数分层）。
保存成功率（相册写入成功）。
引导完成率（壁纸设置引导）。
7 日留存（如后续商业化，再加转化率）。
# 11. 里程碑建议
M0：技术预研（Live Photo 合成可行性、系统版本验证、参数边界）。
M1：MVP（导入视频 → 生成 → 保存 → 基础引导）。
M2：适配 iPad + 编辑体验提升（比例模板、预览增强）。
M3：稳定性与质量（失败提示、自动降级转码、素材建议）。
# 12. 验收标准（MVP）
在 iPhone（至少 2 款机型）与 iPad（至少 1 款机型）上：从相册导入视频可生成 Live Photo 并保存到系统相册。
生成的 Live Photo 在系统相册中显示为 Live Photo（有 Live 标识，长按可播放）。
在支持 Live Photo 锁屏播放的系统版本上，用户可按引导步骤完成设置并在唤醒锁屏时播放。
在不支持版本上，App 必须明确提示限制并给出替代方案，避免误导。
不使用私有 API，权限声明齐全，可通过 App Store 审核。
# 13. 风险与对策
R1：系统版本差异 → 版本检测 + 差异化引导文案。
R2：素材多样导致失败 → 参数归一化 + 自动降级转码 + 可读错误提示。
R3：用户期待“主屏也会动” → 产品内明确说明：通常仅锁屏动效。
R4：审核风险 → 只做引导，不做自动设置；不接触私有 API。
# 14. 参考资料（TBD）
Apple Support：Set a Live Photo as your Lock Screen wallpaper (iOS 17+): https://support.apple.com/120734
Apple Support：Change your iPhone wallpaper（含 Live Photo 入口说明）: https://support.apple.com/102638
Apple iPad User Guide：Create a custom iPad Lock Screen: https://support.apple.com/guide/ipad/ipad782d4de8/ipados
Apple iPad User Guide：Change the wallpaper on iPad: https://support.apple.com/guide/ipad/ipad997d908e/ipados
# 15. 信息架构与页面清单
本节用于指导你用 AI 编码时的页面/路由/组件拆分。
## 15.1 信息架构（IA）
首页（Home）：导入视频 / 高级合成 / 教程与FAQ / 最近作品列表
编辑页（Editor）：比例裁剪、时长裁剪、封面帧选择、预览、生成按钮
生成进度页（Processing）：阶段进度、取消/后台、失败原因与重试
结果页（Result）：保存到相册、再次编辑、进入壁纸引导、分享（后续）
壁纸引导页（Wallpaper Guide）：按系统版本展示步骤、常见问题、跳转设置
作品库（Library - MVP可选）：最近作品、再次导出、删除缓存
设置（Settings）：权限状态、清理缓存、隐私、关于、反馈
## 15.2 页面与路由（建议命名）
# 16. 用户故事与验收标准（更细颗粒）
## 16.1 用户故事（User Stories）
## 16.2 验收标准（按故事拆分）
US-01：生成后在系统相册中显示 Live 标识；长按可播放；不出现仅照片或仅视频的孤儿资源。
US-02：裁剪后的导出在锁屏预览时主体居中，用户可通过手势调整；导出不拉伸。
US-03：用户选定封面帧后，相册静态显示与导出封面一致（允许系统做轻微处理）。
US-05：引导页能根据系统版本显示正确路径；并提示‘低电量模式/系统限制’等常见原因。
US-06：错误提示包含：错误标题 + 可能原因 + 可点击的解决建议（例如缩短时长/降低分辨率/改用H.264）。
# 17. 详细功能需求表（可直接喂给 AI 编码）
## 17.1 功能点-输入-处理-输出
## 17.2 关键约束与参数建议
推荐时长：2-3秒（越长越大且更容易失败）。
推荐分辨率上限：以锁屏显示为目标，通常不需要超过 1440p；可按设备上限做自适应。
帧率：建议 30fps；高帧率素材可降到30fps以提升兼容性。
编码：优先保留原编码；失败时降级到 H.264 + AAC（更通用）。
HDR/Dolby Vision：可提示用户可能存在兼容性问题；必要时转 SDR。
# 18. 技术方案概述（研发实现导向）
## 18.1 模块划分
## 18.2 Live Photo 合成关键点（落地检查清单）
生成 assetIdentifier（UUID字符串）。
图片侧：写入 Apple MakerNote/相关标识（建议HEIC）。
视频侧：写入 QuickTime content identifier 元数据 + still-image-time timed metadata track。
保存侧：PHAssetCreationRequest 同时写入 .photo 与 .pairedVideo。
校验侧：尝试从相册 asset 请求 PHLivePhoto 或检查 Live 标识是否出现。
## 18.3 权限与Info.plist
NSPhotoLibraryUsageDescription：读取相册用于选择素材
NSPhotoLibraryAddUsageDescription：保存生成的 Live Photo 到相册
NSCameraUsageDescription：如后续加入拍摄入口
NSMicrophoneUsageDescription：如保留或录制音频
# 19. 数据模型与本地存储
## 19.1 本地作品模型（示例）
WorkItem：id、createTime、sourceVideoLocalID、exportParams（ratio/trim/keyFrame）、resultAssetLocalID（相册asset.localIdentifier）、status（processing/success/failed）、errorCode、thumbnailPath。
缓存目录：/Library/Caches/LivePhotoBuilder/{workId}/（中间mov、heic、日志）。
清理策略：成功后保留缩略图与参数；中间文件按设置或定期清理。
# 20. QA 测试计划（MVP）
## 20.1 测试矩阵
## 20.2 用例清单（样例）
从相册导入竖屏30fps H.264视频，默认参数生成并保存，确认相册显示Live标识且可播放。
导入60fps HEVC视频，选择3秒裁剪，生成成功；若失败需自动降级转码并提示。
导入HDR视频，提示可能兼容性风险；选择转SDR后生成成功。
拒绝相册权限后再次进入导入流程，能看到解释页并可跳转系统设置。
在iOS 16设备：壁纸引导页必须显示“系统限制/不支持动效”的文案与替代方案。
# 21. 合规、审核与版权
壁纸设置：不得宣称“一键自动设置系统壁纸”，应明确为“引导用户在系统中设置”。
权限说明：文案必须与实际用途一致，避免过度索权。
版权与内容：用户素材本地处理；若引入模板/素材库需提供版权声明与授权来源。
隐私政策：说明是否收集设备信息、崩溃日志与使用数据；提供关闭选项。
# 22. 文案与引导内容（可直接放App里）
## 22.1 关键页面文案（示例）
## 22.2 壁纸设置步骤卡片（iOS 17+ 示例）
打开【设置】->【墙纸】。
点击【添加新墙纸】->【照片】。
选择你刚保存的 Live Photo（带 Live 标识）。
点击屏幕左下角的【Live】按钮确保动效开启（若可见）。
保存并设置到锁屏。唤醒锁屏时，按压/触摸或系统动作会触发动效（以系统表现为准）。
提示：提示：若出现 “Motion not available”，请检查：是否开启低电量模式、是否选择了 Live Photo、素材是否过长/过大。
# 23. 开放问题（需你决策后再让AI编码）
商业化：免费+广告？一次性买断？订阅（模板/批量/高清导出）？
支持的最低系统版本：iOS 14/15/16？（决定了API与用户覆盖）
是否支持拍摄直接生成（AVCapture Live Photo Capture）作为后续版本？
是否需要“跨设备同步”（iCloud）保存作品参数/模板？
是否需要“微信分享优化”（检测相册资产是否仍为Live Photo形态）？
# 附录：表格汇总
## 表格 1
| 版本 | 日期 | 作者 | 说明 |
| --- | --- | --- | --- |
| V0.1 | 2025-12-13 | —— | 首版草案：功能范围、流程与需求拆解 |
| V0.2 | 2025-12-13 | —— | 补充：信息架构、用户故事、详细需求表、技术方案、QA/合规与开放问题 |
| V1.0 | —— | —— | （预留） |
## 表格 2
| 页面 | 路由/模块名 | 主要能力 | MVP |
| --- | --- | --- | --- |
| 首页 | HomeView | 导入入口、最近作品 | 是 |
| 编辑 | EditorView | 裁剪/封面/预览/生成 | 是 |
| 生成进度 | ProcessingView | 进度、取消、失败重试 | 是 |
| 结果 | ResultView | 保存、再次编辑、引导入口 | 是 |
| 壁纸引导 | WallpaperGuideView | 版本检测、步骤卡片、FAQ | 是 |
| 作品库 | LibraryView | 作品管理 | 可选 |
| 设置 | SettingsView | 权限、清理、隐私、反馈 | 可选 |
## 表格 3
| 编号 | 用户故事 | 优先级 | 备注 |
| --- | --- | --- | --- |
| US-01 | 作为用户，我想从相册选择一段视频并生成 Live Photo，这样我可以在相册长按播放。 | P0 | 核心闭环 |
| US-02 | 作为用户，我想裁剪比例以适配锁屏，避免设置壁纸后被系统裁掉关键主体。 | P0 | 需预设模板 |
| US-03 | 作为用户，我想选择封面帧（关键帧），这样锁屏静止画面最好看。 | P0 | 提供智能推荐 |
| US-04 | 作为用户，我想保存到相册并看到 Live 标识，确保微信等平台可识别为实况。 | P0 | 写入 pairedVideo |
| US-05 | 作为用户，我想得到清晰的设置壁纸引导，减少我找不到入口或不能动的困扰。 | P0 | 版本差异化 |
| US-06 | 作为用户，我希望失败时能看到原因和解决办法，而不是一句“失败”。 | P0 | 错误可行动 |
| US-07 | 作为高级用户，我想用‘照片+视频’合成，以照片为封面，视频为动效。 | P1 | 高级模式 |
| US-08 | 作为用户，我想一键清理缓存，避免占用太多存储。 | P1 | 设置页 |
## 表格 4
| 功能点 | 输入 | 处理/规则 | 输出/状态 | 优先级 |
| --- | --- | --- | --- | --- |
| 导入视频 | PHPicker选择视频 | 读取时长/分辨率/帧率/编码；提示不推荐参数 | 进入编辑页或提示不兼容 | P0 |
| 比例裁剪 | 视频画面 + 模板比例 | 支持拖拽/缩放；保持比例；实时预览 | 裁剪区域参数（scale/offset） | P0 |
| 时长裁剪 | 起止时间 | 默认3秒；限制1.5-5秒；对齐关键帧建议 | trimStart/trimEnd | P0 |
| 封面帧选择 | 时间点t | 提供静帧预览；可智能推荐t* | keyFrameTime | P0 |
| 生成Live Photo | 视频+裁剪+关键帧(+可选封面照) | 重封装写入content identifier、still-image-time；必要时转码 | photoURL + videoURL + 成功/失败 | P0 |
| 保存到相册 | photoURL+videoURL | PHAssetCreationRequest写入.photo与.pairedVideo | 相册新增Live Photo资产 | P0 |
| 引导设置壁纸 | 系统版本/设备类型 | 差异化步骤卡片；提示限制与FAQ | 用户完成率提升 | P0 |
| 缓存清理 | 中间文件目录 | 仅清理App生成缓存；不影响相册成品 | 释放存储空间 | P1 |
## 表格 5
| 模块 | 职责 | 关键框架/组件 |
| --- | --- | --- |
| MediaImport | PHPicker选择媒体、读取元信息 | PhotosUI, AVFoundation |
| EditorCore | 裁剪参数管理、预览渲染 | SwiftUI/UIView, AVPlayer |
| LivePhotoBuilder | 写入元数据、重封装/转码 | AVAssetReader/Writer, ImageIO |
| AlbumWriter | 写入系统相册 | Photos |
| Validation | 生成后校验是否为Live Photo | Photos, PHLivePhoto |
| GuideEngine | 版本检测、引导内容与FAQ | UIKit/SwiftUI |
| CacheManager | 中间文件管理与清理 | FileManager |
| Analytics | 埋点与漏斗 | 自研/第三方SDK |
## 表格 6
| 维度 | 覆盖建议 |
| --- | --- |
| 设备 | 至少2款iPhone（不同分辨率）+ 1款iPad |
| 系统 | iOS/iPadOS 17+（验证壁纸动效）+ iOS/iPadOS 16（验证限制提示） |
| 素材 | H.264/HEVC；30/60fps；SDR/HDR；有/无音频；竖/横屏 |
| 时长 | 1.5秒、3秒、5秒边界 |
| 权限 | 首次拒绝/后续开启；相册只读/读写 |
## 表格 7
| 场景 | 标题 | 正文/提示 | 按钮 |
| --- | --- | --- | --- |
| 生成中 | 正在生成 Live Photo | 正在处理视频并写入实况信息，请不要退出。 | 取消 / 后台继续 |
| 生成成功 | 生成成功 | 已生成实况照片。保存到相册后可在“照片”里长按播放。 | 保存到相册 / 去设置壁纸 |
| 保存成功 | 已保存到相册 | 你可以在“Live Photos”相簿找到它。 | 去设置壁纸 / 再做一个 |
| 不支持提示 | 当前系统限制 | 此系统版本无法将 Live Photo 作为可播放的锁屏壁纸。你仍可保存为实况照片，或升级系统后再设置。 | 了解原因 / 返回 |
| 低电量提示 | 可能无法播放动效 | 低电量模式可能导致锁屏动效不可用。 | 知道了 |

167
docs/archive/TECHSPEC_LivePhoto_App_V0.2_2025-12-13.md Normal file
View File

@@ -0,0 +1,167 @@
# 技术规格书｜Live Photo 制作与动态壁纸引导 App（V0.2-Tech）
- 适用平台：iPhone / iPad（iOS / iPadOS）
- 日期：2025-12-13（Asia/Manila）
- 用途：用于 AI 编码 / 架构落地 / 研发验收
## 1. 范围与目标
本技术规格书覆盖：媒体导入、编辑、Live Photo 合成与写入、校验、壁纸引导、缓存与日志、埋点。
- **目标**：在不使用私有 API 的前提下，生成系统相册可识别的 Live Photo 资产，并通过引导帮助用户设置锁屏动态壁纸。
- **非目标**：不直接替用户设置系统壁纸；不做云端上传/存储（默认本地）。
## 2. 总体架构
### 2.1 模块分层
| 层级 | 模块 | 职责 | 关键技术 |
|---|---|---|---|
| UI | Home/Editor/Processing/Result/Guide | 页面展示、交互、状态驱动 | SwiftUI（推荐）/UIKit |
| Domain | Workflows | 导入-编辑-生成-保存-引导的业务编排 | async/await, Combine(可选) |
| Service | MediaImport / Builder / AlbumWriter / Validation | 导入、合成、写相册、校验 | PhotosUI, AVFoundation, Photos, ImageIO |
| Infra | CacheManager / Logger / Analytics | 缓存、日志、埋点、错误封装 | FileManager, OSLog, 自研/第三方 |
### 2.2 目录结构建议（Xcode）
- App/（入口、DI、AppState）
- Features/Home, Features/Editor, Features/Processing, Features/Result, Features/Guide
- Domain/Models（WorkItem、ExportParams、Capability）
- Domain/UseCases（ImportVideo、BuildLivePhoto、SaveToAlbum、Validate、GenerateGuideSteps）
- Services/MediaImport, Services/LivePhotoBuilder, Services/AlbumWriter, Services/Validation
- Infra/Cache, Infra/Logging, Infra/Analytics, Infra/Errors
- Resources/（引导图、FAQ 文案、模板配置 JSON）
## 3. 核心数据模型
### 3.1 WorkItem（作品）
| 字段 | 类型 | 说明 |
|---|---|---|
| id | UUID | 作品唯一标识 |
| createdAt | Date | 创建时间 |
| sourceVideo | SourceRef | 来源引用：PHAsset localIdentifier 或 fileURL |
| coverImage | SourceRef? | 可选封面图引用 |
| exportParams | ExportParams | 比例/裁剪/关键帧等参数 |
| status | enum | idle/editing/processing/success/failed |
| resultAssetId | String? | 写入相册后的 asset.localIdentifier |
| cacheDir | URL | 中间文件目录 |
| error | AppError? | 失败信息（含可行动建议） |
### 3.2 ExportParams（导出参数）
| 字段 | 类型 | 说明/规则 |
|---|---|---|
| aspectRatio | Preset/CGFloat | 模板：iPhoneLock、Full、4:3… |
| cropTransform | scale + offset | 编辑页输出的裁剪参数 |
| trimStart | Double | 秒；默认0 |
| trimEnd | Double | 秒；默认3；限制1.5~5 |
| keyFrameTime | Double | 秒；在trim区间内 |
| audioPolicy | enum | keep/remove；默认keep |
| codecPolicy | enum | passthrough / fallbackH264 |
| hdrPolicy | enum | keep / toneMapToSDR（建议） |
| maxDimension | Int | 上限，例如 1920 或自适应 |
## 4. 状态机与工作流
### 4.1 作品状态机（建议）
- Idle（未开始）
- → Importing（导入中）→ Editing（编辑中）
- → Processing（生成中：Normalize → BuildPhoto → BuildVideo → Pairing → Validate）
- → Success（成功：可保存/已保存）
- → Failed（失败：含可重试点与建议）
处理阶段建议暴露为枚举（用于进度与日志）：
- normalize（归一化：裁剪/转码策略确定）
- extractKeyFrame（取关键帧/封面图）
- writePhotoMetadata（写图片侧元数据）
- writeVideoMetadata（重封装并写视频侧元数据）
- saveToAlbum（写入相册）
- validate（校验 Live Photo 是否可识别）
### 4.2 并发与取消
- 生成任务使用 Task（Swift Concurrency）实现，可被用户取消；取消时清理未写入相册的中间文件。
- 对 AVAssetReader/Writer 的写入任务采用串行队列/actor 封装，避免资源竞争。
- 避免主线程阻塞：任何转码/重封装/写文件都在后台队列或 Task 中执行。
## 5. Live Photo 合成实现规范
### 5.1 输入约束与预处理（Normalize）
- 时长：将 trim 区间限制在 1.5~5s（默认 3s）。
- 分辨率：按 maxDimension 缩放；优先保证主体清晰而不是极限画质。
- 帧率：高帧率（>30fps）可降至 30fps，以提升兼容性与体积。
- HDR：若检测到 HDR/Dolby Vision，优先提示并建议转 SDR（tone mapping），避免部分系统/场景识别异常。
### 5.2 绑定标识（Identifier）
- 每次生成一个 assetIdentifier（UUID string）。
- 图片与视频必须共享同一 identifier；否则系统不会将其识别为 Live Photo 对。
### 5.3 图片侧（Photo）输出规范
- 优先输出 HEIC（更现代且在较新系统上更稳定）；必要时支持 JPEG 作为降级。
- 写入 Apple MakerNote/相关字段以携带 identifier（实现时以可验证的字段集合为准）。
- 封面图来源优先级：用户选封面照片 > 从视频 keyFrameTime 抽帧。
### 5.4 视频侧（Paired Video）输出规范
- 容器：MOV。
- 写入 QuickTime metadata：content identifier（与照片一致）。
- 写入 timed metadata track：still-image-time（标记关键照片时刻）。
- 尽量 re-mux（不重编码）提升速度；若写入失败或素材不兼容，再降级到转码流程。
### 5.5 写入相册规范
- 使用 PHAssetCreationRequest 同时 addResource：.photo 与 .pairedVideo。
- 在 performChanges 回调中记录成功/失败；成功后写入 resultAssetId；失败需返回可行动错误。
### 5.6 校验（Validation）
- 策略 A：保存后用 resultAssetId 取回 PHAsset，尝试请求 Live Photo（或检查其资源类型/子资源）。
- 策略 B：若无法直接取 Live Photo 对象，则至少验证：相册中显示 Live 标识（人工/自动化截图对比可作为 QA 手段）。
- 校验失败要区分：合成失败 vs 写相册失败 vs 系统未识别。
## 6. 错误码与可行动建议（Error Taxonomy）
| 错误码 | 阶段 | 用户可见文案（标题） | 常见原因 | 建议动作（App 提示） |
|---|---|---|---|---|
| LPB-001 | Import | 无法读取视频 | 权限不足/资源损坏 | 检查相册权限；换一个视频 |
| LPB-101 | Normalize | 素材参数不兼容 | HDR/超高分辨率/奇怪编码 | 开启“兼容模式”；降低分辨率/转 SDR |
| LPB-201 | Photo | 封面生成失败 | 抽帧失败/内存不足 | 缩短时长；降低分辨率；重试 |
| LPB-301 | Video | 视频处理失败 | 重封装/转码失败 | 切换到 H.264 兼容导出；关闭音频 |
| LPB-401 | Album | 保存到相册失败 | 无写入权限/相册忙 | 允许“添加到相册”；稍后重试 |
| LPB-501 | Validate | 系统未识别为实况 | 元数据不完整/系统限制 | 重新生成；尝试更短视频；升级系统（如需壁纸动效） |
| LPB-901 | Unknown | 发生未知错误 | 不可预期异常 | 反馈日志；重启 App；重试 |
## 7. 缓存、日志与诊断
### 7.1 缓存目录结构
- `Caches/LivePhotoBuilder/{workId}/source.mov`（可选）
- `Caches/LivePhotoBuilder/{workId}/normalized.mov`（归一化输出）
- `Caches/LivePhotoBuilder/{workId}/photo.heic`（封面图）
- `Caches/LivePhotoBuilder/{workId}/paired.mov`（写入元数据后的成品视频）
- `Caches/LivePhotoBuilder/{workId}/builder.log`（阶段日志，供反馈）
### 7.2 清理策略
- 成功：保留 photo/paired 的短期缓存（例如 24h）以支持“再次保存/分享”；随后自动清理。
- 失败：保留日志与关键中间文件（例如 24h），方便用户一键反馈；随后清理。
- 用户手动“清理缓存”：立即删除所有 workId 目录，但不影响系统相册成品。
## 8. 安全与隐私
- 默认全程本地处理，不上传用户素材。
- 日志默认不包含媒体内容本身；仅记录参数与错误码；用户反馈前需二次确认。
- 权限请求延迟到使用时，并提供用途说明与拒绝后的替代路径。
## 9. AI 编码提示（可直接复制给 AI）
- 按模块创建 Swift Package 或 App 内分组；对 LivePhotoBuilder 使用 `actor` 管理状态与文件路径。
- UseCase 层提供 async 函数：`importVideo()`, `buildLivePhoto()`, `saveToAlbum()`, `validate()`.
- UI 层采用单一 source of truth：`WorkItemViewState`；所有副作用通过 UseCase 注入。
- 为每个阶段输出结构化日志与 `progress (0~1)` + `stage enum`。