一、同步机制简介
庭记的跨设备协作基于 Apple CloudKit 私有数据库（Private Database）——数据存储在您自己的 iCloud 账号容器中，不经过庭记开发者的服务器，开发者无法访问您的数据。
日程与文档走两条独立的同步通道：
- 日程：结构化数据（案号、时间、提醒等）通过 CloudKit Record 同步，数据量小，网络正常时通常 30 秒至 3 分钟内到达另一端。
- 文档（PDF）：分两步走——元数据（文件名、文件夹位置、关联关系）先同步；PDF 正文以 CloudKit Asset 形式单独上传，另一端可在打开时按需下载，或在 Mac 设置中开启「自动同步文档」提前缓存到本机。
注意：日程不同步与文档不同步是两个独立问题，请根据具体现象分别排查，不要混为一谈。
二、开启同步必须满足的全部条件
以下任一条件不满足，同步均无法正常工作。请逐项核对后再排查其他原因。
条件一：两端登录同一 Apple ID
| 设备 | 检查路径 |
|---|---|
| iPhone | 设置 → 顶部头像 → 查看 Apple ID 邮箱 |
| Mac | 系统设置 → 左上角头像 → Apple ID |
两端必须显示完全相同的 Apple ID 邮箱。家庭共享成员各有独立账号，会员资格不在成员间共享，每人需用自己的 Apple ID。
条件二：系统 iCloud 服务正常开启
- iPhone：设置 → [你的名字] → iCloud → 确认「iCloud 云盘」已开启
- Mac：系统设置 → [Apple ID] → iCloud → 确认「iCloud 云盘」已开启
- iCloud 账号不处于欠费、停用或锁定状态（可在 appleid.apple.com 查看账号状态）
条件三：庭记被允许使用 iCloud（系统层面）
- iPhone：设置 → [你的名字] → iCloud → 显示全部 App → 找到「庭记」→ 确认已开启
- Mac：系统设置 → Apple ID → iCloud → 确认庭记 / iCloud Drive 相关权限未被关闭
- 曾关闭后重新开启，可能需要重启 App 甚至重启设备，授权才能真正生效
条件四：账号拥有有效高级会员资格
- 会员通过 iPhone App 内购买，购买后凭证会写入 CloudKit 供 Mac 端读取校验
- 在 App「设置 → 会员」可查看当前状态；曾购买但未显示时，请执行**「恢复购买」**
- 订阅到期后同步开关会在下次校验时自动回退，续订后需重新在 App 内开启同步
条件五：两端 App 均已手动开启同步
- iPhone：设置 → 找到「启用 iCloud」开关 → 打开（首次开启需阅读并同意隐私说明）
- Mac：设置 → 同步 → 将「同步模式」切换为「云端同步」
必须两端都开启；若仅一端开启，另一端处于"仅本地"状态，数据不会互通。
条件六：App 版本不过于落后
建议两端均保持更新到 App Store 最新版（当前 iPhone 1.2.23 · Mac 1.0.4）。版本差异较大时，同步协议可能不兼容。
条件七：网络可正常访问 Apple CloudKit
- 国内正常网络环境通常无问题
- 企业网络、教育网络或部分 VPN / 代理可能拦截 CloudKit 相关请求
- 完全离线时数据保留在本地队列，网络恢复后自动续传，无需手动重新上传
三、首次开启同步的注意事项
- 首次开启时 App 会将本地数据写入 CloudKit，数据量大时可能需要几分钟；请保持 App 前台运行且网络畅通，等待设置页同步状态提示完成后再切换到另一设备。
- 若两端都有历史本地数据，建议先在数据更完整的一端开启同步并等待上传完成，再在另一端开启，避免合并时产生重复条目。
- 另一端首次加载云端数据后，日程列表可能需要完全退出 App 并重新打开才能刷新显示。
- Mac 端文档默认不自动下载 PDF 正文；打开文档时触发按需下载。可在「设置 → 自动同步文档」中开启后台自动缓存。
四、快速自检清单
遇到同步问题时，先在 2 分钟内完成以下核查：
- 两端 Apple ID 一致？
- 系统 iCloud 云盘已开启，庭记的 iCloud 权限未被系统关闭？
- 两端 App 内均已开启同步（不存在一端仅本地）？
- 会员有效，未到期？
- 网络正常，非受限的企业 / 机构网络？
- 两端 App 已更新到较新版本？
- 新建一条测试日程，等待 2–3 分钟后在另一端刷新查看？
全部确认后仍有问题，请按下方对应场景继续排查。
五、分场景排障
场景 1：无法开启云端同步 / 开关立刻回退
可能原因 A：会员资格未被识别
- 进入「设置 → 会员」查看状态；若未显示有效，点击「恢复购买」。
- iOS 端完成购买后，Mac 端通常 2–5 分钟内读取到资格；若超过 10 分钟仍未识别，完全退出 Mac App 后重开再切换同步模式。
- 若两端 Apple ID 不同，Mac 无法读取 iPhone 的会员凭证，请确认账号一致后再操作。
可能原因 B：系统 iCloud 权限问题
- 按「条件三」的路径确认庭记对 iCloud 的访问权限未被关闭。
- 重新开启权限后，可能需要重启 App 甚至重启设备才能生效，之后再尝试开启同步。
可能原因 C：需要重启 App
- 若设置页出现提示文字，请完全退出 App（从任务切换器上划关闭），重新打开后再尝试。
场景 2：日程不同步（一端有，另一端没有）
- 确认两端均为「云端同步」模式，排除一端「仅本地」的情况。
- 在来源设备上小幅修改一条日程（如改标题加一个字再改回来）以触发强制推送，等待 2–3 分钟。
- 在目标设备完全退出 App 后重开，强制刷新本地缓存。
- 若使用 VPN 或企业网络，暂时断开后切换到普通 Wi-Fi 或手机热点再测试。
- 部分情况数据已写入 CloudKit 但 UI 未更新——拉动列表可触发手动刷新。
场景 3：文档一直"待上传"或"上传失败"
- 先确认文件可正常预览（打不开的损坏文件无法上传）。
- iPhone：打开文档信息面板（Inspector），点击「重试上传」，保持 App 前台至上传完成。
- Mac：确认「自动同步文档」已开启，保持 App 前台数分钟以清空上传队列。
- 检查 iCloud 可用空间：设置 → [你的名字] → iCloud → 查看剩余空间；空间不足时先清理后重试。
- 大文件（如 50 MB 以上 PDF）上传较慢，建议在 Wi-Fi 环境下耐心等待，不要反复退出 App 中断上传。
- 文档元数据（文件名、位置）可独立于正文提前同步——另一端已看到条目但点击后提示下载是正常现象，正文会在点击或网络恢复后自动下载。
场景 4：Mac 看得到文件条目但无法打开
- 这是正常的「元数据已同步、正文待下载」状态——点击文件会触发下载，等待进度完成即可打开。
- 若下载进度长时间停滞，检查 Mac 的网络与 iCloud 状态，必要时重启 App 后再次点击打开。
- 曾手动执行「移除本机缓存」的文件需重新下载，行为与上述一致。
场景 5：切换了 Apple ID 后同步异常
- 切换 Apple ID 后，旧账号的 CloudKit 容器数据不会自动迁移到新账号。
- 建议先将两端同步模式切换为「仅本地」，在旧账号设备上将重要文档导出到本机后，再在新账号下重新导入并开启同步。
- 新账号首次开启同步后，需等待本地数据上传完成，再在另一端开启以完成初始同步。
场景 6：企业网络或 VPN 环境下无法同步
- 部分企业防火墙会拦截 Apple CloudKit 的 HTTPS 请求（涉及 *.cloudkit.apple.com 等 Apple CDN 域名）。
- 测试方法：关闭 VPN 或切换到手机个人热点，若同步恢复正常，可判定为网络策略限制。
- 处理方式：联系 IT 部门将 Apple iCloud / CloudKit 相关域名加入白名单，或在非受限网络下完成数据同步操作。
六、何时联系支持
以下情况说明可能是 App 本身的问题，欢迎联系我们：
- 已核对全部条件、完成全部场景排查后，连续 24 小时同步仍无任何变化。
- 日程可同步但文档长期全部失败（或相反），且已确认 iCloud 空间充足。
- App 出现「同步错误」或包含 CloudKit 错误码的明确提示。
- 开启同步后历史数据出现异常丢失或大量重复。
请在 App 内通过「设置 → 反馈」提交，或发邮件至 [email protected]。建议附上：设备型号、iOS/macOS 版本、App 版本、问题首次出现时间，以及设置页同步状态区的截图，便于快速定位。