StaffDto 參考

員工從業人員資料模型參考 POS串接

本文的對象
本文適用於透過 API、MCP 處理 ReceiptRoller 員工（Staff）主檔的開發者。說明與 POS 負責人資訊的關聯，以及交易資料的「負責員工」解析邏輯。

StaffDto 是 ReceiptRoller 的員工（Staff）主檔的正規模型。用於排班管理、打卡、營業額負責人的彙總、人事費計算等。以商業帳戶為單位管理，可指派至底下的多個店鋪。

與顧客（CrmCustomerDto）完全分開管理。顧客是來店客，員工是在店鋪工作的從業人員。

欄位	型別	內容
`OrganizationId`	string	商業帳戶 ID。PartitionKey。
`StaffId`	string	RR 內部的員工 ID（GUID）。RowKey。
`UserId`	string	與 RR 使用者帳戶的關聯（選填）。供未來的員工登入用。有 `IsLinkedToUser` 輔助屬性。
`EmployeeNumber`	string	員工編號（店鋪營運者使用的編號）。
`LastName` / `FirstName`	string	姓、名。有 `FullName` 屬性。
`DisplayName`	string	顯示名稱。姓、名為空時使用的後備（暱稱式）。

欄位	內容
`Position`	職稱（店長、副店長、員工等）。自由文字。
`EmploymentType`	`FullTime`（正職員工）/ `PartTime`（兼職、工讀）/ `Contract`（約聘員工）/ `Other`。以 `EmploymentTypeDisplayName` 本地化。
`HourlyRate`	時薪（decimal）。以 `FormattedHourlyRate` 整理成「¥1,200/時」格式。
`HireDate`	入職日。
`AssignedStoreIds`	所屬店鋪 ID 的逗號分隔。可以 `AssignedStoreIdList` 作為陣列讀寫。

Phone、Email、DateOfBirth、Address、ProfileImageUrl。緊急聯絡人為 EmergencyContactName / EmergencyContactPhone / EmergencyContactRelation。

欄位	內容
`SquareTeamMemberId`	Square Team 的 Team Member ID。將 RR 員工與 Square 負責人關聯的明示連結。可用 `StaffService.FindBySquareTeamMemberIdAsync()` 反查。

Smaregi 的情況，目前版本中 StaffDto 端並未持有專用欄位，而是直接參照交易明細的 StaffId（Smaregi 內部 ID）。詳情請參閱 Smaregi 員工資料的對應。

Notes（自由文字）、IsActive（已離職為 false）、CreatedAt、UpdatedAt。

POS 交易（PosTransactionDto）中包含負責員工的 ID 與姓名。將其解析為 RR 的 StaffDto 的方法因 POS 而異。

Square：以 StaffDto.SquareTeamMemberId 比對交易的 team_member_id。需要事先在 RR 端建立員工，並輸入 Square 的 Team Member ID。
Smaregi：將交易的 staffId（Smaregi 內部 ID）與 staffName 直接用於報表顯示或營業額彙總。與 RR 的 StaffDto 的自動比對在目前版本尚未支援。