保険代理店CRM

テーマ

外部連携 ​

全体像 ​

共通設計 ​

  • アダプタ層: server/integrations/<service>/ にクライアントを置き、テストしやすくモック可能にする
  • Webhook: 署名検証 → イベント永続化 → 同期処理 or キュー投入の順
  • 冪等性: 受け取った外部イベントID（Stripe event.id、LINE webhookEventId）で重複検出
  • リトライ: 外部送信失敗は指数バックオフで再送。永続失敗は dead_letter テーブル
  • レート制限: クライアント側でも各サービスの上限を尊重（特にLINE Push API）

LINE 連携 ​

1チャネルあたりの構成 ​

  • Channel Secret / Access Token は 暗号化保存（LINE_CHANNELS.*_enc）
  • Webhook URL は /api/webhooks/line/:channelId 形式で チャネル別に固有
  • 署名検証: x-line-signature を channel_secret で HMAC-SHA256 検証

主要イベント処理 ​

イベント処理
follow新規 LEAD レコードを作成、未紐付け
unfollowLEAD/LINE_BINDING のステータスを更新
messageLINE_MESSAGES に direction=in で記録、紐付け済みならCustomerに紐付け
postback (リッチメニュー押下)アクション実行
beacon / accountLink（後続）

Reply / Push ​

  • Reply API: Webhook受信から 30秒以内。Reply Token を即時消費
  • Push API: 一斉配信は Multicast / Narrowcast を活用（コストとレート対策）
  • 送信失敗のリトライは dead letter に積み、再配信UIから手動再送

リッチメニュー ​

  • 編集UIで RICH_MENUS.layout を JSON 保存
  • 「公開」操作で LINE 側 API に登録 → デフォルト割当

アンケート ​

  • LINE 内では FlexMessage / Quick Reply で配信
  • 回答は Webhook 経由で SURVEY_RESPONSES に記録
  • 回答者が紐付け済みなら customer_id を付与、未紐付けは line_user_id のまま保持

Stripe / Square 連携（SaaS 課金） ​

プロバイダ選択 ​

  • ADMIN管理画面で選択。1運用環境につき1プロバイダ。
  • 切替は将来追加。MVP では切替不可（または ADMIN による全テナント影響を伴う作業として扱う）。

Stripe フロー ​

Square フロー（要点） ​

  • Subscriptions API で同等のサブスクリプション化
  • Webhook: subscription.created / invoice.payment_made などをハンドル
  • Square SDK は Stripe ほど薄くないため、アダプタ抽象でAPIを揃える

カード情報の取り扱い ​

  • CRM 側のDBに支払い手段は一切保存しない
  • 保存するのは provider_customer_id / provider_subscription_id / provider
  • 課金画面はプロバイダ側の Hosted Page / Checkout に委譲

Webhook 共通 ​

  • パス: /api/webhooks/stripe、/api/webhooks/square
  • 署名検証必須
  • テナント解決: provider_customer_id または metadata.tenant_id から逆引き
  • 受信イベントは webhook_events テーブルに保管（再処理 / 監査用）

Google Calendar 連携 ​

連携モデル ​

  • ユーザー単位で OAuth 認証（テナント単位ではない）
  • リフレッシュトークンを暗号化保存
  • 同期対象カレンダーを1つ選択（または複数）

同期方針 ​

方向仕組み
CRM → Googleスケジュール作成 / 更新 / 削除を即時 API 反映
Google → CRMPush通知（Channels）か定期 incremental sync

注意点 ​

  • Google Push の Webhook URL は HTTPS 必須、有効期限あり → 期限前に renew 処理
  • 競合時は最終更新優先（updated 時刻ベース）
  • 連携解除時は external_event_id を残す / クリアするを設定で選べるようにする

共通ストレージ: Cloudflare R2 ​

  • 書類 / 画像 / 添付ファイルは R2 へ
  • アップロードは 署名付き URL をフロントに発行 → 直接 PUT
  • ダウンロードも署名付き URL（短時間）
  • メタデータは FILES テーブルで管理

監視 / 運用 ​

  • 連携の失敗は integration_errors テーブル + 管理画面で可視化
  • 重要連携（決済）は失敗時に Slack / メール通知（後続）
  • ダッシュボードで Webhook の処理量・エラー率を可視化（後続）

未確定 ​