# アプリ内「不具合・要望」窓口を全アプリへ標準搭載する 社内 Web アプリに、利用者がその場で不具合・要望を送れる窓口を **1コマンドで後付けする**ための指示書。 「利用者 → 管理者 → 開発者」の口頭・チャット伝言を廃止し、報告が構造化データとチャット通知として自動で届く状態にする。 対象: Next.js App Router のアプリ（Pages Router / Remix / Vite でも API 仕様は流用可）。 前提: DB は任意（無い場合はチャット通知のみで動く）。追加の npm パッケージは入れない。 --- ## 1. 設計原則（ここを崩すと横展開できなくなる） | 原則 | 理由 | |---|---| | **追加 npm 依存ゼロ**（DB/Storage/Auth は REST を `fetch` で直叩き） | アプリごとに依存が違っても入る。`npm i` を要求した時点で「後で入れる」になり普及しない | | **CSS フレームワーク非依存**（ウィジェットは inline style で自己完結） | Tailwind 前提や独自トークン前提だと、入れた先で見た目が崩れる | | **Server Action など特定機能に依存しない**（素の API Route + `fetch`） | フレームワークのバージョン差・構成差で壊れない | | **保存先が無くても動く**（DB あり → DB＋通知 / DB なし → 通知のみ） | 「DB が無いから入れられない」を消す。公開サイトや静的寄りのアプリにも入る | | **導入は1コマンド、検証も1コマンド** | 人手の作業を残すと未導入アプリが残り続ける | ## 2. データモデル（DB を使う場合） ```sql create table if not exists app_feedback ( id uuid primary key default gen_random_uuid(), kind text not null default 'bug' check (kind in ('bug','request')), title text not null, body text not null, page_path text, -- 提出時の画面パス。再現の手がかりとして必須級 submitter text, submitter_email text, status text not null default 'new' check (status in ('new','triaged','in_progress','done','rejected')), priority text not null default 'normal' check (priority in ('low','normal','high')), admin_note text, resolved_ref text, -- 対応した PR / commit / URL screenshot_path text, created_at timestamptz not null default now(), updated_at timestamptz not null default now() ); create index if not exists app_feedback_status_idx on app_feedback (status, created_at desc); ``` - `create table if not exists` / `add column if not exists` / `on conflict do nothing` / `drop policy if exists` を使い **何度実行しても安全**にする（同じ SQL を別環境で何度も流すため）。 - `gen_random_uuid()` を使う（`uuid_generate_v4()` は拡張が入っていない環境で落ちる）。 - 画像は**非公開バケット**に置き、閲覧は期限付き署名URLで渡す。テーブルは RLS を有効化し、アプリからの読み書きはサーバー側の管理キーだけに限定する。 ## 3. API 仕様（`POST /api/feedback`） リクエスト: `multipart/form-data` | フィールド | 必須 | 備考 | |---|---|---| | `kind` | ✔ | `bug` / `request` | | `title` | ✔ | 200 字を超えたら**切り詰めて保存**（エラーにしない） | | `body` | ✔ | 4000 字で切り詰め | | `page_path` | – | クライアントが現在パスを埋める | | `screenshot` | – | `image/*`・8MB まで | | `company` | – | **ハニーポット**（後述）。人間には見えない欄 | レスポンス: `{ ok: true, id, sinks: { db: boolean, chat: boolean } }` / 失敗時 `{ ok: false, error }` と 4xx/5xx。 実装の要点: 1. **保存先の自動判定**: DB の URL とサーバー用キーが env にあれば DB へ insert、無ければスキップ。 通知は Bot API → Webhook の順にフォールバック。**片方が成功していれば投稿は成功**として返す。 両方不可のときだけ 503 と「保存先が未設定」を返す（黙って捨てない）。 2. **提出者の特定は best-effort**: 認証 Cookie からアクセストークンを取り出してユーザー情報 API に問い合わせる。 取れなければ `null`。**未認証サイトでは常に null になる前提**で、画面パスと本文で判断できるようにしておく。 3. **通知本文**にアプリ名を必ず入れる（`[アプリ名] 不具合: タイトル`）。複数アプリの通知が同じチャンネルに来るため。 4. **画像は保存先が無いときチャットへ直接添付する**（multipart）。 よくある事故: フォームは添付欄を出しているのに、DB 未設定時だけ画像が**黙って捨てられる**。 添付付き送信が拒否されたら本文だけで再送する。 5. 管理画面を入れない構成では、通知に管理画面リンクを**出さない**（404 に誘導してしまう）。 ビルド時のフラグ置換で出し入れする。 ## 4. ウィジェット要件 - 右下固定の浮遊ボタン → 中央モーダル。`role="dialog"` `aria-modal`、Escape で閉じる、外部イベント（`open-feedback` のようなカスタムイベント）でも開けるようにしてサイドバー等からも呼べる。 - 種別 select / タイトル / 本文 / 画像（任意）。**モーダル内で Ctrl+V の貼り付けから画像を添付**できると報告率が上がる（クリップボードの画像を `DataTransfer` で file input に流し込む）。 - 送信中はボタンを disable、成功でモーダルを閉じてトースト、**失敗時はモーダルを閉じずエラーを表示**。 - ⚠️ **重大な落とし穴**: React のイベントハンドラで `await` をまたいで `event.currentTarget` を触ると `null` になる。 送信後に `event.currentTarget.reset()` を呼ぶと TypeError が自分の catch に落ち、 **投稿は成功しているのに「送信に失敗しました」と表示される**。ハンドラ冒頭で `const form = event.currentTarget` を捕捉する。 ## 5. 公開サイト（未認証で誰でも POST できる）に置く場合 常時有効にしておく（社内アプリでも副作用は無い）: - **ハニーポット**: 人間に見えない入力欄を1つ置き、埋まっていたら**保存も通知もせず成功レスポンスを返す**（bot に弾いたと悟らせない）。 `display:none` は見抜かれるので、画面外配置＋`opacity:0`＋`tabIndex={-1}`＋`aria-hidden` にする。 - **レート制限**: 送信元 IP（`x-forwarded-for` の先頭）単位で「10分あたり5件」程度。超過は 429 と案内文。 上限は env で変更可能にする。 ⚠️ サーバーレスでは**実行インスタンスごとの計数**になるので厳密ではない。厳密に止めたいなら CDN/WAF 側のレート制限を併用する（この限界をドキュメントに明記して過信を防ぐ）。 - **入力長の上限**（前述）と画像サイズ上限。 - 管理一覧を置くなら**必ず認証で守る**。認証機構が無いアプリでは管理画面を入れず、通知とキュー取得スクリプトで運用する。 ## 6. 1コマンド導入インストーラの作り方 配布リポジトリに置いたインストーラを、導入先のリポジトリ直下でダウンロード実行する形にする。 ```sh node -e "fetch('<配布リポジトリのraw URL>/install.mjs?cb='+Date.now()).then(r=>r.text()).then(t=>require('fs').writeFileSync('install-feedback.mjs',t))" \ && node install-feedback.mjs --app-name "<アプリ名>" ``` インストーラがやること（Node 標準モジュールのみで実装する）: 1. `package.json` でフレームワークを確認し、App Router の位置（`src/app` → `app`）とコンポーネント配置先を検出。 2. `tsconfig`/`jsconfig` の `paths` に `@/*` があるかを判定して import の書き方を決める。 ⚠️ **JSON コメント除去の正規表現 `/\/\*[\s\S]*?\*\//` は `include` の `"**/*.ts"` を「ブロックコメント終端」と誤認して JSON を壊す**。 `"@/*"` の有無はテキスト照合で判定するのが安全。エイリアスを使う場合は `./` を前置しない（`./@/components/...` になる事故）。 3. ファイル配置（既存があれば `--force` なしでは上書きしない＝**冪等**）。 4. レイアウトへウィジェットを1行注入。import は **先頭ディレクティブ（`"use client"` 等）の後・既存 import の直後**に入れる（先頭行に入れるとディレクティブより前に来てビルドが壊れる）。 自動注入に失敗したら中止せず、**挿入すべき1行と対象ファイルの絶対パス**を出力する。 5. マイグレーションは既存連番の最大+1で書き出し、CLI や DB 接続文字列があれば自動適用。 できない場合は **SQL 全文＋管理コンソールの直リンク＋完了判定**（「Success. No rows returned と出れば完了」）を出す。 6. env の不足分だけを、取得方法（`vercel env add production` 等の完全なコマンド）付きで表示する。 **既にある値は「OK」と出すだけで再入力を求めない**。 7. 最後に「変更ファイル一覧 / 残作業 / 検証コマンド」をチェックリストで出す。`--dry-run` で何もせず予定だけ出せるようにする。 ### 配布物として崩してはいけない点 - 取得先は **ブランチ参照（`main` など）にしてコミットハッシュで固定しない**。固定すると改善のたびに全員へ URL 差し替えを頼むことになる。 - **テンプレートは全件取得してから書き込む**。1件ずつ取得→即書き込みだと、途中でネットワークが 5xx を返したとき 「API だけ入ってコンポーネントが無い」中途半端な状態が導入先に残る（実際に踏む）。 - 取得は 429/5xx とネットワーク例外に対して**指数バックオフで数回リトライ**（404 は即失敗）。 - raw 配信は push 直後に**古い版を返す**ことがある。配布前に「利用者が実際に叩く URL」を取得して新機能の目印を grep し、反映を確認してから配布する。 - **型注釈を正規表現で剥がして JS 版を生成しようとしない**（`response: Response` や `url: string` を取りこぼして構文エラーのファイルを書く）。 TypeScript のまま置き、非 TS リポジトリではフレームワークの自動セットアップに任せる方が安全。 ## 7. 導入後の検証（ここまでやって初めて「完了」） **Layer1: 実際にリクエストを飛ばす** - 起動したアプリへ multipart で実投稿し、`ok` / `sinks` を確認。 - 保存先のモックまたは実 DB で **read-back**（本当に行が入ったか）。通知は受信側のペイロードを捕獲して 「種別・アプリ名・画面パス・画像リンク（または添付ファイル名）」が入っているか突き合わせる。 - 必須未入力が 400、ハニーポットが「成功レスポンス＋保存0件」、レート制限が上限超で 429 になることを確認。 **Layer2: 実ブラウザで描画と操作** - 浮遊ボタンが表示され、コンテンツを隠していないか（座標を取得して判定）。 - モーダルが開く → 入力 → 送信 → 成功トースト → モーダルが閉じる。Escape で閉じる。 - **コンソールエラー0件**を条件に入れる。 **検証スクリプトの落とし穴** - モックサーバーは**プロセス内にログを保持する**ため、ログファイルを消しても前のテストのデータが残る。 各テストは「自分が投稿したタイトル」で対象を選別する（先頭の1件を取ると別テストのデータを検証してしまう）。 - 開発サーバーは `127.0.0.1` 由来のアクセスを別オリジン扱いして静的アセットを 403 にすることがある。 ブラウザ検証は `localhost` で叩く。 - テスト行は**削除せず**、状態を「却下」＋メモ付きにして残す（破壊的操作を避け、後から検証履歴を追える）。 ## 8. 運用フロー 1. 利用者がアプリ内から投稿 → チャットに即通知（担当者が見るチャンネル）。 2. 開発側は未対応キューを取得するスクリプト（`status in (new, triaged, in_progress)` を JSON 出力）で拾う。 DB を使っていないアプリでは**例外を投げずに「キューはチャットを見ること」と案内して正常終了**させる。 3. 実装 → デプロイ → `status` を `done` にし、`resolved_ref` に PR/commit を記録。 4. **自由記述をそのまま自動実装に流さない**。任意の利用者のテキストが本番コードを無人で書き換える経路を作らないこと（レビュー or 人のトリガーを必ず挟む）。 ## 9. 通知先の資格情報を配る時 - Bot トークンのような**広い権限の秘密を各端末へ配らない**。管理者側の権限で 「そのチャンネルへ投稿するだけの Webhook」を API 作成し、**その URL だけ**を配る（権限の最小化）。 - 既存の Webhook があれば作り直さず再利用する（重複作成を避ける）。作成後に**テスト投稿して疎通確認し、その投稿は削除する**。 - 複数端末へ配る仕組みがあるなら、そこへ載せて**受け取り側の手作業をゼロ**にする。 秘密を1本足すたびに既存の配布内容を書き直さずに済むよう、**追加分は別枠にマージする設計**にしておく （暗号化された設定値は読み戻せないことが多く、全体の再構成は事故のもと）。 ---