庭记 iCloud 同步指南
一、同步机制简介与核心概念辨析
1. 核心概念辨析：iCloud 双端同步 vs. 系统日历单向镜像
很多用户容易将「iCloud 数据同步」与「系统日历镜像」混淆。庭记在底层架构上严格区分了这两套独立的系统：
| 对比维度 | iCloud 双端同步（CloudKit） | 系统日历单向镜像（EventKit） |
|---|---|---|
| 数据流向 | 双向互通（iPhone ⟷ Mac） | 单向推送（庭记 → 苹果系统日历） |
| 底层技术 | Apple CloudKit 私有数据库（Private Database） | Apple EventKit 本地日历数据库 |
| 覆盖内容 | 案件排期、保全状态、多层文件夹结构与 PDF 卷宗正文 | 仅开庭与保全日程元数据（标题、时间、地点、备注） |
| 适用场景 | iPhone 外出办案拍照，Mac 桌面大屏阅卷，双端实时对齐 | 在 Apple Watch、CarPlay 车机或系统桌面日历中接收开庭提醒 |
| 存储位置 | 您个人的 iCloud 私有云空间，开发者服务器完全无权访问 | 系统日历专用的独立**「庭记」**分类下，不污染个人生活日程 |
| 权限与会员 | 高级会员专属功能，需登录同一 Apple ID 并开启 iCloud | 基础功能免费可用，需在设置中授予系统日历访问权限 |
2. iCloud 双端数据同步机制
庭记的多设备跨端流转建立在 Apple CloudKit 私有数据库（Private Database） 之上——所有数据直接存储在您个人的 iCloud 账号容器中，不经过任何第三方或开发者服务器，开发者无法访问您的任何数据。
日程与文档走两条相互独立的同步通道：
- 日程通道：结构化数据（案号、时间、地点、法官、提醒规则等）通过 CloudKit Record 传输。
- 即时更新导入与定时对账（Mac 1.0.21 新增）：Mac 窗口保持常开时，收到 iPhone 端发出的变更推送后约 1 秒内 即可自动完成本地数据导入并刷新视图，无需反复切换窗口，同时辅以 5 分钟定时自动对账兜底；
- 字段级增量保存保护：严格遵循增量保存机制，仅更新实际改动的字段，避免多设备同时编辑同一日程时相互覆盖；
- 提醒配置跨端兼容保护：Mac 端修改备注时自动识别并保护已有的提醒配置标记，不破坏移动端全天与傍晚提醒设置。
- 文档通道（PDF 卷宗）：采用分步传输策略：
- 元数据（文件名、文件夹归属、创建时间等）先行同步，另一端可立即看到文档条目；
- PDF 正文 Asset 单独在后台上传，另一端在轻点文档时按需下载，或在 Mac 端开启「自动同步文档」提前在后台预缓存；
- 防回流保护：替换共享 PDF 失败时，对账逻辑绝不用云端旧版覆盖本机新版，保障本地材料完整性。
二、开启同步必须满足的全部条件
以下任一条件不满足，同步均无法正常工作。排查同步异常前请逐项核对自检清单：
条件一：两端登录同一个 Apple ID
| 设备 | 检查路径 |
|---|---|
| iPhone / iPad | 系统设置 → 顶部头像 → 查看 Apple ID 账号邮箱 |
| Mac | 系统设置 → 左上角头像 → 查看 Apple ID 账号邮箱 |
两端必须显示完全相同的 Apple ID 邮箱。
条件二：系统 iCloud 云盘服务正常开启
- iPhone / iPad：系统设置 → [你的名字] → iCloud → 确认「iCloud 云盘（iCloud Drive）」处于已开启状态。
- Mac：系统设置 → [Apple ID] → iCloud → 确认「iCloud 云盘」已开启。
- 确认 iCloud 账号存储空间未满，且未处于欠费、停用或风控锁定状态。
条件三：庭记被允许使用 iCloud
- iPhone / iPad：系统设置 → [你的名字] → iCloud → 显示全部 App → 找到「庭记」→ 确认开关为开启。
- Mac：系统设置 → Apple ID → iCloud → 确认「庭记」的相关权限未被禁用。
条件四：账号拥有有效高级会员资格
- 庭记会员通过 Apple App Store 官方购买。购买后，凭证快照会自动写入 CloudKit 供 Mac 端读取验证。
- 在 App 内「设置 → 会员」中可随时查看当前会员状态；若已购买但未生效，请点击**「恢复购买」**。
条件五：两端 App 均已手动切换为云端同步
- iPhone / iPad：进入庭记「设置」→ 找到「启用 iCloud」开关并打开。
- Mac：进入庭记「设置」→「同步」→ 将「同步模式」从「仅本地」切换为「云端同步」。
⚠️ 重要提醒：必须两端均手动开启同步。若仅一端开启，另一端处于“仅本地”状态，数据不会跨端互通。
条件六：网络可正常访问 Apple CloudKit
- 正常 Wi-Fi 或蜂窝网络通常畅通无阻。
- 部分涉密单位专网、涉密网络或特定代理抓包工具可能会拦截 Apple CloudKit 的 HTTPS 域名。当设备处于完全离线状态时，数据会暂存在本地变更队列中，恢复网络后自动断点续传。
三、卷宗 Inspector 信息面板与本地存储释放（手机瘦身）
在 iPhone 或 iPad 的「文档」列表中，点击任意 PDF 右侧的 Inspector（信息面板），即可清晰掌控该文件的云端状态：
- 「已同步」：该文档的元数据与完整 PDF 正文均已加密备份至个人 iCloud 云端。
- 「待上传」：本地新扫描生成的 PDF 正在等待后台上传队列，保持 App 前台网络畅通即可自动完成。
- 「云端待下载」：在 Mac 端导入的卷宗已同步元数据至手机，正文尚未下载。轻点即可瞬间按需拉取。
- 释放本地缓存（手机瘦身）：对于已经结案或体积较大的历史卷宗，在信息面板中点击**「释放本地缓存」**，系统将安全清空保存在手机本地的大文件正文，腾出宝贵存储空间。云端文件完好无损，日后任何时候需要查阅，再次轻点即可重新下载。
四、首次开启同步的实务指引
- 首次上传耗时：若本地已有大量历史日程或数百页扫描卷宗，首次上传需要几分钟时间，请保持 App 前台运行且 Wi-Fi 网络通畅。
- 两端皆有本地数据时的合并策略：若两台设备上此前均录入过不同的本地数据，建议先在数据更完整、更重要的一端开启同步并等待上传清空队列后，再在另一端开启。
- 列表首次刷新：另一端首次接收云端数据推送后，若列表未即时呈现，轻拉列表刷新或重新退出打开一次 App 即可加载全量视图。
- Mac 端自动缓存：Mac 桌面硬盘空间通常较充裕，可在 Mac 端「设置 → 同步」中勾选「自动同步文档」，所有移动端扫描的卷宗将在后台静默自动下载到 Mac 本地。
五、分场景深度排障指南
场景 1：无法开启云端同步 / 开关打开后立刻回跳
- 原因 A：会员资格未识别
进入「设置 → 会员」查看状态；若未显示有效，点击「恢复购买」。若刚在 iPhone 端完成购买，Mac 端通常在 1~2 分钟内读取到凭证；亦可直接在 Mac 端点击恢复购买。 - 原因 B：系统 iCloud 权限未授
在系统设置中确认「庭记」使用 iCloud 的开关处于开启状态。 - 原因 C：需要重启进程生效
若设置页弹出重启提示，请在任务管理器中完全退出 App 后重新打开即可顺利开启。
场景 2：日程不同步（一端添加，另一端看不到）
- 确认两端均已切换为「云端同步」模式，排除其中一端处于「仅本地」状态。
- 在来源设备上小幅修改任意一条日程（例如在标题末尾增删一个空格并保存）以触发强制数据推送，等待 1~2 分钟。
- 在目标设备上完全退出 App 后重新打开，强制重新拉取云端快照。
- 若开启了科学上网工具，请暂时将其关闭或切换为直连模式测试。
场景 3：文档一直显示“待上传”或“上传失败”
- 检查 iCloud 剩余空间：进入系统设置查看个人 iCloud 存储空间是否已满。
- 手动重试：在 iPhone 文档信息面板（Inspector）中点击「重试上传」，保持 App 前台运行。
- 大文件网络环境：单份超过 50MB 的超大高清卷宗上传较慢，建议连接稳定的办公 Wi-Fi 进行同步。
场景 4：Mac 端看得到文档文件名但无法打开
这属于正常的**「元数据已同步，正文待下载」**状态。直接双击或点击该文档即可触发正文下载进度条；下载完成后即可正常翻阅。若希望所有文件均提前可用，请在 Mac 设置中勾选「自动同步文档」。
六、联系技术支持
若经过上述排查仍未恢复正常同步，欢迎随时与开发者联系：
- 📱 App 内提交：「设置 → 反馈」
- ✉️ 技术支持邮箱：courtnoteapp@outlook.com
建议在邮件中注明：设备型号、iOS / macOS 系统版本号、庭记 App 版本号，并附上两端设置页及 Inspector 面板截图，我们将竭诚为您定位并协助恢复。