RelationNote

顧客・関係者のつながりをまとめて管理。顧客や関係者のデータを組織ごとに管理する汎用のSaaS

基本設計書 v0.1（2026-10-21）に沿った実装です。最初の想定利用者はNPO（基本設計書の前提）。複数の組織が共通基盤を使うマルチテナント型で、 応募フォームの回答を人物単位に整理し、イベント参加履歴と、写真からの人数推定を管理します。

構成

設計書	実装
画面・業務API	Next.js 16（App Router / Server Actions / Route Handlers）・TypeScript
DB・組織分離	Supabase PostgreSQL。全主要テーブルに organization_id、外部キーにも組織IDを含め、RLS で参照・追加・更新・削除を制御
認証・権限	Supabase Auth ＋ memberships（オーナー／管理者／編集者／閲覧者 ＋ 一括出力・一括削除・人物統合・権限変更の個別権限）
写真保存	Supabase Storage の非公開バケット。アップロードは期限付きURL、閲覧は所属メンバーのみ期限付きURL
非同期処理	Supabase Queues（pgmq）＋ Edge Function process-jobs ＋ Supabase Cron（毎分起動）
人物検出	Amazon Rekognition DetectLabels（Person）。開発用にダミー検出器（DETECTOR=mock）

ディレクトリ:

• supabase/migrations/ … スキーマ・RLS・業務ロジック（名寄せ、統合、利用枠、ジョブ、集計）
• supabase/functions/process-jobs/ … ワーカー（写真解析・回答の取り込み・一括出力・期限切れ整理）
• src/app/orgs/[orgId]/ … 管理画面
• src/app/api/ … アップロード・取り込み・外部フォーム受信・出力ダウンロード
• tests/ … 単体テストと、ローカルSupabaseに対する受け入れテスト

ローカルで動かす

npm install
supabase start -x studio,postgres-meta,imgproxy,vector,logflare,realtime,supavisor
supabase status -o env   # 値を .env.local に転記（.env.example 参照）
cp supabase/functions/.env.example supabase/functions/.env   # WORKER_SECRET を設定
supabase functions serve --env-file supabase/functions/.env --no-verify-jwt   # ワーカー
./scripts/setup-local-cron.sh   # Cron から毎分ワーカーを呼ぶための Vault 登録
node scripts/seed-dev.mjs       # デモ組織とサンプルデータ（任意）
npm run dev                     # http://localhost:3080

ポートは他プロジェクトと衝突しないよう API 55621 / DB 55622 にしています。 CSV取り込みの試験用ファイル: scripts/sample-volunteer-form.csv

テスト

npm test

ローカルの Supabase が起動している必要があります。設計書 §16 の受け入れ条件のうち、自動で確かめられるものを網羅しています。

• 別組織のデータを API・DB・ストレージから取得・変更できない（他組織IDでの登録、外部キーでの越境、organization_id の付け替え、他組織の写真・出力ファイル、ワーカー専用関数）
• 退会・権限変更が即座に反映される／最後のオーナーは削除・脱退できない
• 同じ回答・ジョブを再送しても二重登録されない（回答ID・原文ハッシュ、Webhook 再送、解析結果の保存の繰り返し、同じ写真のジョブ）
• 名寄せが曖昧な人物（連絡先だけ一致、氏名だけ一致）を自動統合しない
• 推定人数と確定人数を別に保存し、写真人数を参加人数・実参加者数に合算しない
• 利用上限到達時は新規処理を止め（CSV は保留）、既存データは閲覧できる／停止中の組織は閲覧のみ
• 失敗ジョブの再試行・隔離・再実行、隔離分は利用枠に計上しない

名寄せのルール（§4.2）

状況	結果
メールまたは電話が一致し、氏名も一致する人物が1人	既存人物に紐づけ（空欄の補完と連絡先・タグの追加のみ。上書きしない）
メール・電話は一致するが氏名が違う	確認待ち（家族で共有している可能性）
氏名だけ一致	確認待ち（同姓同名の可能性）
一致なし	新規作成

確認待ちは「確認待ちの回答」画面でスタッフが判断します。登録済み人物どうしの重複は「重複候補」画面で統合でき、統合前の状態は履歴に残ります。

集計の扱い（§5）

• イベント参加人数 = スタッフ確定値があればそれ、なければ「参加確認済みの記録＋匿名参加者」
• 延べ参加人数 = 期間内のイベント参加人数の合計
• 実参加者数 = 参加確認済みの人物の重複除外（匿名参加者は含められない）
• 継続参加者数・関係人口 = 組織設定の回数・期間で判定
• 写真の人数はイベントごとの最大値を参考表示するだけで、合算も自動転記もしない

顧客管理の機能

• 項目の追加：組織ごとに人物・企業の項目を定義（文字・数値・日付・選択肢・チェックなど10種類）。値は型を検証して保存し、CSV出力・フォームの取り込み（対応先「追加項目」）にも対応
• 企業（法人）：企業の台帳と、担当者（人物）の紐づけ（部署・役職・主担当）
• やりとりの記録：電話・面談・メール・訪問・オンラインを時系列で記録。人物の画面では、やりとり・メモ・イベント参加・フォーム回答をまとめたタイムラインを表示。記録と同時に次の予定をタスクにできる
• タスク：担当・期限・優先度・対象（人物/企業）。期限切れ・今日のタスクはメニューに件数を表示し、毎朝8時に担当者へメールで通知（メール送信の設定後）
• メールの一斉配信：タグ（いずれか／すべて／除外）で宛先を決め、プレビュー・自分あてのテスト送信のあと送信。1人1通・同じアドレスは1通・配信停止は除外。 送信は非同期で「多くて1回」（送信中に止まった宛先は再送せず「送信不明」にする。接続できない障害は未送信なので再試行）。 開封は画像の読み込みで推定。末尾に送信者情報と配信停止リンクを付け、送信時に宛先の同意を確認する（特定電子メール法への配慮）。 送った記録は人物のタイムラインに残る（削除不可）。一斉配信は「一斉メール配信」の権限が必要。今月の送信数はプランの枠（標準 1,000通）で管理

