Skip to content

通知・ウォッチャー

in-app/メール通知・ウォッチャー購読・通知設定

概要

タスクとレビューの出来事を、アプリ内の通知とメールで利用者へ知らせる機能である。ウォッチャーでタスクの変更を購読でき、プロジェクトごとに通知設定を持つ。通知は API と CLI から読める。コアとコメント・アクティビティの機能に依存する。

振る舞い

ウォッチャー

task_watchers はタスクの変更を購読する利用者の一覧である。自分で登録できるほか、担当者に追加されたときとメンションされたときに自動で登録される。担当者を外しても、ウォッチャーの行は残る。

通知の種別と宛先

notification_type と通知対象は次のとおりである。

type 通知対象 トリガー
assigned アサインされた利用者。自分で自分を担当にした場合は通知せず、ウォッチャー登録だけ行う 担当者追加。payload の例は { "assigned_by": "tanaka", "role": "primary" }
mentioned 本文の <@利用者ID> のマーカーで指された利用者(プロジェクトに入れる利用者とテナント owner のみ。コメントとタスクの説明文で共通) コメント投稿・編集、タスクの作成・説明文の編集(編集では増えた分だけ)。説明文の通知は payload.source = "task_description" で分かれる
deadline_soon 担当者 + ウォッチャー(プロジェクトに入れる利用者のみ) 期限の通知に書く
status_changed ウォッチャー全員(変更した本人を除く) ステータス変更(PR のマージによる自動完了を含む)。一括更新では送らない
comment_added ウォッチャー全員(投稿者と、同じコメントでメンション通知が届いた人を除く) コメント投稿
pr_merged リンク先タスクの担当者 + ウォッチャー、その PR のレビューラウンドの作成者 PR 行の state が初めて merged になったとき(webhook の共通処理)
review_round_created レビューの関係者 + review_round_any の購読者 レビューラウンドの起票
review_finding_changed レビューの関係者 指摘の状態遷移

status_changed・comment_added の宛先は、そのプロジェクトに入れる利用者とテナント owner に絞る(notifiable_user_ids)。

review_round_any は通知種別ではなく購読の指定である。in_app_events に入れた利用者を review_round_created の受信者に加えるだけで、この種別の通知行は作られない。既定は OFF である。

期限の通知

deadline_soon は Soft 締切・Hard 締切それぞれの 24 時間以内に入ったときに送る。

  • 15 分ごとのバッチ(job::deadline_soon)で、起動直後にも走る
  • 複数インスタンスでは Redis のロック deadline_soon:sweep_lock(TTL 10 分)を取れた 1 つだけが走る
  • 完了・アーカイブ・削除済みのタスクは除く
  • 同じ期限に 1 回送り、期限を変えたら再送する
  • payload は { task_id, seq_key, title, kind: "soft" | "hard", deadline } である

通知の生成

タスクの更新を受けたハンドラが、同じトランザクションの中で通知の行を作る。作るのは service::notifications::create_notification の 1 箇所である。アプリ内が無効の種別は行を作らないので、メールも送らない。メールが有効なら行に送信待ちの時刻を入れるだけで、送るのはメール送信のループである。

flowchart TD
    event["タスク更新イベント発生"]
    targets["task_watchers から宛先を取得する"]
    scope{"プロジェクトに入れる利用者で、本人の操作でないか"}
    skip["通知しない"]
    inapp{"in_app_events に種別があるか"}
    row["notifications に INSERT"]
    email{"email_events に種別があるか"}
    queue["同じ行の email_queued_at を入れる"]
    done["アプリ内の通知だけ"]
    sweep["送信ループが拾って送る"]
    event --> targets --> scope
    scope -- いいえ --> skip
    scope -- はい --> inapp
    inapp -- いいえ --> skip
    inapp -- はい --> row --> email
    email -- はい --> queue --> sweep
    email -- いいえ --> done

読み取り(GET /v1/users/me/notifications)は project_id で見える範囲を絞る。入れないプロジェクトの通知は一覧にも未読数にも出ない。project_id IS NULL の通知はセッションからは常に見える。

レビュー通知の受信者

