产品文档 / 历史记录与验收范围以文中日期为准

ZipHarbor 新工程最终验收报告

日期：2026-10-01。交付入口：ZipHarbor/ZipHarbor.xcodeproj，scheme ZipHarbor，独立 Bundle ID com.xiaolongxu.zipharbor.app。旧 app/ 工程、旧应用及其数据保留；新工程不读取旧数据库。

交付与结论

迁移实现已完成，功能映射与技术架构分别见 05、06。界面按 HTML 原型重建，对照结果见 08 和 截图对照页。

新工程完成模拟器与 iPhone 14 真机核心、UI 工作流验收。真机最新 21 项单元/集成/性能测试全部通过；最终 UI suite 为 13 项通过、1 项媒体用例按设计跳过、0 失败；其中包含冲突处理工作流，系统 Files 导入另有独立 1/1 复测通过。最新版 Release 已签名构建、校验并安装。真实云盘、本人 Face ID 与真人 VoiceOver 的人工验收仍单独列为未验证范围，不据此宣称所有环境与无障碍场景均已通过。完整本轮真机结果见 iPhone 14 真机验收。

环境与实际结果

历史 UI runner 初始化失败为 com.apple.LocalAuthentication Code=-1，底层 com.apple.sharing.authentication Code=12 / Timed out waiting for response。用户解锁后 passcodeRequired: false，CLI 与 Xcode 菜单启动仍曾认证超时，因此不能把历史错误仅归因于锁屏。退出 iPhone 镜像、通过 Apple Device Hub 建立真机屏幕连接后，runner 正常初始化，完整 suite 执行通过。未关闭设备密码、开发安全检查或修改配对凭据。复现遇到相同错误时先确认解锁并使用 Device Hub 的 View Screen 建立屏幕会话。

自动化验收使用 Debug 构建；发布构建不包含 QA 初始化入口。最后的 Release 安装与进程启动命令成功，但屏幕捕获返回全黑，重新连接后 Device Hub 显示锁屏，因此该图保留为 device/release-screen-unavailable.png，不作为 Release UI 通过证明。界面结论依据实际执行的真机 XCTest 截图。

验证范围

引擎、任务与完整性

测试覆盖 ZIP、AES ZIP、7z 往返；独立 TAR、tar.gz、tar.bz2、原始 gzip/bzip2、RAR5 读取；中文文件名、空目录、目录展开和同名去重；选中目录及后代解压；缺少/错误密码；分卷重组和缺卷；全部冲突策略及询问选择；穿越路径、已有符号链接逃逸；暂停/恢复、启动前取消及写入中取消；清记录/30 天保留不删除文件与收藏；进程重启后任务标为中断；密码续接不重复创建历史记录；偏好与路径持久化。

新增混合普通/加密 ZIP 测试验证：缺少或错误密码时输出目录保持为空；正确密码后两个条目可直接解压，不因为之前已写文件再次询问重名。

单元测试验证真实 libarchive、真实文件与输出内容，UI 测试验证用户入口和结果。两种证据不能互相替代。引擎暂停/恢复与写入中取消已验证；长任务运行时的真机暂停/恢复触控仍无专门 UI 用例。

UI 工作流

最终模拟器 suite 包含 13 项：中英文/深色、大字体、两步 AES 创建往返并保留返回选择、密码自动继续与“完成”关闭、错误密码重试、密码取消与清记录保留文件、目录浏览与 Quick Look、系统 Files/分享面板、默认目标和目录开关实际生效、收藏和选中目录解压、实际 Files 导入、合成照片/视频导入并打包、取消外部目录选择保持原目标。

追加的第 14 项 UI 用例验证重复解压出现真实重名询问、取消后在失败筛选中重试、开启“应用到全部冲突”后保留两者、输出中同时存在原文件及 课堂笔记 (2).txt。该用例在真机与模拟器均通过。

照片/视频用例使用专用模拟器中生成的纯色 PNG 和 2 秒 MP4，真机运行此用例时明确跳过，不自动选取用户私人照片。系统分享只验证面板，不向联系人、邮件或第三方服务实际发送文件。

性能与内存

计时覆盖创建、解压和大文件输出校验；不包括生成输入样本。1 GiB 输入为重复模式的高可压缩内容，不能将此速度推广到视频、随机数据或远程 iCloud 文件。内存是进度回调中 task_vm_info.phys_footprint 的采样最大值，包含测试宿主开销，不等同于 Instruments 连续追踪的绝对峰值。测试限制 ZIP 处理峰值相对基线增量小于 128 MiB。

本次验收发现并修复的问题

