# 交互规格书｜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. 所有错误页必须包含：重试与返回编辑两个行动。