通知配信パイプライン設計（キュー・レート制御・再送）

この記事の目的

現状、このリポジトリ内に通知配信パイプラインの実装コードはありません。
本記事は、将来実装する際に安全で運用可能な構成へ揃えるための設計基準です。

特に配信基盤は障害時の影響が広いですよね。
だからこそ、速度よりも再現性と回復性を重視し、先に設計判断を固定しておくことを目的にしています。

キュー中心アーキテクチャ

同期送信を避ける理由

登録処理と送信処理を同じリクエストで実行すると、外部プロバイダ遅延の影響を直接受け、ユーザー操作が不安定になります。
通知はキューへ積み、ワーカーで非同期処理する方針にすると、UI応答を保ちながら失敗時の再送も柔軟に扱えます。

まずは責務分離を前提に据えることが、拡張しやすい設計の出発点になります。

状態遷移を明示する効果

pending、processing、sent、failed のようなジョブ状態を明確に定義すると、障害時の切り分けが速くなります。
運用担当は「どこで止まっているか」を即座に把握でき、開発側も再送条件をコード化しやすくなります。

状態を曖昧にすると、重複配信や取りこぼしの原因が追跡できず、長期的な保守コストが上がります。

配信制御と再送方針

レート制御のコンセプト

通知は一括送信すると到達率が下がるため、全体上限とドメイン別上限を分けて制御する設計が有効です。
特定ドメインへの集中を抑え、配信品質を平準化できます。

運用現場では「たくさん送る」より「確実に届く」方が価値が高いですよね。
スループットより安定性を優先する設定思想を、最初から共有しておくことが重要です。

エラー分類と再送のルール化

一時障害と恒久障害を分けずに再送すると、無駄なリトライが増え、キュー滞留の原因になります。
timeout や 429 は再送対象、アドレス不正は即停止というように、エラー種別ごとの処理を設計段階で定義します。

再送回数の上限と待機間隔を明文化すれば、障害時の判断を個人依存にせず、チームで同じ運用を再現できます。

セキュリティと監査性

機微情報の扱い方

配信ジョブには顧客連絡先が関わるため、ジョブ本体に平文を持たない設計が安全です。
必要最小限の参照IDで処理し、表示時だけマスク済み情報を展開する方針にすると漏えいリスクを下げられます。

ログにもトークンや生データを残さないルールを徹底し、障害解析に必要な情報だけを安全に保存するのが基本です。

監査ログの役割

通知は顧客接点のため、「いつ・誰が・どのジョブを再送したか」を追跡できることが重要です。
監査ログがあると誤配信発生時の説明責任を果たしやすく、再発防止策も立てやすくなります。

運用では便利機能よりも、履歴の正確さが信頼を支えます。
初期段階から監査ログ要件を仕様に含めておくのが効果的です。

実装前チェックリスト

最低限そろえるべき合意項目

実装前に「状態遷移」「再送条件」「上限値」「エラー分類」の4点が合意されているかを確認します。
ここが曖昧なまま開発を始めると、後で運用要望に引きずられて改修が増えます。

先に合意事項を文書化し、変更時はレビューを通す運用にすると、機能追加があっても基盤品質を維持しやすくなります。

KPIは実装後に段階導入

本リポジトリでは通知機能自体が未実装のため、通知専用KPIダッシュボードも未実装です。
先に配信の信頼性を作り、その後に計測を段階導入する方が安全です。

実装前の記事でKPI成果を断定せず、現時点では「将来の観測項目候補」として扱う。
この整理をしておくと、読み手に誤解を与えない構成にできます。

まとめ

配信パイプラインは「速く送る仕組み」ではなく「安全に送り続ける仕組み」です。キュー化、状態遷移、再送ルール、監査設計を先に固めることで、実装時の手戻りと運用リスクを大幅に下げられます。