# ZipHarbor iPhone 14 真机验收报告

日期：2026-10-01。工程：`ZipHarbor/ZipHarbor.xcodeproj`，scheme：`ZipHarbor`，Bundle ID：`com.xiaolongxu.zipharbor.app`。

## 验收结论

本轮在 iPhone 14 真机上完成了新 App Icon 构建后的核心功能和用户界面验收。核心引擎、任务、格式、安全与性能测试 **21/21 通过**；完整真机 UI suite **14 项中 13 项通过、1 项按设计跳过、0 项失败**；系统 Files 导入又以独立用例 **1/1 通过**。本轮没有发现需要修改产品代码的真机回归问题。

照片/视频导入用例只在专用模拟器中使用合成 PNG 和 2 秒 MP4 完成验证，真机用例明确跳过，避免读取用户私人媒体。因此不能把真机结果表述为照片/视频 14/14 全部通过。Face ID、真人 VoiceOver、真实 iCloud/第三方云盘端到端行为，以及 Release 构建前台 UI 截图仍属于人工验收边界。

## 测试环境

| 项目 | 值 |
| --- | --- |
| 设备 | iPhone 14 |
| iOS | 27.0，Build 24A437 |
| UDID | `IPHONE14_UDID` |
| 架构 | arm64 |
| Bundle ID | `com.xiaolongxu.zipharbor.app` |
| 自动化构建 | Debug，Xcode XCTest，Swift 6 |
| 新图标 | 已包含在本轮真机 Debug 构建并随应用安装 |

## 结果统计

| 类别 | 结果 | 证据 |
| --- | --- | --- |
| 核心引擎、单元、集成、性能 | 21/21 通过，0 失败，0 跳过 | [`results/engine.xcresult`](iphone14-acceptance-20261001/results/engine.xcresult)、[`engine.log`](iphone14-acceptance-20261001/engine.log) |
| 真机 UI suite | 13 通过、1 跳过、0 失败 | [`ui-final2-summary.json`](iphone14-acceptance-20261001/ui-final2-summary.json)、[`ui-final2-tests.json`](iphone14-acceptance-20261001/ui-final2-tests.json) |
| 系统 Files 导入独立复测 | 1/1 通过 | [`results/files-import-back.xcresult`](iphone14-acceptance-20261001/results/files-import-back.xcresult)、[`files-import-back.log`](iphone14-acceptance-20261001/files-import-back.log) |
| 真机关键界面截图 | 已导出 | [`screenshots/final-named/`](iphone14-acceptance-20261001/screenshots/final-named/) |
| 源码与验收构建一致性 | 当前源码哈希无不匹配 | [`source-sha256.json`](migration-evidence/source-sha256.json) |

## 核心功能覆盖

真机核心测试覆盖以下范围：

- ZIP、ZIP AES、7z 的创建/往返解压，以及 TAR、tar.gz、tar.bz2、gzip、bzip2、RAR5 的读取。
- 中文文件名、空目录、目录层级、选中目录及后代解压、同名去重。
- 缺少密码、错误密码、正确密码后继续原任务，且不会重复创建历史记录。
- 混合普通/加密 ZIP：密码错误时不发布任何输出，密码正确后普通条目与加密条目均可继续解压。
- 分卷 ZIP 重组、缺卷错误、路径穿越拦截、已有符号链接逃逸拦截。
- 冲突询问、取消、重试、跳过、替换、保留两者及“应用到全部”。
- 任务暂停/恢复、启动前取消、写入中取消、临时文件清理、任务重启状态。
- 清理记录、30 天保留策略、收藏与文件不被错误删除。
- 性能和内存采样：1 GiB ZIP 往返约 4.69 秒，2,000 个小文件约 3.22 秒；物理内存基线约 72 MiB，采样峰值约 90 MiB。

性能样本为本轮 iPhone 14 Debug XCTest 的重复模式高可压缩数据，不代表视频、随机数据或远程云盘的速度。内存值来自任务进度中的 `phys_footprint` 采样，包含测试宿主开销，不等同于 Instruments 连续追踪峰值。

## 真机 UI 用例

