# TASK｜to-live-photo

> 说明：本清单按阶段拆解研发事项，默认最低支持 iOS/iPadOS 16+，先完成 MVP 闭环，再逐步完善。

## M0｜技术预研 / POC（以"系统可识别 Live Photo"为第一目标）✅

- [x] 建立 Xcode 工程骨架（SwiftUI 优先），设置 Deployment Target = iOS/iPadOS 18.0
- [x] 补齐权限与 Info.plist 文案：
  - [x] NSPhotoLibraryUsageDescription
  - [x] NSPhotoLibraryAddUsageDescription
- [x] POC：最小链路跑通（不做复杂编辑）
  - [x] 从相册导入视频（PHPicker，视频过滤）
  - [x] 以默认参数（~0.917s、1080x1920、60fps 策略）生成 photo + pairedVideo
  - [x] 写入相册（PHAssetCreationRequest 同时写入 .photo 与 .pairedVideo）
  - [x] 校验：保存后按 assetId 取回并验证 Live 识别（相册 Live 标识 + 长按可播 + **可设置为动态壁纸**）
- [x] 约束与策略确认（写入代码常量/配置）：
  - [x] 时长限制：标准化为 ~0.917s（与 iPhone 原生 Live Photo 一致）
  - [x] 分辨率上限：竖屏 1080x1920，横屏 1920x1080
  - [x] 帧率策略：统一转换为 60fps
  - [x] HDR 策略：默认转 SDR（ExportParams.hdrPolicy = .toneMapToSDR）
  - [x] 编码策略：默认 H.264（ExportParams.codecPolicy = .fallbackH264）
- [x] 设计基础设施：
  - [x] WorkItem / ExportParams 数据模型（与 TECHSPEC 对齐）
  - [x] CacheManager：按 workId 建目录
  - [x] Logger：LivePhotoLogger 阶段化日志

### M0 完成定义

- [x] 能在至少 1 台 iPhone + 1 台 iPad 上生成并保存 Live Photo，且系统相册可识别（有 Live 标识，长按可播放）。
- [x] **额外达成**：生成的 Live Photo 可设置为动态壁纸，动态效果正常。

## M1｜MVP（导入→编辑→生成→保存→引导）

### 1) UI 页面闭环

- [x] HomeView：首页导入入口（最近作品功能移至 M2）
- [x] EditorView：时长裁剪、预览（比例裁剪/封面帧选择移至下方编辑能力）
- [x] ProcessingView：进度条 + 阶段文案 + 返回重试
- [x] ResultView：保存到相册、进入壁纸引导、继续制作
- [x] WallpaperGuideView：按系统版本展示步骤卡片、FAQ、打开照片 App、完成确认

### 2) 编辑能力（MVP 版）

- [x] 比例模板：iPhone 锁屏 / 全面屏 / 4:3 等（先做 2~3 个核心模板）
- [x] 裁剪手势：缩放 + 拖拽，保持比例
- [x] 时长裁剪：slider（1~1.5s 范围）
- [x] 封面帧：滑杆选择 keyFrameTime，实时刷新封面预览

### 3) 生成与保存（与 TECHSPEC 阶段枚举对齐）

- [x] 生成管线：normalize → extractKeyFrame → writePhotoMetadata → writeVideoMetadata → saveToAlbum → validate
- [x] 取消策略：取消时终止任务并清理未写入相册的中间文件
- [x] 错误码与可行动建议：覆盖 LPB-001/101/201/301/401/901

### 4) 引导内容（MVP 版）

- [x] 版本检测：iOS/iPadOS 16 显示"系统限制/不支持锁屏 Live 动效"的明确文案
- [x] iOS/iPadOS 17+：展示步骤卡片（照片 App → 分享 → 用作壁纸 → 开启 Live）
- [x] FAQ：Motion not available、低电量模式、找不到 Live 按钮等

### 5) 基础埋点（可先打印日志，后续再接 SDK）

- [x] home_import_video_click / import_video_success
- [x] editor_generate_click / build_livephoto_start / build_livephoto_fail
- [x] save_album_success / save_album_fail
- [x] guide_open / guide_complete

### 6) MVP QA（手工为主）

- [x] 测试矩阵：iPhone 1~2 台 + iPad 1 台；iOS/iPadOS 17+ 与 16 各至少 1 台
- [x] 素材覆盖：H.264/HEVC、30/60fps、竖/横、SDR/HDR
- [x] 验收点：生成成功率、保存成功率、相册识别率、引导文案准确性
- [x] 测试文档：docs/TEST_MATRIX.md（包含 13 个测试用例）

### M1 完成定义

