# アクティブ通知とWeb Push 更新:2026-09-25。実装・隔離fixture検証済み。同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。実機Push受信確認は未実施。 2026-11-01追記:配送処理を [Ordoschnellic](ordoschnellic.md) へ初期分離。 以下のUI・API・DB・購読を維持するソース変更であり、この分離自体は未デプロイ。 claim世代と購読更新競合を含む配送保証・残件は同契約に記録する。 ## UIと設定 通知ベルを開いたInboxの「⚙ 通知設定」に集約する。アカウント・ドメイン・ブラウザごとにlocalStorageへ保存し、他ユーザの設定を継承しない。通知本文はlocalStorageに保存しない。 | 状態 | 動作 | | --- | --- | | フォーカス中 | 右下に8秒で消えるトースト。最大3個。入力フォーカスを奪わない。既定ON | | 別タブ・別ウィンドウ/タブ終了 | 明示的に許可した端末へWeb Push。OSの通知UIを使用 | | 再訪 | 前回訪問以降の未読がある場合、設定ONならInboxを自動表示。既定OFF | | ダイアログ・入力を操作中 | 自動Inboxは保留し、次の確認時まで待つ | 新着は30件ずつ取得し、Inboxは「さらに表示」でページングする。訪問watermarkはサーバー時刻を使う。Web Locksと通知UUIDの短い履歴(最大200個)で複数タブのトーストを抑制する。Web Locks非対応時はbest effort。 音は「なし/ソフト/チャイム/ベル」と音量・試聴。Web Audioはブラウザの自動再生制限に従い、利用者の操作後に有効になる。カスタム音はフォーカス中のページ通知用。背景/タブ終了時の音はOS設定で決まり、サイト側から任意の音に置き換えることは保証しない。 ブラウザの通知許可は設定操作時のみ要求する。HTTPSと対応ブラウザが必要。iOS等はホーム画面への追加など端末側の条件もある。サービス・省電力・通信・キュー待ちに依存するため、定刻到達を保証するアラーム用途ではない。 ## 配信経路と安全性 `notification_inbox`挿入のDB triggerで`notification_push_queue`へ原子的に追加する。Inboxの全種類(タスク期限・計画日、Pomodoro、アナウンス等)で同じ経路を使う。購読開始前の通知を一斉再送しない。 `/_/api/v1/notifications/push`: - GET: VAPID公開鍵のみ。秘密鍵はDB内部に保存。 - POST: PushSubscription、focused、seen(最大30通知ID)。購読更新/閲覧中のack。 - DELETE: 現在の利用者が所有する購読を削除。 購読はDomain・Principal・**元の認証セッションのハッシュ**に束縛する。Bearer tokenは保存しない。claim時にセッション期限/失効、Principal、membership、Domain配置を再確認する。この時点でログアウト済み・無効化済みなら送信しない。claim後の失効と送信の競合は残る。最大8購読/利用者・Domain、30日lease(閲覧時に更新)。 VAPID秘密鍵は`notification_push_keys`に保存するため、DBバックアップを秘密情報として扱う。鍵を失った復旧では再購読が必要。端末の購読URL・鍵・通知本文をログへ出さない。 送信先はChrome/Chromium FCM、Mozilla Push、Apple Web Pushに限定。HTTPS/443のみ、資格情報・fragmentを拒否し、公開IPをDNS解決後に固定する。proxy環境変数とredirectは使用しない。プライベートIPへの接続は禁止する。Push本文は暗号化された通知UUID/受取人UUID/Domain UUIDのみ。件名・本文をPushサービスへ送らない。OSに表示するのも一般的な「新着通知」のみ。クリック後に通常の認可されたInboxで詳細を表示する。 Service Workerは`/static/js/notifications-worker.js`、scopeは`/static/js/`。fetch handlerやページキャッシュを持たず、既存のWikiページ/エディタに古い内容を返さない。notificationclickは同一originの`/v/notification`だけを開く。 ## スケジューラと上限 イベント`notification.push.deliver`、定義`builtin.notification.push`。既定30秒、priority -3。設定画面のイベント設定から停止・間隔変更・手動実行でき、再起動で既存設定を上書きしない。 - 最大20件/run、全体25秒、送信要求5秒。DB transaction内でネットワーク通信しない。 - 60秒のclaim lease。期限切れを再取得できる。クラッシュ時はat-least-onceだが、ブラウザ通知tagを固定し積み上げない。 - 429/5xx/通信失敗は指数backoff、最大5試行。404/410は購読を削除。 - キューの有効期間24時間、Push側TTL300秒。期限切れキュー削除は最大500件/run、期限切れ購読削除は100件/run。 - フォーカスlease90秒。閲覧中は送信を延期し、ブラウザが一覧を受け取った通知のackでキューを消す。表示できなかったままタブが閉じればlease終了後に再評価する。 - 前面pollは30秒。Pushが有効な背景タブは定期pollを停止し、Pushと復帰を契機に更新する。 - sent/failed集計をイベントログへ記録。再送でもInbox本体は複製しない。 フォーカスを失う瞬間やネットワーク遅延にはraceがあり、OS通知を完全に抑制する保証はしない。常に通知権限とOSの設定が優先する。 ## 検証・残TODO - Go: 原子rollback、claim重複防止、focus延期とack、他人のack拒否、失効後の配信遮断、backoff、購読API認証、公開鍵のみ、送信先とP-256鍵検証、イベント設定保持。 - Chromiumの合成fixture: 前面トースト、再訪Inbox、設定モーダルの横幅、既存Inbox既読/バッジ。実通知サービスへは送っていない。 - TODO: 実機Chrome/Firefox/Safari/iOSでの購読・閉タブ配信・復帰・logoutを確認。Pushサービス障害テストの拡充、端末一覧/VAPID rotation UI、quiet hours/digest、種類別設定、OS通知の詳細表示opt-in、端末間の個人設定同期。 - TODO: expired/revoked購読の清掃メトリクス、Push queue深さ/遅延/失敗コードの管理UI。旧worker購読の移行手順。 参考:[MDN Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)、[MDN Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)、[webpush-go](https://github.com/SherClockHolmes/webpush-go)。