発行と同期
レコードがヘルスケアからあなたのサーバーへどう旅するのか、各状態が何を 意味するのか、そしてタイミングについて Courier が何を約束し（正直に言って） 何を約束しないのかを説明します。
トリガー
- バックグラウンド配信 — ヘルスケアが新しい睡眠／ワークアウトの データを受け取ると、iOS が Courier を短時間起こします。Courier は差分を 読み取り、発行します。
- アプリを開く — 起動時と復帰時のフォアグラウンド同期。
- 手動 — アプリ内の発行アクション、または今すぐ発行ショートカット。
- 一括発行 — 編集部 → 一括発行：日付範囲を選び、任意の購読者へ過去の データをさかのぼって送れます。
4 つのトリガーはすべて同じパイプラインに流れ込みます。
項目の状態
送信されるレコードはすべて明示的なステートマシンを通り、状態は永続化されて います。強制終了や再起動があっても見失うことはありません。
| 状態 | 意味 |
|---|---|
queued | 順番待ち |
awaitingRoute | GPS トラックがまだ Watch から届いていない屋外ワークアウト — Courier は不完全なレコードを送らず、待ちます |
sending | リクエスト送信中 |
sent | 配信済み（2xx）。発行履歴に記録されます |
failed | 失敗し、確認済み — 自動で再送されることは決してありません。手動で再送してください |
needsAttention | 失敗または不完全で、まだ未確認：リトライを使い果たした、ルートが届かなかった、あるいは元データが消えた場合。赤いドット＋通知 |
リトライ
- フォアグラウンドの発行は、ネットワークエラーを指数バックオフで リトライします（2 秒 → 4 秒 → 8 秒 → 16 秒）。
- バックグラウンドの発行は、15 秒タイムアウトの 1 回きりの試行です — iOS のバックグラウンド時間は希少であり、Courier はそれを賭けに使いません。 失敗はそのまま要対応のキューに入ります。
failedに達したものが自動で再送されることは決してありません — 何を 再送するかの主導権は常にあなたにあります。
冪等性
すべてのリクエストには Idempotency-Key ヘッダーが付きます。
- 通常の送信と手動の再送は、レコードの安定した canonical な
idを使い ます — キーで重複排除するエンドポイントなら、配信を何度リトライしても 同じワークアウトが二重に保存されることはありません。 - 意図的な複製（「もう 1 部送る」）はキーを
id#2、id#3、… と回転させる ので、冪等なエンドポイントでも意図した複製は受け入れられます。
サーバーが Idempotency-Key を尊重する（または data.id で upsert する） なら、パイプライン全体がどの時点でも安全にリトライ可能になります。
発行履歴の台帳
編集部 → 発行履歴には、すべての発行がタイムスタンプ、購読者、HTTP ステータス、レスポンスの抜粋とともに表示されます。履歴は 6 か月保持 され、古いエントリは自動的に整理されます — もちろん、配信された内容 そのものはあなたのエンドポイント上に残り続けます。
タイミングについて、正直に
バックグラウンド配信は iOS によって制限されます。数分から 1 時間程度の 遅延を見込んでください。最悪の場合、発行は次にアプリを開いたときに行われ ます。Courier は即時であるかのように装うのではなく、この事実を UI の文言 でも明示しています。今すぐ確実に送りたい場合は、アプリを開くか、 今すぐ発行ショートカットを使ってください。
通知
2 つのモードがあります（編集部 → 通知）：
- 常に — 自動発行のたびに、成功でも失敗でも結果のサマリー通知。 デフォルトです。
- 失敗時のみ — あなたの対応が必要なとき以外は沈黙します。
通知にはシステムの許可が必要です。拒否されている場合、Courier は動作して いるふりをする代わりに、実際の状態と iOS 設定へのショートカットを表示 します。