Smaregi會員資料與ReceiptRoller顧客資料的對應關係

Smaregi 會員顧客資料 POS連動資料對應

Smaregi的會員主檔資料，在完成與ReceiptRoller的連動後，會自動轉換並匯入至ReceiptRoller的顧客資料（CrmCustomerDto）中。本文將整理欄位層級的對應關係，以及Smaregi特有的注意事項。

會員資訊的雙向同步機制本身（時機、衝突發生時的優先順序、疑難排解）請參閱Smaregi、Square的會員資訊雙向同步。本文純粹是聚焦於「哪個欄位對應到哪裡」的技術文件。

Smaregi（`SmaregiCustomer`）	ReceiptRoller（`CrmCustomerDto`）	備註
`customerId`	— （保存於PosCustomerLink）	Smaregi內部ID。ReceiptRoller端並非儲存於Customer，而是儲存在連結資料表 `PosCustomerLinkEntity` 的 `vendorIdentifier` 中。
`customerCode`	`MembershipCode`	Smaregi的會員代碼（門市經營者一般使用的編號）。直接採用作為ReceiptRoller的會員編號。
`lastName` / `firstName`	`LastName` / `FirstName`	原樣轉錄。因Smaregi標準規格無假名欄位，`LastNameKana` / `FirstNameKana` 留空。
`email`	`Email`	轉為小寫、去除前後空白後正規化儲存。
`mobileNumber` 或 `phoneNumber`	`Phone`	優先採用行動電話號碼（`mobileNumber`）。若為空值，則採用 `phoneNumber`。正規化為E.164格式（`+819012345678`）。

在Smaregi標準會員欄位中，以下項目在目前版本中並不會匯入至ReceiptRoller端。

地址（PostalCode / Prefecture / City / Address1 / Address2）— 因Smaregi標準欄位中不含地址資訊。需在ReceiptRoller端另行登錄，否則將維持空值。
生日（DateOfBirth）— Smaregi Platform API的標準會員回應中並不包含此欄位。僅在本人透過ReceiptRoller App登錄時才會保留。
性別（Gender）— 同上。
姓名假名（LastNameKana / FirstNameKana）— 因Smaregi標準欄位中無此欄位，故留空。

從Smaregi收到新的會員資料時，ReceiptRoller端會依下列順序進行與既有顧客的同一人判定。

若三者皆未比對成功，則會以新顧客的形式新增至CRM。若比對成功，則既有顧客的資訊會被更新（欄位層級的last-write-wins）。

會員新增、更新（Smaregi → ReceiptRoller）：透過Smaregi的Webhook於數秒內反映至CRM。
定期備援：為應對Webhook未送達的情況，每1小時取得會員主檔的差異資料。
ReceiptRoller → Smaregi：當App內顧客完成會員登錄或資料更新的瞬間，向Smaregi登錄的作業便會加入佇列。通常會在數秒至數分鐘內完成反映。

若在Smaregi端實體刪除會員資料，ReceiptRoller端的比對將失效。建議在Smaregi中改用邏輯刪除（停用）。
若日後變更Smaregi端的 customerCode，ReceiptRoller端的 MembershipCode 比對將會中斷，並有可能被視為新顧客處理。變更代碼時，請確保能透過電子郵件地址或電話號碼進行比對，並同時維持這兩個欄位。
假名姓名、地址、生日等僅ReceiptRoller端持有的欄位，不會回寫至Smaregi。這些欄位是配合Smaregi端的欄位結構所致。