# ZipHarbor UI/UX 原型对照验收

日期：2026-10-01。设计基准：`app-prototype.html`。实现入口：`ZipHarbor/ZipHarbor.xcodeproj`。原型内的 ZipKit 是设计稿旧名，新工程品牌为 ZipHarbor。

## 验收方法与结论

实际打开 Safari 中的交互原型，逐页检查首页、归档详情、两步创建、任务、设置和底部弹层；通过 XCTest 在 iPhone 14 模拟器及 iPhone 14 / iOS 27.0 真机运行真实流程并保存截图，另在 iPad mini 模拟器验证创建往返和英文深色外观。并排证据见 [原型与实现对照](migration-comparison.html)，可切换真机与模拟器。

新界面已使用原型的信息层级、颜色、卡片、按钮、筛选和任务结构。归档详情和创建页按原型隐藏底部导航，主页/任务/设置显示三个固定入口。完整真机 UI suite 为 12 项通过、1 项合成媒体用例跳过、0 失败，另有 1 项补充冲突 UI 通过；真机截图已逐页检查，密码自动解压、结果关闭、目录选择取消、两步创建、英文深色、最大字号与系统 Files 导入均取得实际证据。

这不是逐像素一致性断言。字体由 SwiftUI 原生排版，图标采用 SF Symbols；状态栏、安全区、系统文件/照片选择、分享面板和 sheet 外框由 iOS 绘制。真机截图左上方的屏幕会话指示来自系统。真实文件名、大小、时间、项目数与原型演示值不同。原型固定窗口尺寸，原生界面随设备和 Dynamic Type 调整；长归档标题时动作移到下一行，最大字号时布局纵向扩展。这些差异在对照页可直接查看。

## 页面与交互对照

| 页面 | 原型结构 | 新工程与验收重点 | 证据 |
|---|---|---|---|
| 首页 | 标题、蓝紫渐变卡、两个快捷操作、最近文件、四个位置入口 | 同结构；真实导入后显示最近文件；空库有明确入口；位置使用系统授权 | `simulator/home-zh.png`、`prototype/home-phone.png` |
| 归档详情 | 摘要卡、三项统计、解压/选择、搜索、五类筛选、归档目录 | 同结构；收藏与选择独立；目录点击进入、文件点击预览；选中后出现底部解压按钮 | `simulator/archive-detail.png`、`prototype/archive-phone.png` |
| 创建第一步 | 返回、已选数量、文件列表、继续设置 | 多选；新增真实 Files/照片入口；返回此步保持选择；未选内容时禁用继续 | `simulator/create-select.png`、`media/photos-video-imported.png` |
| 创建第二步 | 名称、位置、格式、级别、密码、目录结构、创建按钮 | 使用自定义分段控件和小开关复现原型；ZIP 可用 AES；7z 不显示不支持的密码能力；保留原有分卷选项 | `simulator/create-settings.png`、`prototype/create-settings-phone.png` |
| 解压位置 | 四个位置、目录结构、冲突策略、开始按钮 | 实际读取设置；取消系统目录选择保留原位置，避免界面显示 iCloud 而实际仍写到本机 | `system/extraction-default-settings.png` |
| 密码 | 明确提示、输入与继续 | 缺少/错误密码分别提示；输入后原任务自动继续；不重复创建记录、不再要求点解压 | `simulator/wrong-password.png` |
| 结果 | 成功、位置、打开、分享、完成 | “完成”明确关闭；打开实际输出目录；分享完整分卷；外部授权保持至分享结束 | `simulator/extraction-result.png`、`simulator/output-folder.png` |
| 任务 | 进行中/已完成/失败/全部、卡片、进度、暂停/取消/重试 | 使用真实状态和进度；引擎验证暂停、取消和冲突控制；已完成可重新打开结果 | XCTest 日志与引擎测试；`device-conflict/tasks-completed.png`、`tasks-cancelled.png`、`conflict-apply-to-all.png` |
| 设置 | 文件处理、隐私与安全、外观、版本说明 | 三组结构对应原型；默认位置、目录选项、深色、清记录实际生效；增加开源许可入口 | `simulator/settings-zh.png`、`prototype/settings-phone.png` |
| 收藏与部分提取 | 收藏入口、目录/文件勾选 | 只提取选中目录及后代，不包含未选根文件；收藏可从首页位置进入 | `providers/` 与最终模拟器附件 |

## 视觉规格

浅色背景 `#f3f5fa`、纸面 `#ffffff`、主文字 `#171c2e`、次文字 `#8990a3`、分隔线 `#edf0f5`、主色 `#5669ee`、浅蓝 `#eef0ff`、成功绿 `#19896b`。渐变颜色为 `#596cf1 → #737ef4 → #8a90f4`。内容水平边距 20 pt，普通卡片圆角 16–20 pt，首页渐变卡片 22 pt，主按钮 14 pt。颜色由统一 DesignSystem 管理。

自定义分段选择和开关避免新版 iOS 默认玻璃胶囊改变原型观感。图标保留原型线性风格与文件类型配色，使用系统可用符号，不引入外部图片授权依赖。

## 可用性与国际化

- 中文和英文界面均测试，用户文件名不翻译。日期、字节单位按系统格式显示。
- 英文冲突选项修正为 Ask each time、Keep both、Skip、Replace，避免显示内部枚举键；补充 UI 回归验证按钮与实际重名行为。
- 字体随 Dynamic Type 缩放。大字时页头操作移到下一行，快捷操作与位置入口改为单列；设置标题和说明可换行。
- 主要交互提供 accessibility label/value 和稳定测试 ID；密码使用 SecureField，展示错误后可重试。
- 点击图标与开关留出 44 pt 容器。常规字体下维持原型的视觉尺寸；归档筛选、密集文件列表和最大字号仍需后续真人 VoiceOver/触控复核，自动测试不等同于无障碍全面认证。
- 用户选中照片或视频后才读取文件，不要求相册全量权限。原型的模拟导入弹层在产品中替换成原生系统选择器。
- iPad 内容宽度限制为 700 pt 并居中，不放大字号；两步创建和深色外观流程通过。

## 尚未完成的验收

Face ID 本人验证与失败回退、真实 iCloud/第三方提供者下载写入、真人 VoiceOver，以及长任务暂停/恢复触控仍未取得完整真机证据。合成照片/视频只在专用模拟器验收。完整结果与真机认证连接方法见 [最终验收报告](07-新工程最终验收报告.md)。