需排班員工 · 02

修改員工資料

完整更新組員基本資料，並保留身份別與既有技能指派。

完成結果王小明的暱稱與員工編號已更新；綁定手機號碼、正職身份別、清潔技能與組別維持原設定。

實際案例

HRIS 通知原員工編號 S0001 的王小明，暱稱改為「阿明」、員工編號改為 Q0008。這筆 enrollment 已綁定手機號碼 +886900000011，不可修改；FREONE 中原有的正職身份別及等級 3 的清潔技能也必須在更新 profile 時一起送回，避免清除技能。

資料流

1. 1找到組員以 merchantId 與原 externalId S0001 精確查詢，取得 enrollment ID 和現有 profile。GET /v1/enrollments
2. 2保留標籤保留現有 identityTag.id 和每筆 skills 的 tagId、level；新增技能時才查詢商家可用標籤。GET /v1/identity-tags/{merchantId} + skill-tags
3. 3組合完整 profile替換暱稱與 externalId，保留已綁定手機號碼、姓名、正兼職、身份別和技能。business mapping
4. 4更新並回讀送出完整 profile，再按 merchantId 與新 externalId Q0008 查詢驗證。PUT /v1/enrollment/{id}/profile

欄位 mapping

欄位	本次送出值	來源
Path enrollmentId	a571cbd6-8795-4ccd-924b-63097c77314c	現有 enrollment
name	王小明	現有資料，保留
alias	阿明	HRIS 新值
phone	+886900000011	現有已綁定手機號碼，保留
parttime	false	現有資料，保留
externalId	Q0008	HRIS 新員工編號，原值 S0001
identityTagId	65107fa0-4284-46a5-82f7-b3657f660ed1	現有 identityTag.id，保留
skills[0]	清潔 tagId、level: 3	現有技能指派，保留

Request

PUT /v1/enrollment/a571cbd6-8795-4ccd-924b-63097c77314c/profile
Content-Type: application/json

{
  "name": "王小明",
  "alias": "阿明",
  "phone": "+886900000011",
  "parttime": false,
  "externalId": "Q0008",
  "identityTagId": "65107fa0-4284-46a5-82f7-b3657f660ed1",
  "skills": [
    {"tagId": "4f2b126d-eccf-44aa-b98a-dd2ac1879d12", "level": 3}
  ]
}

Response

以下是依新增員工範例資料推導的更新後結果：

{
  "data": {
    "id": "a571cbd6-8795-4ccd-924b-63097c77314c",
    "externalId": "Q0008",
    "name": "王小明",
    "alias": "阿明",
    "phone": "+886900000011",
    "parttime": false,
    "connected": true,
    "merchant": {
      "id": "tkfv5t",
      "name": "台北信義店"
    },
    "identityTag": {
      "id": "65107fa0-4284-46a5-82f7-b3657f660ed1",
      "name": "正職"
    },
    "skills": [
      {"tagId": "4f2b126d-eccf-44aa-b98a-dd2ac1879d12", "level": 3}
    ],
    "createdTime": "2026-09-15T02:00:00Z",
    "updatedTime": "2026-09-29T02:00:00Z",
    "activatedTime": "2026-09-24T16:00:00Z",
    "activatedBy": {
      "id": "a9da86bb-e7a7-4779-a8e4-f61c40e72553",
      "name": "IT串接服務帳號"
    },
    "squads": [
      {
        "id": "sqmmhw5vonCzo",
        "name": "外場",
        "shiftSurveyEligible": true,
        "dayOffSurveyEligible": true
      }
    ],
    "suspension": null
  }
}

驗收結果

• 以 merchantId=tkfv5t、externalId=Q0008 回讀時，alias 是阿明；已綁定的 phone 仍為 +886900000011，enrollment ID 不變。
• identityTag.id 仍是正職，skills 仍有清潔技能且等級為 3。
• squads 與 activatedTime 不受 profile 更新影響。

關鍵提醒

當 connected: true 時，表示該手機號碼已在小橘 App 綁定登入，號碼無法修改。若要更換手機號碼，請使用新增員工流程，以新號碼建立組員，不要透過 PUT /profile 修改原有 phone。

PUT /profile 不是局部修改。name、alias、phone、parttime、externalId 與 identityTagId 都須送出；本例的 phone 須沿用現有值。skills 若省略、傳 null 或 []，會清除所有既有技能。這支 API 不修改組別、啟用時間或停權狀態。