# アプリ内フィードバック → 責任者の個別DM → Issue → 自動修正PR → 1タップ承認 社内 Web アプリの「不具合・要望フォーム」を、**報告が入ってから修正が本番に出るまで**繋ぐ設計。 責任者の手作業は最後の「PR をマージする1タップ」だけになる。 対象: Next.js App Router のアプリ（複数可）／通知先 Discord ／ CI は GitHub Actions ／ ホスティングは Vercel。 他スタックでも「中継を1箇所に置く」「既読マークを通知先に持たせる」考え方はそのまま使える。 --- ## 全体像 ``` [アプリのフォーム] POST /api/feedback ↓ [中継サーバー1台] POST /api/feedback-intake → 責任者の個別DMへ通知 ↓（夜間バッチが取りに行く） GET /api/feedback-intake?pending=1 … 未処理の報告を JSON で返す ↓ [夜間ジョブ] gh issue create --label feedback → 成功したものだけ POST /api/feedback-intake/ack （通知に ✅ を付ける＝既読） ↓ [無人セッション] feedback ラベルの Issue を拾って修正 → テスト → PR 作成（マージはしない） ↓ [中継] POST /api/notify → 「PRできました」＋PRリンク＋承認手順 をDMへ ↓ [人] PR を開いて Merge を押す → Git 連携でそのまま本番デプロイ ``` --- ## 設計判断（ここを外すと破綻する） ### 1. 通知先を各アプリに持たせず、中継1箇所に集約する 各アプリに Bot トークンを配ると、権限（多くの場合 Administrator）がアプリの数だけ拡散する。 中継サーバー1台だけがトークンを持ち、各アプリには**中継の URL と共有シークレットの2つだけ**を渡す。 得られるもの: - 通知先を変えたい時（DM → チャンネル、担当者の変更）に**中継の1箇所だけ**直せばよい。各アプリは無改修。 - 新しいアプリを追加する時、通知先を毎回考えなくていい（標準の既定が決まる）。 ``` FEEDBACK_RELAY_URL=https://<中継のホスト>/api/feedback-intake FEEDBACK_RELAY_SECRET=<32バイトのランダム16進> ``` 認証は `Authorization: Bearer ` の**定数時間比較**。 シークレット未設定のときは「認証なしで通す」ではなく **503 で止める**（設定漏れが公開中継になるのを防ぐ）。 ### 2. 個別DMを読む処理をローカルに置かない 「夜間ジョブが DM を読んで Issue 化する」と考えると、ジョブ側に Bot トークンが必要になる。 しかし **別の Bot のトークンでは他人との DM チャンネルを読めない（403）**。 通知に使った Bot 自身のトークンが要る＝結局トークンを配ることになる。 そこで**中継に「未処理キューの取得」と「既読化」も持たせる**。ジョブ側は共有シークレットだけで動く。 ``` GET /api/feedback-intake?pending=1&limit=50 → {"ok":true,"items":[{message_id, created_at, parse_ok, app_name, kind, title, body, submitter, page_path, source_url, permalink}]} POST /api/feedback-intake/ack {"message_id":"..."} ``` - **古い順**で返す（先に来た報告から処理したいので）。 - パースできなかったものは `parse_ok:false` で返す。**捨てない**。呼び出し側が判断する。 ### 3. 既読マークは「通知先のリアクション」で持つ 処理済みかどうかを状態ファイルや DB で持つと、実行するマシンが変わった時に二重起票する。 **通知メッセージに ✅ のリアクションを付ける**のを唯一のマーカーにすると、状態が通知先に一元化されて壊れない。 - Issue 作成に**成功した時だけ** ack する。失敗したら ack しない＝次回そのまま再試行される。 - ack は冪等にする（既に付いていても成功扱い）。 ### 4. 自分の通知を自分で拾う無限ループを、絵文字で断つ 同じ DM に「報告の通知」と「PRができた通知」の両方を流すと、 未処理キューが**自分の送った通知を報告として拾い、そこから Issue を作り、また通知が飛ぶ**。 先頭の絵文字で種別を固定し、キューは報告だけを拾う: | 種別 | 先頭 | キューが拾うか | |---|---|---| | 不具合の報告 | 🐛 | 拾う | | 要望の報告 | 💡 | 拾う | | こちらからの連絡（PR完成など） | 🔧 | **拾わない** | この判定は**純関数に切り出してテストを書く**。ここが壊れると通知が無限に増える。 ```js export function isFeedbackNotification(content) { return content.startsWith("🐛 **[") || content.startsWith("💡 **["); } ``` ### 5. 自由記述から作った修正は「PR で止める」 不具合報告は**利用者の自由記述**であり、それが人の目を通らずに本番コードを書き換えるのは危ない。 無人セッションには次を**禁止事項として明文で**渡す: - PR をマージしない - 本番へデプロイしない - 既定ブランチへ直接 push しない - 報告が曖昧で修正内容を特定できない場合は、**推測で実装せず** Issue にコメントして終わる 承認は**専用のボタンサーバーを作らない**。GitHub の PR 画面の Merge ボタンがそのまま承認ボタンになる（スマホでも1タップ）。 ホスティングを Git 連携にしておけば、**マージ＝本番反映**まで自動で繋がる。 ### 6. 通知に「次に何をすればいいか」を書く 承認者は手順を覚えていない。PR の URL が付いている時だけ、通知の末尾に固定文を足す。 ``` 承認するには: 上のリンクを開く → 緑の「Merge pull request」→「Confirm merge」。 これで本番に反映されます。直さない時は何もしなくて大丈夫です。 ``` PR 以外のリンク（Issue など）には付けない。判定は正規表現でよいが、**テストを書く**。 --- ## 実装の要点 ### 中継エンドポイント（Next.js App Router） `app/api/feedback-intake/route.ts` に `POST`（通知）と `GET`（未処理キュー）、 `app/api/feedback-intake/ack/route.ts` に既読化、`app/api/notify/route.ts` に連絡用を置く。 - `export const runtime = "nodejs"`（`crypto` と `FormData` を使う） - 通知本文は先頭の絵文字・アプリ名・種別・タイトル・本文300字・提出者・画面パス・提出元URL の順で固定 - ペイロードに `allowed_mentions: { parse: [] }` と **`flags: 4`（SUPPRESS_EMBEDS）**。 本文に URL を入れるとリンクプレビューが展開されて通知欄が流れるため - スクリーンショットは multipart で素通しする。**添付付きが弾かれたら本文だけで再送**する （画像のせいで通知全体が消えるのが最悪） - 送信元アプリ単位のレート制限（例: 1時間60件）。サーバーレスではインスタンス単位の概算になることをコメントに書く ### 夜間ジョブ ``` 1. GET ?pending=1 で未処理を取得 2. parse_ok:false → Issue を作らず ack もせず、理由をログに出す 3. アプリ名 → リポジトリのマッピングで宛先を決める（未マッピングも同様に残す） 4. gh issue create --label feedback（ラベルが無ければ作る） 5. 成功したものだけ ack。ack に失敗したら「重複の可能性」を警告に出す 6. 上限を超えた分は「残りN件」を明示して次回へ回す ``` **黙って何もしない経路を作らない。** 設定が無い・CLI が無い場合もスキップした事実を1行必ず出す。 （沈黙は「正常」と誤読され、動いていないことに何ヶ月も気付かない） ### 無人セッションへの渡し方 Issue を拾ったら `in-progress` ラベルを付けて二重着手を防ぐ（起動に失敗したら外す）。 子プロセスへ長いプロンプトを渡す時は **argv ではなく stdin かファイル経由**にする （日本語長文は argv でサイズ上限と文字化けに当たる）。 --- ## 踏んだ罠（全部実際に起きた） - **ローカルの作業ディレクトリをリポジトリ名から組み立てない。** `owner/my-app` → `~/work/my-app` と決め打ちすると、フォルダ名が違う（日本語名など）作業ツリーを見つけられず、 「無ければクローンする」フォールバックが動いて、**環境変数も依存パッケージも無い新品のクローン**でテストを回そうとして落ちる。 **`git remote get-url origin` を突き合わせて既存の作業ツリーを探す**のが正しい。URL は `https://host/owner/repo(.git)` と `git@host:owner/repo(.git)` の両形式を正規化して比較する。 - **人間の DM を試し撃ちの的にしない。** 「今後こう届きます」という見本を送った結果、貼ったリンクが 404 だったり、既にマージ済みの PR だったりして 「押すボタンが無い」と混乱させた。受け手は文面ではなく**リンク先の画面**を信じる。 経路の確認は API のレスポンスや読み取りで完結させ、人に届く形で試すなら**状態が文面と一致する実物**だけを貼る。 - **フォームの設置先レイアウトを間違えると誰も使えない。** 自動導入スクリプトが「最も深いレイアウト」を選ぶ実装だったため管理者用レイアウトに入り、 **報告者である一般利用者の画面に出なかった**。ルートレイアウトを最優先にする。 - **レイアウトへの自動挿入で壊れた JSX を書かない。** 閉じタグの位置を推測して挿入すると、兄弟要素が2つ並ぶ構文エラーになる。 安全に挿入できない形なら**書き換えず「手で入れてください」と残作業に積む**。 - **strict な TypeScript 設定（`noUncheckedIndexedAccess`）のリポジトリでは配列添字が `T | undefined`。** 配布用テンプレートは添字アクセスに undefined ガードを入れておく。 - **提出者の特定は認証方式に依存する。** テンプレートが特定の認証前提だと、別方式のアプリでは常に「不明」になる。 導入時にそのアプリのセッションから取り直す。 --- ## 検証（ここまでやって初めて「動いた」と言える） 1. 中継: 認証なし→401 / 必須項目なし→400 / シークレット未設定→503 / 正常→200 を**実際に叩いて**確認 2. 通知が**実際に届いた本文**を読み返して確認する（送信APIが200を返したことは着弾の証明にならない） 3. フォームから**本番の実投稿**を1件行い、レスポンスがどの経路を通ったか（例: `sinks.via === "relay"`）で確認 4. 夜間ジョブを `--dry` で流し、何件・どのリポジトリへ・どんなタイトルで作る予定かを表示させる 5. 実際に1件だけ起票し、**キューが1件減る**ことを確認（＝ack が効いている） 6. 「こちらからの連絡」を送った直後にキューを見て、**0件のまま**であることを確認（＝無限ループしない） --- ## そのまま使える環境変数 | 名前 | 置き場所 | 用途 | |---|---|---| | `FEEDBACK_RELAY_URL` | 各アプリ / 夜間ジョブ | 中継のエンドポイント | | `FEEDBACK_RELAY_SECRET` | 各アプリ / 夜間ジョブ / 中継 | Bearer 認証の共有シークレット | | `FEEDBACK_DM_USER_ID` | 中継のみ | 通知先の個人ID | | `` | **中継のみ** | 通知先APIの認証。アプリや各PCへ配らない | | `FEEDBACK_REPO_MAP` | 夜間ジョブ | `アプリ名=owner/repo` のカンマ区切り | ---