Smaregi員工資料與ReceiptRoller員工資料的對應關係

Smaregi 員工 POS連動資料對應

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

同步的操作方式是在員工畫面右上方選單中點選「與Smaregi同步」。詳細內容請參閱Smaregi的POS連動設定。

Smaregi `/pos/staffs`	ReceiptRoller（`StaffDto`）	備註
`staffId`	`SmaregiStaffId`	Smaregi內部ID。作為再次同步時的比對鍵。
`staffCode`	`EmployeeNumber`	以員工編號的形式儲存。
`staffName`	`LastName` + `FirstName` + `DisplayName`	以半形空白拆分為姓、名（例如「下田昌平」→ LastName=下田／FirstName=昌平）。若無空白，則LastName為完整字串，FirstName留空。DisplayName則原樣保留原始字串。
`email`	`Email`	若為空值，則保留ReceiptRoller端既有的數值。
`displayFlag`	`IsActive`	`"0"`（不顯示）者不列入同步對象。`"1"`則對應 `IsActive = true`。

受限於Smaregi /pos/staffs 端點的規格，以下ReceiptRoller端欄位並無對應資料，需在ReceiptRoller端另行登錄。這些欄位在再次同步時不會被覆寫。

電話號碼（Phone）
出生年月日（DateOfBirth）
到職日（HireDate）
雇用形態（EmploymentType）— 正職、兼職、約聘等
時薪（HourlyRate）
住址、緊急聯絡人
職稱（Position）— Smaregi會回傳 roleId，但因解析職稱名稱需要額外的端點，目前版本尚未支援
所屬門市（AssignedStoreIds）— Smaregi的 /pos/staffs 不會回傳門市指派資訊
姓名假名（LastNameKana / FirstNameKana）— StaffDto尚無對應欄位。未來新增 staffNameKana 時將會啟用

從Smaregi匯入員工資料時，僅會透過 SmaregiStaffId 的完全一致來比對既有員工。若不一致，則會以新員工的形式登錄。系統不會依姓名或員工編號進行自動合併。

Smaregi → ReceiptRoller：於員工畫面右上方選單點選「與Smaregi同步」手動執行。系統會從 /pos/staffs 取得所有員工資料，並以 SmaregiStaffId 比對後進行新增或更新。
再次同步時的行為：既有員工（相同 SmaregiStaffId）的 EmployeeNumber / LastName / FirstName / DisplayName / Email / IsActive 會被覆寫更新。而在ReceiptRoller端額外新增的 HourlyRate / HireDate / EmploymentType / Position / AssignedStoreIds ／緊急聯絡人等資料則會予以保留。
ReceiptRoller → Smaregi：目前版本尚未支援。在ReceiptRoller端登錄的員工資料不會自動反映至Smaregi。

只要事先同步好員工主檔，交易資料（PosTransactionDto）中所包含的 staffId 便能自動解析為ReceiptRoller的員工紀錄。如此一來，收據顯示及銷售負責人統計就能以「在ReceiptRoller登錄的員工姓名」呈現，而非「Smaregi內部ID」。

若尚未同步員工主檔，則會直接使用交易資料中所含的 staffName（Smaregi端顯示的姓名）。

若在Smaregi端實體刪除員工，該員工透過 SmaregiStaffId 的比對將失效。建議在Smaregi中改用 displayFlag 進行不顯示設定。
即使在ReceiptRoller端將員工設為 IsActive = false（離職狀態），過去交易資料的負責人解析仍會持續生效。請勿刪除離職員工的紀錄。
姓名的自動拆分僅為「以第一個空白分成兩段」的簡易處理。複姓或三個字以上的姓名，有可能會被拆分成非預期的結果。同步完成後可於ReceiptRoller端個別修正。
若一位員工需負責多間門市，請於同步後在ReceiptRoller端的 AssignedStoreIds 中設定多間門市。