> 新工程迁移说明（2026-10-01）：本文记录旧版设计或旧工程历史状态。当前实现以 `ZipHarbor/ZipHarbor.xcodeproj` 为准，参见 [迁移映射](05-新工程迁移与功能映射.md)、[新架构](06-新工程技术架构.md) 和 [最终验收报告](07-新工程最终验收报告.md)。

# ZipHarbor 功能对齐与验收报告

**验收日期**：2026-09-30  
**工程目录**：`app/`  
**Bundle ID**：`com.xiaolongxu.zipharbor`  
**原型基线**：[app-prototype.html](./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-home-final.png)；真机深色模式截图：[iphone14-real-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. 模拟器验证

### 已通过

- 构建：`xcodebuild build`，iPhone 14 Simulator，成功。
- 单元测试：`ZipHarborTests` **8/8 通过**。
  - 路径穿越和绝对路径阻断
  - ZIP 创建/识别/解压往返
  - ZIP AES 往返
  - ZIP AES 无密码解压时进入需要密码状态
  - 普通 7z 创建/识别/解压往返
  - 7z 密码创建边界拒绝
  - ZIP 分卷重组/解压
  - 复合扩展名格式识别
- UI 测试：`ZipHarborUITests` **1/1 通过**，覆盖首页、创建页、返回、任务页和设置页导航。
- 安装启动：`simctl install` 和 `simctl launch` 在 iPhone 14 Simulator 成功。
- 结果包：
  - 单测：`/tmp/ZipHarbor-sim-unit-release-final-1790772304.xcresult`
  - UI 测试：`/tmp/ZipHarbor-sim-ui-release-final-1790772331.xcresult`

### 国际化验收

- 支持语言：英文（`en`）和简体中文（`zh-Hans`）。
- 本地化资源：`app/Resources/en.lproj`、`app/Resources/zh-Hans.lproj`，包含 `Localizable.strings` 和 Face ID 权限用 `InfoPlist.strings`。
- 工程资源已通过 `project.yml` 的 `sources.buildPhase: resources` 加入 Copy Bundle Resources，构建产物实际包含两个 `.lproj` 目录。
- 首页、创建页、任务页、设置页、详情页、错误提示、数量格式和系统 Face ID 权限说明均已覆盖；格式名、文件大小、日期等使用系统 locale 格式化。
- 在简体中文 iPhone 14 Simulator 上完成安装、启动和首页截图验收：[iphone14-zh-i18n.png](./iphone14-zh-i18n.png)。
- 简体中文环境全量测试：7/7 单测、1/1 UI 测试通过，结果包：`/tmp/ZipHarbor-i18n-zh-current/Logs/Test/Test-ZipHarbor-2026.09.30_21-29-44-+0800.xcresult`。
- 英文环境全量测试：7/7 单测、1/1 UI 测试通过，结果包：`/tmp/ZipHarbor-i18n-current/Logs/Test/Test-ZipHarbor-2026.09.30_21-28-57-+0800.xcresult`。

### 环境提示

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

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

## 5. iPhone 14 真机验收

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

- 真机单元测试：`ZipHarborTests` **7/7 通过**，包含 ZIP、ZIP AES、普通 7z、ZIP 分卷、路径安全和 7z 密码边界。
- 真机安装和冷启动：已使用当前含国际化资源的真机包，通过 `devicectl device install app`、`process launch` 重新安装并启动；已保存 [iphone14-real-i18n-reinstalled.png](./iphone14-real-i18n-reinstalled.png)。截图确认真机运行时为简体中文，深色模式下页面和快捷操作卡片文本对比度正常。
- 真机 UI Test：测试 runner 在开启自动化模式时超时，报 `Timed out while enabling automation mode`；未形成页面断言结果，这一项标记为环境阻断。

### 密码解压问题修复

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

- 单测：`/tmp/ZipHarbor-password-fix-sim2/Logs/Test/Test-ZipHarbor-2026.09.30_22-14-43-+0800.xcresult`
- UI 测试：`/tmp/ZipHarbor-password-fix-full/Logs/Test/Test-ZipHarbor-2026.09.30_22-15-16-+0800.xcresult`
- 修复版真机截图：[iphone14-real-password-fix.png](./iphone14-real-password-fix.png)

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

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

结果包：

- 单测：`/tmp/ZipHarbor-real-unit-release-final-1790772379.xcresult`
- UI Test：`/tmp/ZipHarbor-real-ui-final-1790771593.xcresult`

## 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. 发布前动作

- 在真机 UI 自动化环境稳定后补跑页面断言；当前已完成真机安装、启动和核心归档单测。
- 使用真实 ZIP AES、RAR4/RAR5、7z 样本和 ZIP 分卷 fixture 做跨工具兼容测试。
- 完成空间检查、特殊文件拒绝、完整校验、暂停/恢复和通知后再提交 App Store。