トーク / メンション

本ページは 2 段構成。上段が biz/CS 向け（ユーザー提示可）、下段（## 🔧 実装詳細 以降）が dev 向け。biz/CS がユーザーへ提示・転用してよいのは上段のみ。

概要

トークルームの投稿テキスト内で特定ユーザーを「メンション」する機能。投稿入力欄で @ を入力すると候補が表示され、選択したユーザーが本文に埋め込まれる。投稿が成功すると対象ユーザーへ専用のメンション通知が届き（./notification.md 参照）、対象ユーザーのメンションタブにも未読として記録される（./unread.md 参照）。

主な使い方:

• 受講者・メイン講師・サブ講師（投稿時）: 投稿入力欄・スレッド入力・編集ダイアログで @ を起点にメンション候補を呼び出して選択
• メンション対象側: 自身宛のメンション通知を受信し、メンションタブで一覧確認

候補は投稿者の権限・所属講座に応じて絞り込まれ、投稿時に対象ユーザーが権限要件を満たさない場合は自動的にメンションが解除されてプレーンな @ユーザー名 テキストへ置換される（誤って権限外ユーザーへ通知が届かない仕組み）。

📝 レビュー観点（draft 段階の記述ヒント、完成時に削除）:

• 目的: 特定ユーザー宛の発言を明示し、対象に通知（./notification.md）を届ける
• 誰が使うか: 受講者・メイン講師・サブ講師（投稿時）
• どこで使うか: トークルーム投稿入力欄、スレッド入力、編集時
• 隣接機能との関係: 投稿（./post.md）/ メンション通知（./notification.md）/ メンションタブ未読（./unread.md）
• CS 問い合わせで頻発する論点: 「メンションしたのに通知が来ない」「メンション候補が出ない」（@ 入力で候補表示の発見性）「メンション数の上限」
• [本機能特有] 候補サジェスト上限 20 名: FE 側の TALK_MENTION_USERS_MAX=20 はサジェスト候補表示の上限。本文に挿入するメンション総数の硬性制限ではない（BE 側にも件数チェックなし）
• [本機能特有] 権限フィルタによる自動除外: メンション対象が投稿禁止 / 退会 / 講座未契約 / プラン限定外 / DM 相手不一致 等の場合、本文中のメンションタグが @ユーザー名 のテキストに自動置換される（投稿後）
• [本機能特有] DB の二重持ち: talk_mention テーブル + talk.mention_user_ids (CSV) の両方に保存（dev 改善課題）

利用シナリオ

シナリオ 1: 受講者がメイン講師に質問する

受講者が講座の質問チャンネルで投稿するとき、メイン講師に直接届くようにしたい。@ を入力するとサジェスト候補にメイン講師・サブ講師が常時表示されるので、メイン講師を選択して投稿。投稿が完了するとメイン講師にメンション通知が届く。

シナリオ 2: 受講者同士でやり取りする

受講者同士のディスカッション中に他の受講者を呼び出したい。@ で候補から相手の名前を入力で絞り込み、選択して投稿。相手がメンション通知を受け取り、メンションタブにも未読として記録される。相手が通知 OFF にしている場合は通知が届かないが、メンションタブの未読は残る。

シナリオ 3: 編集でメンションを追加・削除

投稿後に「あの人もメンションすればよかった」と気づき、自分の投稿を編集してメンションを追加。新たに追加された対象ユーザーには通知は再送されないが、メンションタブには表示される。逆にメンションを削除した場合、相手のメンションタブからも該当が外れる。

よくある失敗ケース

• 退会者宛のメンション: メンション対象が投稿前に退会していた場合、投稿成功時に該当部分は @ユーザー名 のテキストに自動置換され、メンションは成立しない（通知も発火しない）
• 候補が出ない: アーカイブ / 非公開ルームでは受講者を候補に含められない（講師のみ候補表示）
• メンション通知が届かない: 対象ユーザーのメンション通知設定が OFF / 講座単位で通知 OFF / 投稿禁止フラグ等の権限制約に該当する場合は通知が届かない（メンションタブの未読は残る）

📝 レビュー観点:

• 標準的なメンション付き投稿（@ で候補から選択 → 投稿）
• メイン講師宛のメンション
• 退会者宛のメンション → 自動的に @ユーザー名 テキストに置換
• 編集時にメンション対象を追加 / 削除
• 失敗ケース: 候補が表示されない（権限）、サジェスト上限到達

権限別仕様

権限定義は ../user-roles.md 参照。用語は ../terminology.md。

講座権限軸

操作	未受講者	受講者	サブ講師	メイン講師
投稿時にメンション付与	×	○	○	○
自身宛のメンションの受信	×	○	○	○
メンション候補のサジェスト表示	×	○	○	○
自身宛メンションタブの閲覧	×	○	○	○

横断軸

操作	運営アドミン	テストユーザー	投稿禁止
メンション付与	（運営アドミン経由の直接投稿はなし）	（通常と同じ）	×
メンション対象としての受信	×	（通常と同じ）	×（投稿禁止フラグの影響なし、要確認）

📝 レビュー観点:

• 投稿禁止フラグユーザーがメンション「対象」になった時の挙動（要確認）
• 講師がアーカイブ済みルームでメンションした場合
• 候補サジェストでメイン講師は常時表示、受講者はルーム / 契約条件依存