| 用例 | 结果 | 验证内容 |
| --- | --- | --- |
| `testAccessibilityLargeTextLayout` | 通过 | 最大 Dynamic Type 下首页与设置页不截断，快捷入口可操作 |
| `testCancellingExternalFolderChoiceKeepsPreviousDestination` | 通过 | 取消外部目录选择后仍保留原目标 |
| `testCreateTwoStepsAESRoundTripAndBackPreservesSelection` | 通过 | 两步 AES 创建、返回保留选择、再打开并解压 |
| `testDefaultDestinationAndPreserveSettingsAffectExtraction` | 通过 | 默认目标和保留设置实际影响解压行为 |
| `testEnglishAndDarkAppearance` | 通过 | 英文国际化与深色模式 |
| `testFavoritesAndSelectedDirectoryExtraction` | 通过 | 收藏与选中目录解压 |
| `testPasswordAutomaticallyContinuesAndDoneDismisses` | 通过 | 输入密码后自动继续，结果弹窗“完成”可关闭 |
| `testPasswordCancelAndClearHistoryKeepFiles` | 通过 | 密码取消、清记录不误删文件 |
| `testPhotosAndVideoImportThenCreateArchive` | 按设计跳过 | 仅在专用模拟器使用合成媒体；真机不读取私人媒体 |
| `testRepeatedExtractionConflictCancelRetryAndKeepBoth` | 通过 | 重名询问、取消、失败筛选重试、应用到全部、保留两者 |
| `testSelectedFolderExtractionAndPreview` | 通过 | 目录选择、解压目标与 Quick Look 预览 |
| `testSystemFilesImportsRealArchive` | 通过 | 从系统 Files 选择真实归档并进入归档详情 |
| `testSystemPickerAndSharePresentation` | 通过 | 系统文件选择器与分享面板呈现 |
| `testWrongPasswordCanRetryWithoutRestartingExtraction` | 通过 | 错误密码后无需重启任务即可重试 |

## 系统 Files 路径问题与复测

首次真机 UI 运行时，系统 Files 的 `Downloads` 默认指向 iCloud Drive，而 QA 文件实际位于应用本地容器 `Documents/Downloads/Provider QA.zip`。这造成测试找不到文件，属于测试导航假设错误，不是归档读取或产品导入逻辑错误。

复测时，测试在 Files 顶部返回后进入 `在我的 iPhone → ZipHarbor → Downloads`，找到 `Provider QA.zip` 并成功返回 ZipHarbor 归档详情页。最终完整 UI suite 和独立 Files 用例均通过；诊断期间产生的失败截图与日志保留在 [`files-import-diagnostic/`](iphone14-acceptance-20261001/screenshots/files-import-diagnostic/) 供追溯。

## 视觉与交互抽查

已查看以下真机截图，确认页面可读、主要控件可操作、弹层状态与原型交互一致：

- 中文首页、英文深色首页。
- 密码解压结果页，以及“完成”关闭结果弹窗。
- 系统 Files 导入后的归档详情页。
- 重名冲突处理中的“应用到全部”与保留两者输出。
- 设置页大字体布局。

最终截图索引见 [`final-named-screenshots.json`](iphone14-acceptance-20261001/final-named-screenshots.json)。本轮使用 Debug XCTest 截图完成真机 UI 验收；Release 构建已签名、安装并启动验证，但没有取得可用的 Release 前台截图，不将其作为 Release 视觉验收证据。

## 已确认的边界

- 真机照片/视频选择未执行，合成媒体流程已在专用模拟器完成。
- 系统分享只验证系统面板呈现，不向联系人、邮件或第三方服务实际发送文件。
- 真实 iCloud 或第三方文件提供者的联网下载、延迟和写入由系统提供者负责，本轮没有真实云盘端到端证据。
- Face ID 的成功、失败、取消及设备密码回退未由本人进行人工验收。
- 真人 VoiceOver 逐屏朗读和长任务暂停/恢复的真机触控仍需人工验收。
- 密码不持久化；应用被系统终止后任务从头重试，不提供跨进程 checkpoint。

## 证据目录

- 核心测试结果：[`results/engine.xcresult`](iphone14-acceptance-20261001/results/engine.xcresult)
- 核心测试日志：[`engine.log`](iphone14-acceptance-20261001/engine.log)
- 最终 UI 结果：[`results/ui-final2.xcresult`](iphone14-acceptance-20261001/results/ui-final2.xcresult)
- UI 摘要与测试列表：[`ui-final2-summary.json`](iphone14-acceptance-20261001/ui-final2-summary.json)、[`ui-final2-tests.json`](iphone14-acceptance-20261001/ui-final2-tests.json)
- Files 独立通过结果：[`results/files-import-back.xcresult`](iphone14-acceptance-20261001/results/files-import-back.xcresult)
- 真机关键截图：[`screenshots/final-named/`](iphone14-acceptance-20261001/screenshots/final-named/)
- 真机测试归档副本：[`device-copy/Provider-QA.zip`](iphone14-acceptance-20261001/device-copy/Provider-QA.zip)

## 复现命令

从工程根目录执行：

```sh
xcodebuild -project ZipHarbor/ZipHarbor.xcodeproj -scheme ZipHarbor \
  -destination 'platform=iOS,id=IPHONE14_UDID' \
  -derivedDataPath /tmp/ZipHarbor-Device -allowProvisioningUpdates \
  -parallel-testing-enabled NO test -only-testing:ZipHarborTests

xcodebuild -project ZipHarbor/ZipHarbor.xcodeproj -scheme ZipHarbor \
  -destination 'platform=iOS,id=IPHONE14_UDID' \
  -derivedDataPath /tmp/ZipHarbor-Device -allowProvisioningUpdates \
  -parallel-testing-enabled NO test -only-testing:ZipHarborUITests
```

UI 测试使用 Debug QA fixture 初始化入口；在包含真实资料的设备上运行前，应使用专门验收设备或清晰隔离的测试资料。