1. 真机 /var 与 Foundation 解析后的 /private/var 不一致，导致合法解压路径被误判为不安全。已按 iOS 路径别名归一化，同时保留真实符号链接解析与逃逸测试。
2. 大文件循环中的 Foundation 临时对象累积，早期物理内存采样超过 1 GiB。读写与分卷循环加入每块 autoreleasepool，最新真机采样峰值 88 MiB，SHA256 不变。
3. 系统文件/照片面板尚未完成呈现时，测试误操作底层页面。改为等待真实系统控件；照片选择器新版按钮的 accessibility ID 为 Add、可见标签为 Done，按实际 ID 操作。
4. 设置弹层存在两个“完成”，测试定位不明确。为保存按钮增加独立 ID，并验证设置影响实际解压。
5. 外部目录选择取消后界面目标已切换但引用未变。只在成功选择时提交新目标，取消保持原位置；用例验证通过。
6. 外部分享/预览可能在任务授权结束后读取失败。预览与分享分别持有授权至呈现结束，父级位置保留原书签授权根。
7. 超大字体页头被截断。改为可换行布局和垂直操作区，快捷入口在无障碍字号下使用单列。
8. 英文重名处理选项显示了 ask、keepBoth 等内部枚举键。修正为 Ask each time、Keep both、Skip、Replace，并增加重复解压、取消、重试与保留两者的界面回归。

格式与运行边界

• 可创建 ZIP 与未加密 7z；密码创建使用 ZIP AES。加密 7z 创建和加密 RAR 解压明确不支持。
• 分卷支持 .zip.001 原始切片/拼接；不承诺所有传统 split ZIP、多卷 RAR 和损坏修复格式。
• 密码不持久化，应用退出后需重新输入。任务在应用运行期间可暂停，系统终止后从头重试，未提供跨进程 checkpoint。
• 解压取消/读取损坏文件时保留已经完整发布的条目，清理当前 partial 文件；不承诺整个任务回滚所有已完成输出。
• iCloud 和第三方提供者使用系统 Files 权限，联网下载与写入由提供者负责，尚无真实云盘端到端验收证据。
• Face ID/设备密码集成已实现，但本人识别、取消、失败回退及真人 VoiceOver 仍未完成真机验收。

最终结果索引

• iPhone 14 模拟器：results/simulator-final.xcresult，34/34 通过，0 失败、0 跳过。统计为 simulator-test-summary.json，列表为 simulator-tests.json。
• 全量通过后的局部调整另有 results/visual-final.xcresult（3/3）及 results/selection-final.xcresult（23/23），分别验证普通/大字间距、密码续接、选中目录和全部引擎用例。只选择混合 ZIP 中未加密条目时不索要密码。截图以这些最新复测为准。
• iPad 模拟器：results/ipad-final.xcresult，2/2 通过；统计为 ipad-test-summary.json。
• iPhone 14 真机：本轮最新核心结果见 iphone14-acceptance-20261001/results/engine.xcresult，21/21 通过；最新 UI 结果见 iphone14-acceptance-20261001/results/ui-final2.xcresult，13 项通过、1 项跳过、0 失败。摘要及列表为 ui-final2-summary.json、ui-final2-tests.json。此前 migration-evidence/device-final-ui-* 的 12 项结果保留作历史证据，不作为本轮最终统计。
• 补充冲突回归：results/iPhone14-conflict-final.xcresult 与 results/conflict-simulator-final.xcresult，各 1/1 通过；摘要为 device-conflict-summary.json、conflict-simulator-summary.json，真机截图与原始附件 manifest 在 device-conflict/。前两次补充脚本存在 Cancel 同名选择与 native Toggle 点击区域问题，已按弹层 ID 和实际开关区域修正，先断言开关值再验证输出；这些脚本定位失败不计作业务通过。
• 历史 20 项引擎结果与 UI runner 阻塞记录保留。device-latest-blocked.log 和 device-unlocked-auth-blocked.log 是修复连接前的历史，不能当作当前结果。

证据与复现

migration-evidence/ 保存结果摘要、测试列表、截图、来源 manifest 与通过的 xcresult。原型截图在 prototype/，模拟器在 simulator/，iPhone 14 真机在 device/，iPad 在 ipad/，系统选择分享在 system/，媒体在 media/。真机截图包含系统屏幕会话指示标志，这是 iOS 状态栏内容。临时 /tmp 结果不作为唯一交付证据。

从工程根目录运行，目标 ID 可通过 xcrun simctl list devices 或 xcrun devicectl list devices 获取。专用模拟器需先使用 simctl addmedia 加入两份合成测试媒体，媒体用例验证实际导入。

xcodebuild -project ZipHarbor/ZipHarbor.xcodeproj -scheme ZipHarbor \
  -destination 'platform=iOS Simulator,id=1AD6D2D0-A263-4965-9686-A1D292533A48' \
  -derivedDataPath /tmp/ZipHarbor-Migration \
  -parallel-testing-enabled NO test

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

xcodebuild -project ZipHarbor/ZipHarbor.xcodeproj -scheme ZipHarbor \
  -configuration Release -destination 'generic/platform=iOS' \
  -allowProvisioningUpdates build

Debug UI tests 显式使用 --qa-fixtures --qa-reset，只重置新应用测试库/记录与 Downloads；旧 app 不受影响。发布构建不包含该入口。使用有真实资料的新应用运行这些测试前，应改用专门验收设备/数据，避免测试重置资料。

人工验收边界

核心引擎与上述用户工作流已经在真机实际执行。真实 iCloud/第三方文件提供者下载写入、本人 Face ID 成功/失败/取消与设备密码回退、真人 VoiceOver，以及长任务暂停/恢复的真机触控仍需对应环境和本人参与。照片/视频只对专用模拟器中的合成媒体完成验收。

下载 Markdown 文档