機能詳細（ふるまい）

メンション入力 UI

投稿入力欄・スレッド入力・編集ダイアログで @ を入力するとサジェスト候補が表示される。候補から選択するとそのユーザーが本文に埋め込まれ、表示上は @ユーザー名 の形で見える。複数のメンションを 1 つの投稿に含めることも可能。

サジェスト候補

候補に含まれるユーザーは「該当講座のメイン講師・サブ講師（常時表示）」+ 「該当ルームの参加受講者」。検索文字列で名前を絞り込みながら選択する形式。サジェストとして同時に表示できるのは最大 20 名。20 名を超える対象がいる場合は名前検索で絞り込んで表示する想定。

DM ルームでは候補が「DM 相手 + メイン講師 + サブ講師」に限定される（DM 相手以外の受講者を候補に出さない）。アーカイブ済み・非公開ルームでは候補は講師のみに限定。

権限フィルタ（投稿時）

投稿時にサーバー側でメンション対象ユーザー一人ずつの権限・状態を確認し、要件を満たさないユーザーはメンションから自動除外される。除外された場合、本文中の該当部分はメンション扱いではなく @ユーザー名 のプレーンテキストに置換される（投稿後の表示も同様）。除外されたユーザーには通知が届かず、メンションタブにも記録されない。

除外条件

• 投稿禁止フラグユーザー
• 退会済みユーザー
• 講座未契約者
• プラン限定公開ルームで該当プラン未契約
• DM ルームで DM 相手以外（ただし講師は OK）
• アーカイブ / 非公開ルームで非講師

自身宛メンションの確認

トーク画面の「メンションタブ」で、自身宛のメンションが時系列に並んだ一覧を閲覧できる。一覧から該当投稿を開くとそのトーク本文へジャンプ。未読 / 既読の判定は ./unread.md のメンション未読軸に従う（投稿を含む位置までルーム / スレッドを開いた時点で既読化）。

編集時のメンション

自分の投稿を編集する際、メンション対象を追加・削除できる:

• 追加: 既存メンションに加えて新しいメンションを差し込める。新規追加された対象には通知は再送されない（追加分は通知済み扱いにはならず、メンションタブのみに反映）
• 削除: 削除された対象のメンションタブから該当エントリが外れる。通知済みの通知が取り消されるわけではない（通知としては履歴に残る）
• 編集時もメンション対象には同じ権限フィルタが走る

📝 レビュー観点:

• 入力 → 処理 → 出力: @ 入力 → 候補表示 → 選択 → 本文中に表示用文字列挿入 → 投稿時に対象 ID リストとして送信 → 権限フィルタ → 保存
• エッジケース: 候補ユーザーが投稿前に退会した場合、ルームのプラン限定が変更された後の既存メンション、編集時の差分計算
• エラー表示: 候補なし時、サジェスト上限到達時
• [本機能特有] サジェスト 20 名は「候補表示数」: 本文に何人メンションできるかの硬性上限ではない

admin 操作

該当なし

メンション関連の運営アドミン専用操作は存在しない。

実装されていない / 不明

• 運営アドミンによるメンション一覧参照: 専用経路なし
• 不適切メンションの強制解除: 専用経路なし、講師に依頼する運用 — 今後の改善課題

📝 レビュー観点:

• メンションを使った嫌がらせ等の運営対応経路の必要性

品質 / 約束事項

• 応答性: 候補サジェストは入力即時、メンション付き投稿は通常投稿と同じ応答性（投稿成功時に同期で返り、通知は数秒以内に非同期配信）
• 信頼性: 投稿時の権限フィルタにより、不適切ユーザーへの通知は防止される（除外ユーザーは投稿成功時に自動的にプレーンテキストへ置換）。投稿後にユーザーの権限が変わってもメンション記録は再評価されない（編集時のみ再フィルタ）
• 制限値:
  • サジェスト候補表示: 最大 20 名
  • 本文中のメンション総数: 硬性上限なし（本文 5000 文字制限内で実質決まる）
• データ保持: メンション対象はメンション記録テーブルに保持、論理削除

📝 レビュー観点:

• 応答性: 候補表示の体感速度（受講者数の多い講座での性能）
• [本機能特有] 制限値の不在: メンション数の硬性上限を入れるかは要件次第（dev 改善課題）

変更履歴（リリースノート候補）

v2.31.0: 2026-05-04

• [修正] プラン限定ルームでメンション解決時に追加契約者のメンションが内部エラーで打ち切られる不具合を修正（FIN-441）。複数契約のあるユーザーへのメンション通知が届かなくなるケースを解消。詳細は ./notification.md を参照

v2.29.2: 2026-05-02（PSD 初版）

• [PSD 追加] 本ドキュメント初版作成。v2.29.2 時点の実装を起こし。機能追加・変更は含まない

📝 レビュー観点:

• 過去の主要変更（メンション機能追加 / 権限フィルタ追加 / メンションタブ追加 等）

関連ドキュメント

• 権限定義: ../user-roles.md
• 用語辞書: ../terminology.md
• 関連 PSD:
  • ./post.md — 投稿（メンションを含む投稿の作成・編集・削除）
  • ./notification.md — メンション通知の発火
  • ./unread.md — メンションタブ未読
  • ./thread.md — スレッド内でのメンション扱い

---