ZipHarbor
本页目录

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

新工程迁移说明（2026-10-01）：本文记录旧版设计或旧工程历史状态。当前实现以 ZipHarbor/ZipHarbor.xcodeproj 为准，参见 迁移映射、新架构 和 最终验收报告。

ZipHarbor 功能对齐与验收报告

验收日期：2026-09-30
工程目录：app/
Bundle ID：com.xiaolongxu.zipharbor
原型基线：app-prototype.html

1. 结论

原生 App 已完成一次 UI/UX 重构，核心结构已经按 HTML 原型对齐。当前页面不再使用旧版系统 TabView、系统大标题、List/Form 组合，而是采用原型中的自定义顶栏、渐变欢迎卡、双列快捷操作、圆角内容区和胶囊底部导航。

这不是逐像素复制：原型使用演示数据和网页图标，原生 App 使用真实 Files/Photos 入口、SwiftUI 原生控件和动态数据。核心信息层级、主操作入口、页面导航和任务筛选逻辑已对齐，具体字体渲染、系统弹窗和文件选择器仍由 iOS 决定。

2. UI/UX 对齐

原型区域 原生实现 结果
首页顶栏：Files、最近文件数、搜索、更多 FilesHomeView.homeHeader 已对齐
渐变欢迎卡：本地处理、隐私说明、打开压缩包 FilesHomeView.welcomeCard 已对齐
双列快捷操作：打开/解压、创建压缩包 ActionTile 已对齐
最近归档列表、收藏筛选、空状态 ArchiveRow、ContentUnavailableView 已对齐并接入真实 SwiftData
底部 Files / Tasks / Settings 胶囊导航 ZipHarborBottomBar 已对齐，支持无障碍标识
任务页筛选胶囊、任务卡片、空状态 TaskCenterView 已对齐
设置页分组、隐私与外观开关 SettingsView 已对齐
创建页分步信息层级、格式/压缩级别/密码/分卷 CreateArchiveView 已对齐；7z 密码创建显示边界提示
归档详情页搜索、类型筛选、选择和解压设置 ArchiveDetailView 已对齐

视觉验收截图：iphone14-home-final.png；真机深色模式截图：iphone14-real-home-final.png

3. 已实现功能

功能域 当前结果 代码/页面
文件导入 Files 文件选择器、分享面板 URL、照片/视频选择器；导入后复制到 App 本地 Archives AppModel.importArchives、Files 首页
归档识别 ZIP、7z、RAR、TAR、GZIP、BZIP2、ZIPX 常见读取；复合扩展名识别和目录安全校验 LibArchiveEngine.inspect
目录查看 搜索、全选、清除、目录选择、加密标记、收藏 ArchiveDetailView
解压 流式读取、选择性解压、保留目录、冲突策略、原子临时文件、进度、路径穿越阻断 LibArchiveEngine.extract
创建 多文件/文件夹、ZIP、普通 7z、压缩级别、照片/视频 LibArchiveEngine.create、CreateArchiveView
加密 ZIP AES-256 创建和解压；7z 密码创建明确拒绝并引导使用 ZIP；加密 RAR 明确提示不支持 ArchiveFailure.encryptionUnsupported、创建页密码提示
ZIP 分卷 .zip.001 卷组导入/重组；创建端 64/128/256/512 MB 切片；完成页分享全部分卷 prepareArchiveURL、splitFile
任务和隐私 SwiftData 任务历史、进度、失败状态；本地处理；Face ID/设备密码应用锁；深色模式 JobRecord、ZipHarborApp、设置页

4. 模拟器验证

已通过

国际化验收

环境提示

测试日志出现 iOS 26.5 Simulator 的 UIAccessibilityLoaderWebShared 重复实现警告，但本次 UI 测试仍完成并通过；该警告来自系统运行时，不是 ZipHarbor 代码。

该模拟器的 simctl 截图以 iOS 26 的窗口化方式呈现，上下会出现黑色窗口留白；真机截图为完整设备画布，页面内容和安全区正常。

5. iPhone 14 真机验收

设备：iPhone 14，UDID IPHONE14_UDID，iOS 27.0。

密码解压问题修复

此前 libarchive 在真正读取加密 ZIP 文件内容时返回 Passphrase required for this entry，应用将其误判为损坏压缩包并直接显示错误。当前已统一映射为需要密码/密码错误状态，解压会重新打开密码输入弹窗；修复后的模拟器单测 8/8、UI 测试 1/1 通过，结果包：

本轮交互修复：从解压动作触发密码输入时，输入正确密码后会自动继续当前解压任务，不再要求再次点击“解压到…”；解压完成页的“完成”按钮现在会关闭结果弹窗。修复后模拟器全量测试 8/8 单测、1/1 UI 测试通过，真机修复版已重新安装，并通过 devicectl device process launch --console 验证应用进程可正常启动。

真机补充：最终包安装后，iPhone 14 可能显示 iOS 的“无法验证 App”开发者信任提示，需要设备联网完成开发证书验证；该提示属于手工签名测试环境限制，应用进程本身已成功启动。

结果包：

6. 已知边界

  1. 当前使用的 libarchive.xcframework 7z 写入器不提供 7z AES 创建能力；应用已在逻辑层和 UI 层明确禁止该组合，ZIP AES 仍可用。
  2. ZIP 分卷使用 ZipHarbor 的 .zip.001 原始切片卷组，ZipHarbor 内可导入和解压，其他工具是否识别取决于其卷格式支持。
  3. 暂停后检查点恢复、本地通知、Shortcuts、回收站、云端 File Provider 下载等待、逐文件冲突询问、空间预检和完整校验仍需后续补齐。
  4. RAR 以读取为主，加密 RAR 明确提示不支持；发布前仍需使用真实 RAR4/RAR5 样本做跨工具兼容性验证。

7. 发布前动作

下载 Markdown 文档