Samurai-meet

機能仕様：募集カード・マッチング

最終更新: 2026-08-29

1. 対象

ユーザーが日時、時間帯、キーワード、公開半径を指定した募集カードを公開し、閲覧者の関心をカード所有者が承認したときだけマッチを成立させます。承認後はチャットと会合セッションを別APIで開放します。

現行コードでは募集・検索・関心・承認／辞退のGo APIと、外国人／日本人画面からの募集・募集管理・応募履歴フロー接続コードが存在します。日時入力の初期パース問題はISO内部値／Asia/Tokyo固定化と自動テストで解消済みです。2026-08-29時点で公開APIのhealthzとreadyzは確認済みで、iPhone実機では表示言語の設定変更が現在表示中の画面にも直ちに反映されることを確認しています。一方、日時pickerから公開・応募・通知遷移・取消・ログアウト後の戻る操作までを単一の手順として再現する全通しE2Eは未完了です。

対応要件：FR-007、FR-009、C-001、C-003、C-004、C-005

2. 募集カード項目

項目	必須	仕様
日時	Yes	available_date。国内利用向けにAsia/Tokyo固定の壁時計として扱う
時間帯	Yes	start_time / end_time
キーワード	Yes	交流目的、言語、興味分野等。複数可
公開半径	Yes	1 km / 3 km / 5 km の選択式
位置	自動	有効な現在地から取得。正確な値は非公開
有効期限	自動	時間帯終了後に非表示
状態	自動	draft / open / matched / closed / expired
案内カテゴリ	自動	募集文をサーバー側のgemini-3.1-flash-liteでFood / Places / Activity / Otherの1つに分類する。Gemini APIキーはサーバー環境変数だけに置く

3. カード状態

card:  draft -> open -> matched
                  ├-> closed
                  └-> expired

match: pending -> accepted -> completed
       └-> cancelled（応募者が取り下げ）

• draft：未公開。作成者だけが閲覧可能。
• open：公開中。公開半径と検索条件を満たすユーザーへ表示。
• matched：少なくとも 1 件のマッチが成立。カードを閉じるか期限切れになるまで、追加の関心を受け付ける。カード自体は今回のAPIではcompletedへ遷移しない。
• closed：作成者が停止。
• expired：日時または有効期限を過ぎた状態。

4. マッチフロー

1. ユーザー A がカードを閲覧する。
2. A が「興味がある」を送る。
3. カード所有者 B が承認する。
4. matches.status = accepted となる。
5. チャットを作成または開放する。
6. 交流後、completed にして評価を有効にする。

5. 実装分担

処理	言語 / 場所
カード入力・プレビュー・状態表示	TypeScript / TSX
入力値の一次検証・フォーム状態	TypeScript
状態遷移、重複、期限、権限	Go
距離・公開条件	GoのHaversine + PostgreSQL（PostGIS未導入）
永続化	PostgreSQL / SQL

表示言語と利用モード

• 表示言語（日本語／英語）と利用モード（local／traveler）は別の保存設定です。片方の変更で、もう片方を切り替えてはいけません。
• 表示言語の変更は、すでに取得済みの募集・応募・通知データを再取得せず、現在の画面のコピーだけを即時に再描画します。画面復帰や設定変更を理由とする自動リロードは行わず、一覧の更新は利用者が明示的に行います。
• 通知の遷移先は表示文言ではなく、通知に含まれる構造化ID（募集ID・マッチID・応募者ID）で決めます。このため、言語や利用モードを変更した後でも既存通知を開けます。

6. API / DB

• GET /api/v1/recruitments
• GET /api/v1/recruitments/mine
• POST /api/v1/recruitments
• POST /api/v1/recruitments/classify
• GET /api/v1/recruitments/{id}
• PATCH /api/v1/recruitments/{id}
• DELETE /api/v1/recruitments/{id}（物理削除ではなくclosed化）
• POST /api/v1/recruitments/{id}/interest
• GET /api/v1/matches?role=owner&status=pending&limit=50
• GET /api/v1/matches/{id}
• POST /api/v1/matches/{id}/accept
• POST /api/v1/matches/{id}/reject
• POST /api/v1/matches/{id}/withdraw
• POST /api/v1/matches/{id}/complete
• POST /api/v1/matches/{id}/meeting
• テーブル：recruitment_cards、matches、blocks

募集カードの公開には名前・国コードが揃ったプロフィールが必要です。作成・更新の成功レスポンスは { "data": { ...card } }、検索は { "data": [ ...card ] } です。カードのレスポンスには正確な緯度・経度を含めず、現在地を使った場合だけ distance_band（within_1_km / within_3_km / within_5_km）を返します。