レビューは PR 単位で起きるのでウォッチャーが使えない。宛先は次の 2 つの和から、操作した本人とそのプロジェクトに入れない利用者を除いたものである。

  1. 関係者は、同じ PR の全ラウンドから集める。ラウンドの作成者、指摘を修正したと宣言した人(fixed_by)、解決できた PR の作者である。各人の in_app_events を見る
  2. 購読者(review_round_created のみ)は、そのプロジェクトの in_app_events に review_round_any を入れている利用者である。設定で明示的に ON にしているので、重ねて in_app_events は見ない

1 と 2 の両方に当たる利用者でも通知は 1 件である。

review_finding_changed の payload は project_id / review_id / finding_id / pr_number / round / from / to ほかである。to = deferred のときは繰り延べ先タスクの deferred_task_id(起票・再オープン直後の値)も入れる。クライアントはこれらの ID で遷移先を組み立てる。

PR の作者はラウンドの起票時点では分からず、要約ジョブが GitHub から取って reviews.pr_author に保存する。そのため作者への「ラウンドが起票された」通知は要約ジョブが補う。

  • 宛先は pr_author が NULL だったラウンドだけである。この列が NULL から埋まるのはラウンドごとに 1 回きりなので、ジョブを何度走らせても重複しない
  • 過去ラウンドから作者が判明している場合や購読者の場合は、起票時に作った同じラウンド・宛先の通知を確認し、要約ジョブから二重に通知しない

pr_merged の受信者

PR イベントの共通処理(Git ホスティング連携の Webhook)が、PR 行の state を merged 以外から merged へ変えたトランザクションの中でだけ送る。merged は戻らず、遷移は自然キーのロック下で判定するので、再送・再試行・マージ後の後続イベントでは送り直さない。

宛先は次の和から、そのプロジェクトに入れない利用者を除いたものである。各人の in_app_events / email_events を見る。

  1. PR にリンクされたタスク(削除済みを除く)の担当者とウォッチャー。通知はそのタスクに結ぶ
  2. その PR のレビューラウンドの作成者(reviewer_id)。PR 行のプロジェクトで判定し、タスクには結ばない

1 人 1 通にまとめ、先に当たった 1 のタスクに結ぶ。payload は { number, title, html_url, repo_owner, repo_name } である。メールのリンクはタスクに結ばれていればタスク詳細、そうでなければレビュー画面のその PR である。

メール送信

通知の行そのものがメールの送信待ち行列(outbox)になっている。job::notification_email の送信ループが 30 秒間隔で、email_queued_at が現在時刻以下で emailed_at が NULL の行を最大 50 件拾って送る。FOR UPDATE SKIP LOCKED なので複数インスタンスでも二重送信しない。

  • 1 通ごとに確定する。行ごとの短いトランザクションで FOR UPDATE SKIP LOCKED を取り、送信とその行の更新を commit するので、後の行の失敗で送信済みの記録が消えて再送されることはない
  • 成功すると emailed_at を入れる。1 通の失敗で他の行は止めない
  • 失敗すると email_attempts を 1 進め、email_queued_at を 30 秒 / 5 分 / 30 分 / 2 時間後へ進める
  • 5 回で打ち止めにする。email_queued_at を NULL に戻し、以後は拾わない
  • 次のいずれかに当たる行は、送らずに email_queued_at を NULL に戻して打ち切る
    • 宛先がメール未認証(users.email_verified = false)である
    • プロジェクトを引けない通知である
    • 送信時点で宛先がそのプロジェクトに入れない。通知作成後にテナントやプロジェクトから外れた場合で、判定は作成時と同じ notifiable_user_ids である

email_events の review_round_any は review_round_created の通知もメール対象にする。全ラウンドを受け取るには in_app_events にも review_round_any を設定する。メールは作成済みの in-app 通知から送るため、メール設定だけでは宛先は増えない。

件名・本文は service::notification_email::render が種別ごとに日本語で組み立てる。導線の URL は email_verification_app_url を基点に、タスク系は /{tenant}/projects/{KEY}/tasks/{KEY}-{seq_id}、レビュー系は /{tenant}/projects/{KEY}/reviews?pr={N} を出す。

保持期間

保持期間は NOTIFICATION_RETENTION_DAYS(既定 90 日)である。掃除ループ(job::notification_retention)が、メール送信と同じ tokio のループで、起動直後と以後 1 日 1 回、それより古い通知を消す。

  • メール送信待ちの行は古くても残す。email_queued_at あり・emailed_at なし・試行 5 回未満の行で、送信ループが拾う条件と同じである。再試行時刻を待つ間も送信待ちである
  • 送信を諦めた行(5 回に達した行)は待ちではないので消す
  • 通知の削除は監査ログ・遷移履歴に影響しない

