グループとラベル

連絡先のグループ管理は2つの仕組みで構成されます: 手動グループ（KV Storage）と スマートラベル（Cellar DB）。

---

手動グループ

概要

グループ定義は Cloudflare KV (CONTACT_GROUPS) に店舗ごとに保存されます。連絡先のグループ所属は、連絡先レコードの groupIds 配列で管理されます。

グループ構造

フィールド	型	説明
id	string	グループ ID
name	string	グループ名
icon	string	アイコン識別子
color	string	バッジ背景色
textColor	string	バッジ文字色
criteria	object	スマートグループ条件（任意）
order	number	表示順序

KV キーの形式

groups:{shopId}

値は Group[] の JSON 配列です。

CRUD 操作

Vintage RPC: listGroups({ shopId })
Vintage RPC: getGroup({ id, shopId })
Vintage RPC: createGroup({ shopId, name, icon, color, textColor?, criteria?, order })
Vintage RPC: updateGroup({ id, shopId, name?, icon?, color?, textColor?, criteria?, order? })
Vintage RPC: deleteGroup({ id, shopId })
Vintage RPC: reorderGroups({ shopId, groupIds })

連絡先のグループ操作

Vintage RPC: addContactToGroup({ id, groupId, shopId })
Vintage RPC: removeContactFromGroup({ id, groupId, shopId })

連絡先の groupIds 配列に追加/削除します。

スマートグループ

criteria フィールドが設定されたグループは「スマートグループ」として動作します。一括配信のターゲティング時に、criteria の条件を動的に評価して対象を決定します。

// スマートグループの criteria 例
{
  tags: ['VIP', '常連'],
  userType: ['customer']
}

---

スマートラベル

概要

ラベルはタグの組み合わせ条件を定義する仕組みで、Cellar DB の label テーブルに保存されます。ラベル同士をネストすることで、最大3階層の条件定義が可能です。

ラベル構造

フィールド	型	説明
id	UUID	ラベル ID
shopId	UUID	店舗 ID
name	text	ラベル名
color	text	バッジカラー
description	text	説明
logic	text	AND, OR, NOR, NAND
tags	text[]	タグ条件配列
labels	text[]	子ラベル ID 配列

論理演算子

演算子	意味	例
AND	全てのタグを持つ	VIP かつ 常連
OR	いずれかのタグを持つ	VIP または 常連
NOR	いずれのタグも持たない	VIP でも 常連 でもない
NAND	全てのタグは持たない	VIP と 常連 の両方は持たない

階層制限

Lv1: タグのみを参照するラベル
Lv2: Lv1 ラベルを参照するラベル
Lv3: Lv1/Lv2 ラベルを参照するラベル（最大深度）

循環参照の検出とLv3を超える深度の防止がUI側で実装されています。

CRUD 操作

Vintage RPC: listLabels({ shopId })
Vintage RPC: createLabel({ id, shopId, name, color?, description?, logic?, tags?, labels? })
Vintage RPC: deleteLabel({ id, shopId })

createLabel は Upsert（UPSERT）で動作するため、更新にも使用します。

---

Counter での表示

タグ・ラベル管理画面

┌──────────────────────────────────┐
│ タグ・ラベル管理                  │
├──────────────────────────────────┤
│ ■ ラベル                         │
│ ┌────────────────────────┐      │
│ │ VIP会員     Lv1  [編集]│      │
│ │ AND: VIP, 来店5回以上   │      │
│ └────────────────────────┘      │
│ ┌────────────────────────┐      │
│ │ 優良顧客    Lv2  [編集]│      │
│ │ OR: VIP会員, 高額購入者 │      │
│ └────────────────────────┘      │
│                                  │
│ [+ 新規ラベル作成]                │
│                                  │
│ ■ タグ（読み取り専用）            │
│ VIP (12) | 常連 (8) | 新規 (25)  │
└──────────────────────────────────┘

ラベル作成フォーム

• ラベル名（必須）
• 説明（任意）
• 論理演算子（AND / OR / NOR / NAND）
• タグ選択（マルチセレクト）
• 子ラベル選択（Lv3 以下のみ）
• カラーピッカー（12色パレット）

視覚的な階層表示

レベル	ボーダースタイル
Lv1	静的な青ボーダー
Lv2	回転する青→紫グラデーション（8秒）
Lv3	回転する赤→紫グラデーション（8秒）

---

タグの管理

タグは連絡先に直接付与される文字列ラベルです。

タグの特徴

• 自由入力: 事前定義不要。連絡先編集時に任意のタグを追加
• 店舗スコープ: タグは店舗内で共有
• 一覧取得: 店舗内の全連絡先で使用されているユニークタグを取得

Vintage RPC: getContactTags({ shopId })
→ { tags: string[] }

タグの用途

用途	説明
連絡先フィルタリング	連絡先一覧のタグフィルタ
ラベル条件	スマートラベルの条件要素
グループ条件	スマートグループの条件要素
配信ターゲティング	一括配信の対象者絞り込み

---

関連ページ

• 連絡先管理 概要 - 連絡先 CRUD
• ターゲティング - 配信でのグループ・ラベル使用
• Vintage RPC メソッド - グループ・ラベル RPC
• Cellar ラベルテーブル - ラベル DB スキーマ