連絡先管理概要

連絡先管理は Vintage サービスが担当し、店舗ごとの顧客情報を管理します。

連絡先の構造

フィールド	型	説明
`id`	UUID	連絡先 ID
`shopId`	UUID	所属店舗
`name`	text	氏名
`index`	text	フリガナ（50音インデックス）
`phones`	text[]	電話番号配列
`emails`	text[]	メールアドレス配列
`tags`	text[]	タグ配列
`userType`	text	ユーザー種別
`groupIds`	text[]	所属グループ ID 配列
`memo`	text	メモ
`userId`	text	Vault ユーザー ID（認証連携）

CRUD 操作

連絡先作成

Vintage RPC: createContact({
  shopId, name, index, phones?, emails?,
  tags?, userType, groupIds?, memo?
})

purelovers 未連携の連絡先を作成した場合、自動的に NO_PURELOVERS_USER のチャットNG が設定されます。

連絡先更新

Vintage RPC: updateContact({
  id, shopId, name?, index?, memo?,
  phones?, emails?, tags?, userType?, groupIds?
})

連絡先削除

Vintage RPC: deleteContact({ id, shopId })

連絡先詳細取得

Vintage RPC: getContact({ id, shopId })

詳細取得では以下の関連データも含まれます:

purelovers 連携情報
チャットNG ステータス
マージ候補（電話番号・メールの重複検出）

連絡先一覧

フィルタリング

フィルタ	パラメータ	説明
50音インデックス	`index`	フリガナの先頭文字
ユーザー種別	`userType`	customer, prospect 等
タグ	`tag`	タグ名で完全一致
グループ	`groupId`	グループ ID
キーワード検索	`search`	名前・電話番号・メールで部分一致

ページネーション

カーソルベースのページネーションを使用します。

{
  contacts: Contact[];
  nextCursor: string | null;
  hasMore: boolean;
}

連絡先マージ

2つの連絡先を統合する機能です。

Vintage RPC: mergeContacts({ id, targetContactId, shopId })

マージルール

データ	マージ方法
電話番号	両方の配列を結合（重複除去）
メールアドレス	両方の配列を結合（重複除去）
タグ	両方の配列を結合（重複除去）
グループ	両方の配列を結合（重複除去）
メモ	結合（改行区切り）
チャットルーム	ソース連絡先のルームを対象に移行

マージ後、ソース連絡先は削除されます。

purelovers 連携

連絡先は purelovers のユーザーデータと連携できます。

連携データ

フィールド	説明
`pureloversUserId`	purelovers 側のユーザー ID
`pureloversShopId`	purelovers 側の店舗 ID
`displayName`	purelovers 上の表示名
`profileImageUrl`	プロフィール画像
`lastSyncedAt`	最終同期日時

連携フロー

purelovers から Tap Gateway 経由でセッションが作成される際に、連絡先と contact_purelovers が自動作成されます。

詳細は purelovers 連携を参照してください。

アバター

連絡先のアバター画像は以下の優先度で取得されます:

purelovers のプロフィール画像（contact_purelovers.profileImageUrl）
連絡先に直接設定された画像
デフォルトアバター

Vintage RPC: getContactAvatar({ id, shopId })
→ { image: string | null, isPurelovers: boolean }

Counter での表示

連絡先一覧画面

┌──────────────────────────────────┐
│ 顧客リスト                       │
├──────────┬───────────────────────┤
│ [50音]   │ プロフィール / チャット │
│ あ か さ │                       │
│          │ 名前: 田中太郎         │
│ [フィルタ]│ 電話: 090-xxxx-xxxx  │
│ タグ     │ タグ: VIP, 常連       │
│ グループ │                       │
│          │ [チャット] タブ        │
│ [検索]   │                       │
├──────────┴───────────────────────┤
│ ボトムナビ                       │
└──────────────────────────────────┘

モバイル: 一覧と詳細が画面遷移で切り替わる
デスクトップ: 2カラムレイアウトで同時表示
プロフィールタブとチャットタブを切り替え

連絡先管理 概要