外国人側の募集確認に入る前に、POST /api/v1/recruitments/classifyが入力文をGeminiへ送り、Food、Places、Activity、Otherの案内カテゴリと最大5件の短いキーワード候補を返します。クライアントはAPIキーを保持せず、公開前にカテゴリ・候補キーワードを選び直せます。応答が契約外、未設定、またはGemini障害の場合はカテゴリを推測して公開せず、明示的なエラーにします。

検索条件は keyword（複数可）、available_date、start_time、end_time、radius_km（1/3/5）、verified_only、latitude、longitude、limit（最大50）です。緯度経度を省略した場合は、期限内の user_locations を使います。位置がない場合はキーワード・日時検索として扱い、位置による絞り込みは行いません。

現行のPostgreSQLイメージにはPostGISを追加していないため、距離計算はGoのHaversine計算です。座標はDB内だけで扱い、PostGISへの置換は性能改善タスクとして残します。

timezoneを省略または空にした募集入力はAsia/Tokyoへ正規化し、他のtimezoneは拒否します。created_atやexpires_atなどの絶対時刻はUTCで扱います。ISO内部値、JST固定の日時正規化、期限境界は自動テストで確認済みですが、過去時刻・日跨ぎ・端末日時pickerの実機確認は未完了です。

応募者はpending中に関心を取り下げられ、matchの状態はcancelledになります。取り下げ後の行は履歴と通知の冪等性のため保持します。

7. 受け入れ条件

• 必須項目が揃わないカードを公開できない。
• 公開半径は 1 km / 3 km / 5 km のいずれかに限定される。
• 作成者以外がカードを編集・削除できない。
• 同じユーザーが同じカードへ重複して関心を送れない。
• 相互承認前にチャットが開かない。承認後のチャットはchat_threadsを遅延作成する。
• 期限切れカードへ新たな関心を送れない。
• ブロック関係があるユーザーへカードが表示されない。
• 同じカードへの関心はユーザーごとに一度だけで、重複時は 409 interest_already_sent。
• カード所有者以外の承認・更新・削除は拒否する。
• 所有者または参加者に限定される状態変更は、別ユーザーが同じ募集ID・match IDを渡しても拒否し、募集・match・会合セッション・通知に副作用を残さない。URLのIDだけでなく、今後追加する関連ID入力も同じ認可境界で検証する。
• フロントエンドは募集公開、募集検索・詳細、関心送信、応募一覧、承認・辞退を上記APIへ接続する。
• 上記フロント接続、募集管理・応募履歴・応募取り下げ、表示言語に依存しない通知遷移、ログアウト後の履歴ガードはコードと自動テストで確認済み。iOSの表示言語即時切替は実機確認済み。iOSの日時pickerから公開・応募・通知遷移、応募取消、ログアウト後の戻る操作までの全通し実機E2Eは未完了とする。
• accepted前のチャットAPIは存在しない。承認後はRESTの暗号化メッセージ、既読、短命transport tokenを利用できる。

8. 要確認

• 通知はアプリ内RESTの一覧・既読・未読管理まで実装済み。OSプッシュ通知は未実装。
• 具体的な待ち合わせ場所をいつ・誰に表示するか。
• 時間帯の変更をマッチ成立後に許可するか。
• QUICによるリアルタイム配送と、会合セッション／距離補助のフロント接続。QUICは未実装の予定である。

9. iPhone実機E2Eの確認手順

本項の全項目が同じ公開API環境で確認できるまで、この機能を実機E2E完了とは扱わない。

1. 外国人モードで説明・日付・開始時刻・時間・半径を入力し、JSTの未来時刻で募集を公開する。空の説明、過去時刻、日跨ぎは公開されないことも確認する。
2. 日本人モードへ切り替え、同じカードを検索して応募する。再度開いたカードでは重複送信ではなく既存応募の状態が表示されることを確認する。
3. 募集者の通知から応募詳細を開き、承認または辞退する。表示言語を切り替えた後でも、同じ通知から正しい画面へ遷移できることを確認する。
4. 応募者の応募履歴で結果を確認し、pendingなら取消できることを確認する。募集者は募集管理で応募者と状態を確認する。
5. 画面復帰だけで一覧が再読込されないこと、明示的な更新操作では最新状態へ更新できることを確認する。
6. ログアウト後に戻るジェスチャーを行っても保護画面へ戻らず、言語選択画面にとどまることを確認する。