既定の通知設定

notification_settings の行が無い利用者には、コードの既定(common::notifications::DEFAULT_IN_APP_EVENTS)を使う。assigned・mentioned・status_changed・deadline_soon・comment_added・pr_merged・review_round_created・review_finding_changed がアプリ内で有効で、メールは無効である。列の DEFAULT はコードの既定より狭いが、行は PUT で両方の列を指定して作るので適用されない。

データ

task_watchers

列 型 制約 説明
task_id UUID NOT NULL, FK→tasks CASCADE, PK(task_id, user_id)
user_id UUID NOT NULL, FK→users CASCADE, PK(task_id, user_id)
created_at TIMESTAMPTZ NOT NULL DEFAULT now()

notifications

列 型 制約 説明
id UUID PK
user_id UUID NOT NULL, FK→users CASCADE 受信者
task_id UUID NULLABLE, FK→tasks CASCADE
project_id UUID NULLABLE, FK→projects CASCADE 可視性の判定に使う。レビュー通知のようにタスクへ紐づかない通知も、プロジェクト単位で絞れる
notification_type VARCHAR NOT NULL 通知の種別と宛先の表のとおり
payload JSONB NOT NULL 表示に必要なデータ
read_at TIMESTAMPTZ NULLABLE NULL は未読
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
email_queued_at TIMESTAMPTZ NULLABLE 次にメール送信できる時刻。初回は通知作成時刻、失敗時は再試行時刻。NULL は送らない
emailed_at TIMESTAMPTZ NULLABLE 送信済み時刻。NULL は未送信
email_attempts SMALLINT NOT NULL DEFAULT 0 送信の試行回数。5 回で打ち止め

notification_settings

列 型 制約 説明
user_id UUID NOT NULL, FK→users CASCADE, PK(user_id, project_id)
project_id UUID NOT NULL, FK→projects CASCADE, PK(user_id, project_id)
email_events VARCHAR[] NOT NULL DEFAULT ‘{}’
in_app_events VARCHAR[] NOT NULL DEFAULT ‘{assigned,mentioned,status_changed,deadline_soon,comment_added,pr_merged}’

列の定義は m20260520000000_initial_schema.rs にある。project_id は m20260922000000_notifications_project_id.rs で、email_queued_at / emailed_at / email_attempts は m20260922010000_notifications_email_outbox.rs で足す。一覧のカーソルの並び順に合わせたインデックスは m20260924000000_notifications_cursor_index.rs にある。

API

ウォッチャー

パスは /v1/tenants/{tenant_id}/projects/{project_id} の配下である。

メソッド パス 説明
GET /tasks/{id}/watchers 購読者一覧(WatcherListResponse)
POST /tasks/{id}/watch 自分を追加(リクエストボディ不要。既に購読中でも 201)
DELETE /tasks/{id}/watch 自分を解除

解除できるのは自分の分だけで、テナントオーナーが他人を外す API は無い。

通知

メソッド パス 説明
GET /v1/users/me/notifications 一覧(新着順・カーソル)
PATCH /v1/users/me/notifications/read-all 権限のある通知を全件既読
PATCH /v1/users/me/notifications/{id}/read 1 件既読

GET /v1/users/me/notifications のクエリは次のとおりである。

クエリ 意味
unread true で未読のみ
kind task / review。既知のレビュー通知種別に含まれるかで分ける。それ以外の値は 400
limit 既定 50、上限 100(超える指定は 100 に切る)
cursor このカーソルより古い行(ページ送り)
after このカーソルより新しい行(catch-up)。cursor と同時指定は 400

表に書けない規則は次のとおりである。

  • 並びは created_at DESC, id DESC のみである。未読優先はせず、未読を上に出したい画面は unread=true で別に引く。offset は持たない
  • after 指定時だけは古い順(created_at ASC, id ASC)で返す
  • next_cursor は続きがあるときだけ返る。null なら取り切っている
  • next_cursor は、cursor 指定時・無指定時はページ内の最も古い行で、次の cursor に渡す
  • next_cursor は、after 指定時はページ内の最も新しい行で、次の after に渡す
  • 各行の cursor はその行自身を指すカーソルである。catch-up では受け取った最新行の cursor を保存して次回 after に渡す。next_cursor は取り切ると null になるので保存には使えない
  • カーソルは common::cursor((created_at, id) を base64 で畳んだもの)である。壊れた値は 400 になる
  • unread_count はクエリに関係なく、見える通知全体の未読数である
  • catch-up は unread=true ではなく after を使う
  • project は project_id から引いた要約で、API パスと画面 URL の組み立てに使う。引けなければ null である

