ZipHarbor产品文档 / 历史记录与验收范围以文中日期为准
ZipHarbor 新工程迁移与功能映射
迁移日期：2026-10-01。开发入口为 ZipHarbor/ZipHarbor.xcodeproj，scheme 为 ZipHarbor。旧 app/ 保留作迁移来源。应用标识为 com.xiaolongxu.zipharbor.app，与旧应用独立，不迁移旧数据库。
工程与产品边界
iOS/iPadOS 17+，Swift 6，SwiftUI，SwiftData 本地存储。保留用户初始化的原生 Xcode 工程、同步文件夹与三个 targets；移除模板 Core Data、CloudKit、推送和多平台配置。iCloud Drive 由用户通过系统 Files 授权访问，不代表使用 CloudKit。ArchiveKit 1.0.0 精确锁定；本地打包完整依赖许可，设置页可查看。
本次实现旧版真实能力及 HTML 原型的实际交互。不包含账号、广告、云端解压、完整文件管理器、回收站、快捷指令、跨进程断点续传或加密 7z 创建。加密 RAR 保持明确不支持。分卷指 .zip.001 原始切片方式，不承诺传统 split ZIP/多卷 RAR 的全面兼容。
功能映射
| 来源能力 | 新工程实现 | 关键行为 |
|---|---|---|
| Files / URL 导入 | FileAccess、AppSession | 安全访问授权、协调读取、复制到独立目录；外部打开后进入详情 |
| 照片及视频 | CreateView、PickedMedia | 系统 PhotosPicker，仅处理选中内容，FileRepresentation 避免把视频整体加载到内存 |
| 多格式归档浏览 | LibArchiveEngine、ArchiveViewModel | ZIP/7z/RAR/TAR/GZIP/BZIP2；复合扩展名、目录导航、类型筛选、搜索 |
| 文件与目录选择 | ArchiveViewModel | 选择和打开分为独立点击区域；目录包含后代 |
| 全部 / 部分解压 | TaskCoordinator、LibArchiveEngine | 目标目录、层级保留/展开、输出文件夹、真实进度 |
| 重名处理 | ArchiveOperationControl、ConflictView | 询问/保留两份/跳过/替换；可应用到全部冲突 |
| ZIP / 7z 创建 | CreateViewModel、LibArchiveEngine | 两步创建；名称、目标目录、压缩级别、目录结构 |
| AES ZIP | 密码弹层及引擎 | 密码仅保存在内存；缺少密码/错误密码分别处理 |
| 密码后继续解压 | TaskCoordinator 原任务恢复 | 保留 JobSpec 与任务 ID，输入后直接继续，无需再点解压 |
| 分卷 | LibArchiveEngine、创建设置及系统分享 | 64/128/256/512 MB；流式分块、缺卷检查、全部分卷分享 |
| 收藏 / 最近文件 | LibraryItem、首页和收藏位置 | 本地持久化，原型最近文件列表与查看全部 |
| 任务历史 | JobRecord、TasksView | 筛选、重试、查看结果、打开文件夹、沿用最近设置 |
| 暂停 / 继续 / 取消 | 独立 operation control | 工作队列检查点；切换页面仍继续；取消清理临时文件 |
| 应用锁 | AppLockService | LocalAuthentication，Face ID 或设备密码；验证失败保持锁定 |
| 深色外观 | AppSettings、DesignSystem | 原型颜色 token、持久化开关 |
| 默认解压设置 | AppSettings、ExtractionSheet | 实际使用默认目标与目录结构；外部位置书签 |
| 清除记录 | TaskCoordinator | 只清除已结束任务；不删除文件、收藏及运行中任务 |
| 中英文 | Resources/en、zh-Hans | 界面、错误、系统权限提示；文件名保持原样 |
| Quick Look / 分享 | SystemBridges、FolderBrowser、ResultView | 只读预览、嵌套目录、原生分享面板 |
| 原型结果弹层 | ResultView | 真实文件位置与结果；“完成”明确关闭 |
文件位置与默认值
- 导入文件复制至 Documents/Library/随机目录，分卷保留在同一目录。
- 本机输出使用 Documents/Downloads，对系统 Files 开启文档共享。
- 默认解压位置为压缩包所在位置；打开目标弹层时读取真实设置。
- 每次解压生成按归档名称命名的结果目录，重名条目按所选策略处理。
- 本机路径以 Documents 相对路径保存，避免沙盒绝对路径变化导致文件失联。
- 外部位置使用书签，执行期间保持访问权限，失效时显示重新选择位置的错误。
- 串行任务队列；暂停当前任务保留执行位置并等待恢复。系统终止后的任务标为已中断，可以从头重试。
- 任务记录保留 30 天；过期和清除记录均不删除结果文件。
- 默认浅色，用户可开启深色并持久保存。
最终验证结果及已知边界见 07-新工程最终验收报告.md。