发行与同步
记录如何从 Apple 健康走到你的服务器、各状态是什么意思,以及 Courier 对时机 的承诺(与坦白不承诺的部分)。
触发源
- 后台投递 —— Apple 健康收到新睡眠/运动,iOS 短暂唤醒 Courier,读增量 并发行。
- 打开 App —— 启动与回前台时的前台同步。
- 手动 —— App 内的发行操作,或快捷指令的立即发行。
- 批量发行 —— 编辑部 → 批量发行:选日期区间,向任意订户补发历史。
四个入口汇入同一条管线。
条目状态
每条出站记录走一个显式状态机,状态持久化——强杀或重启也不会失忆:
| 状态 | 含义 |
|---|---|
queued | 排队等候 |
awaitingRoute | 户外运动的 GPS 轨迹还没从手表到齐——Courier 宁可等,也不发残缺记录 |
sending | 请求在途 |
sent | 已送达(2xx),记入台账 |
failed | 失败且你已知悉——永不自动重试,只能手动重发 |
needsAttention | 失败/不全且未知悉:重试耗尽、轨迹久等不到、或源数据消失。红点 + 通知 |
重试
- 前台发行对网络错误做指数退避重试(2 s → 4 s → 8 s → 16 s)。
- 后台发行只做单次尝试、15 秒超时——iOS 后台时间金贵,Courier 不赌。 失败直接排进待处理。
- 一旦进入
failed,绝不自动重试——重发什么、何时重发,由你掌控。
幂等
每次请求都携带 Idempotency-Key 头:
- 正常发送与手动重发用记录稳定的 canonical
id——只要端点按键去重,同一次 运动无论重试多少遍都只会入库一次。 - 刻意的复份(「再发一份」)会轮换键为
id#2、id#3……让遵守幂等语义的 端点也能收下你故意要的副本。
只要你的服务器尊重 Idempotency-Key(或按 data.id upsert),整条管线在 任何环节重试都是安全的。
台账
编辑部 → 发行台账记录每一次发行:时间、订户、HTTP 状态与响应摘要。台账保留 6 个月,更早的自动清理——送达的内容本身,当然一直在你的端点上。
关于时机,说实话
后台投递受 iOS 节流。正常延迟几分钟到一小时左右,最坏情况要等你下次 打开 App。Courier 在界面文案里如实说明,而不是假装秒达。需要立刻发出? 打开 App,或运行立即发行快捷指令。
通知
两档(编辑部 → 通知):
- 始终通知 —— 每轮自动发行后给一条汇总,无论成败。默认。
- 仅失败时 —— 平时安静,出事才响。
通知需要系统权限;若在系统层被拒,Courier 会显示真实状态并给出去系统设置的 入口——而不是装作开关有效。