通知設定

メソッド パス 説明
GET /v1/users/me/notification-settings/{project_id} 現在の設定取得
PUT /v1/users/me/notification-settings/{project_id} 設定更新(email_events と in_app_events)

認可

操作 誰が スコープ
ウォッチャーの一覧 プロジェクトに入れる人 read:task
ウォッチャーの追加・解除 プロジェクトに入れる人。自分の分だけ write:task
通知の一覧・未読数 本人。見える範囲は下に書く 種別に応じて read:task / read:review
通知の既読(1 件・全件) 本人。見える範囲は下に書く 種別に応じて write:task / write:review
通知設定の取得 本人 read:task
通知設定の更新 本人 write:task

CLI(task notifications list / read / read-all / settings)は PAT で呼ぶので、通知の 5 つのエンドポイントはセッション専用にしない。

スコープの規則は次のとおりである。

  • タスク通知には read:task / write:task、レビュー通知(review_round_created / review_finding_changed)には read:review / write:review が必要である
  • 一覧・未読数は読み取り権限のある種別だけを含み、個別・一括既読は書き込み権限のある種別だけを対象にする
  • 各操作でどちらのスコープもなければ 403、個別既読で対象の種別に書き込み権限がなければ 404 である
  • 既存の上位スコープの包含関係も適用する
  • 未知の通知種別は PAT に公開しない
  • CLI の task notifications settings --project にキーを渡すと UUID の解決にプロジェクト API を呼ぶため read:project も要る。UUID を渡せば設定 API だけを呼ぶ

PAT から見える範囲は「PAT のテナントのプロジェクト ∩ allowed_project_ids(指定があれば)」を、セッションと同じ所属判定(入れるプロジェクト)と重ねた集合まで絞る。一覧・未読数・全件既読の対象・1 件既読の 404 判定は、このプロジェクト範囲と種別ごとの権限を重ねて決める。

project_id を持たない通知(この列を足す前に作られた行)はセッションにだけ見せる。PAT からは一覧にも未読数にも出ず、全件既読の対象にもならない。

未実装と既知の制限

  • task_blocked(ブロッキング関係が追加されたときに担当者へ知らせる種別)が無い。関係を追加しても通知は作らず、種別の定数も無い
  • created_at はトランザクション内の時刻なので、長いトランザクションの通知が後から commit されると保存したカーソルより古い位置に現れ、after では拾えない。現状の生成経路は短いトランザクションなので許容する
  • 通知を見る画面・ウォッチャーの操作・通知設定の画面が無い。ヘッダーの利用者メニューに Notifications の項目はあるが、選んでも何も起きない

計画している画面は次のとおりである。

  • ヘッダーの通知ベルに未読数のバッジを出す
  • ベルをクリックすると通知のドロップダウンを開き、未読の表示・タスク(KEY-N とタイトル)・内容・操作者・相対時刻を並べ、「全て既読」の操作を置く
  • タスク詳細にウォッチャーの一覧と購読の切り替えを置く
  • 設定画面でプロジェクトごとの通知設定を編集する

決定の記録

日付 決定 理由
2026-09-22 review_round_any の既定を OFF にする 既定に入れるとプロジェクト全員が全 PR のラウンドを受け取る
2026-09-23 通知の行を送信待ち行列(outbox)にし、行に時刻を入れて送信ループが拾う create_notification からジョブは積めない(依存の向きが service から job)
2026-09-23 project_id を持たない通知はセッションにだけ見せる どのプロジェクトのものか判別できない
2026-09-24 通知一覧で未読優先の並びをしない 既読化で順位が変わるとカーソルが成り立たない
2026-09-24 after 指定時だけ古い順で返す 新しい側から limit 件を切ると、after との間の行を引く手段が無くなる
2026-09-24 catch-up は unread=true ではなく after を使う 既読だが未受信の行を落とさない
2026-09-24 メール送信待ちの行は保持期間を過ぎても消さない 送る前に消さない

Type to search…

↑↓ navigate↵ selectEsc close