メール送信の設定

ワーカー（Edge Function）の環境変数 MAIL_TRANSPORT=smtp・SMTP_*・MAIL_FROM・APP_URL（supabase/functions/.env.example 参照）を設定し、 Vercel の環境変数 MAIL_SENDING_CONFIGURED=1 を入れると画面の送信ボタンが有効になる。Edge Functions は 25・587 番ポートに接続できないため、Gmail は 465 を使う。 ローカルでは Supabase 付属のテスト用メールサーバー（Mailpit、http://127.0.0.1:55624）に送られ、外部には届かない。

申し込みフォーム（公開URL）

外部サービスを使わず、RelationNote の中でフォームを作って公開できる。「フォーム・取り込み」→ 方式「申し込みフォームを作る」。

• 作る：質問の追加・並べ替え、種類（文章・メール・電話・数値・日付・選択肢・チェック）、登録先（氏名・ふりがな・メール・電話・地域・備考・タグ・追加項目・回答として保存）、受付期限と上限、送信後の文章。右側に回答者の画面のプレビューが出る
• 公開する：/f/<推測できない文字列> の URL を発行。ログイン不要、スマートフォン対応、検索エンジンには載せない
• 届いた回答：CSV・外部フォームと同じ流れ（二重取り込み防止 → 名寄せ → 確認待ち）に入り、1分ほどで人物に登録される。申込先イベントを指定すると「申込」として登録する
• 同意の記録：公開には個人情報の取り扱いの説明が必須。回答者は同意してから送信し、同意した文面を回答と一緒に残す

公開の入口を増やすため、次のように守っている（supabase/migrations/20261029000001_public_forms.sql、src/app/f/）。

• 未ログインの利用者に DB の権限は与えない。公開画面はサーバーがサービスロールで専用の RPC だけを呼ぶ。組織はURLから決まり、送信側から指定できない
• 画面に返すのは受け付けたかどうかだけで、すでに登録されている人かどうかは分からない。公開画面に組織IDや登録先の情報は渡さない
• 検証はサーバー側で行う（選択肢にない値、形式違い、長すぎる値を拒否）。自由入力をタグの登録先にはできない
• 連続送信の制限：同じ送信元から10分に30件、フォーム全体で1日5,000件。人に見えない欄、画面の表示からの最短時間、署名付きの札で機械的な送信を止める。送信元は IP アドレスを鍵付きハッシュにして記録し、1日で消す
• 同じ画面からの二重送信は1件にまとめる
• 定義の変更は管理者のみ（直接の表の更新は不可）。操作は操作履歴に残る

未対応：回答者への自動返信メール（メール送信の設定後に検討）、ファイル添付、CAPTCHA（外部サービスの契約が要るため。回答数に合わせて判断）、回答一覧の CSV 出力（人物一覧の出力は使える）。

外部データとのコネクト（自動取り込み）

「フォーム・取り込み」でフォームを追加するときに方式を選ぶ。取り込んだ回答は CSV と同じ流れ（二重取り込み防止 → 名寄せ → 確認待ち）に乗る。

方式	仕組み	利用者の操作
Google フォーム	OAuth（読み取り専用）で連携し、Forms API から前回以降の回答を定期取得（既定15分ごと）	「Google と連携」→ フォームの URL を貼る → 提案された項目の対応を確認 →「自動取り込みを始める」
Google スプレッドシート	同上。Sheets API で1行目を見出しとして読み、内容が同じ行は二重に取り込まない	同上（シート名は任意）
Typeform / Tally	相手のサービスから Webhook。署名（HMAC-SHA256）で送信元を確認	「署名用の秘密を発行」→ 相手の Webhook 設定に URL と秘密を入れる
汎用 Webhook	Authorization: Bearer <秘密> 付きの JSON	Apps Script などから送る

• 連携の鍵（Google のリフレッシュトークン・署名用の秘密）は Supabase Vault に暗号化して保存し、利用者向け API からは読めない。連携を削除すると鍵も消える
• 「氏名」の対応が決まるまで届いた回答は保留にし、対応を保存すると自動で処理する
• Google の連携が取り消されたら「連携し直してください」にして自動取得を止める
• Google を使うには Google Cloud で OAuth クライアント（ウェブアプリ）を作り、GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET を Vercel と Edge Function の両方に設定する。 承認済みのリダイレクト URI は https://relationnote.vercel.app/api/connectors/google/callback。 フォームの回答・スプレッドシートの読み取りは Google の「機密性の高いスコープ」のため、一般公開には Google の審査が必要（審査前はテストユーザーに登録した100人まで）
• ローカルでは node scripts/mock-google.mjs（Google を模した疑似サーバー）で、連携から取り込みまで確認できる。本物の Google での検証ではない

This is the beginning of the README. Read the rest at the original. Read the full README ↗