- [x] 按 PRD 的 MVP 验收标准打通闭环：生成 Live Photo → 保存相册可识别 → 可进入引导并在不同系统版本下给出正确提示。

## M2｜完善（体验提升 + 失败率降低）

- [x] 兼容模式开关（UI 可见）：降分辨率/30fps/H.264/SDR
- [x] 自动诊断与建议：根据素材参数提示"建议缩短/建议兼容模式/建议转 SDR"等
- [x] iPad 编辑页布局优化：左右分栏（预览/参数）
- [x] 最近作品列表完善：持久化（仅存参数与缩略图/assetId，不重复存媒体）
- [x] 设置页（可选）：权限状态、清理缓存、反馈入口
- [x] 错误反馈包导出（可选）：builder.log + 参数（不包含媒体内容）

## M3｜稳定性 / 上线准备

- [x] 性能与内存优化：大视频处理、峰值内存控制
- [x] 崩溃与异常收敛：日志脱敏、错误归因完善（按 stage 统计）
- [x] App Store 合规检查：权限文案、引导表述（不承诺一键设置壁纸）、隐私说明
- [x] 产出核心文档补齐（按需要最小化）：
  - [x] 测试文档：MVP 测试矩阵与用例
  - [x] 用户手册：导入/生成/保存/设置引导与常见问题

## M4｜AI 增强（差异化功能）

- [x] Real-ESRGAN Core ML 集成架构
  - [x] AIEnhancer 模块：公共 API 和配置
  - [x] RealESRGANProcessor：Core ML 推理逻辑
  - [x] TiledImageProcessor：真正的分块处理（512×512 tiles，64px 重叠，加权混合拼接）
  - [x] WholeImageProcessor：小图处理（≤512×512 使用整图缩放）
  - [x] ImageFormatConverter：格式转换工具
- [x] LivePhotoCore 集成
  - [x] ExportParams 扩展 aiEnhanceConfig
  - [x] LivePhotoBuildStage 新增 .aiEnhance 阶段
  - [x] resolveKeyPhotoURL 集成 AI 增强（失败静默降级）
- [x] UI 集成
  - [x] EditorView AI 超分辨率开关
  - [x] ProcessingView 新阶段文案
  - [x] 设备能力检查（isAvailable）
- [x] 模型准备
  - [x] 使用预转换的 Real-ESRGAN x4plus Core ML 模型（来源：john-rocky/CoreML-Models）
  - [x] 将 RealESRGAN_x4plus.mlmodel 放入 Resources 目录（66.9MB，编译后 64MB）
  - [x] Package.swift 已配置模型资源打包
  - [x] 模型输入 512x512，输出 2048x2048，实际放大约 2.25x

## M5｜未来优化（可选）

- [ ] 包体积优化
  - [ ] 使用 INT8 量化模型（预估可从 64MB 降至 ~16MB）
  - [ ] 或使用 On-Demand Resources 按需下载模型
- [x] AI 增强质量优化（已完成 ✅）
  - [x] 真正的分块处理：将大图拆分为 512×512 tiles，分别推理后拼接
  - [x] 64px 重叠区域 + 线性权重混合，消除接缝
  - [x] 自动选择处理器：大图用 TiledImageProcessor，小图用 WholeImageProcessor
  - [x] 信息损失从 ~86% 降至 0%（1080×1920 图像不再压缩）
- [ ] 高级合成功能（照片+视频合成 Live Photo）
  - [ ] 双导入入口：支持分别选择静态照片和视频
  - [ ] 尺寸对齐逻辑：照片自动 match 视频尺寸
  - [ ] resolveKeyPhotoURL 扩展：支持外部照片输入
  - [ ] UI 设计：照片裁剪/对齐预览
- [ ] 其他性能优化
  - [ ] 尝试使用支持灵活输入尺寸的模型（EnumeratedShapes）
  - [ ] 探索 Metal Performance Shaders 替代方案

---

## 决策备忘（已完成 ✅）

- [x] **HDR 默认策略**：✅ 保持默认转 SDR
  - 理由：Live Photo 壁纸场景下 SDR 显示更稳定，避免 HDR 在不同设备/亮度下显示不一致
  - 后续：M5 可在设置页添加"高级选项"供专业用户切换

- [x] **编码兜底策略**：✅ 保持完全自动兜底
  - 理由：符合"Just Works"理念，诊断系统已能提前识别风险并建议兼容模式
  - 可选改进：ProcessingView 显示"使用兼容模式编码中..."提升透明度

- [x] **高级合成功能**（照片+视频）：✅ 延后到 M5 或 M6
  - 理由：属于高级功能，非核心需求，当前专注上线 M0-M4
  - 技术要点：双导入入口、尺寸对齐逻辑、resolveKeyPhotoURL 扩展