排班主管 · 08

新增主管

為新主管建立 FREONE 帳號，並授予指定 Merchant 或 Squad 的管理權限。

完成結果陳小文副理取得台北信義店外場 Squad manager 權限，可管理該組別。

實際案例

要新增 manager.chen@example.com 陳小文副理，管理台北信義店外場。因為管理範圍只有單一組別，選擇 Squad scope；若要管理全店才選 Merchant scope。

管理層級	unit	scope 應填的 ID
組織（全集團）	organization	Organization ID，例如 tjticx
商家（單店）	merchant	Merchant ID，例如台北信義店的 tkfv5t
組別（例如外場）	squad	Squad ID，例如台北信義店外場的 sqmmhw5vonCzo

unit 決定管理層級，scope 必須填該層級對應的 ID，不能填名稱或其他層級的 ID。本例要管理外場組，所以 unit 是 squad，scope 是外場的 Squad ID sqmmhw5vonCzo，不是台北信義店的 Merchant ID。

資料流

1. 1決定管理範圍本例只管理台北信義店外場，因此選 Squad scope。business decision
2. 2解析 scope ID由 Squad 清單取得台北信義店外場 ID sqmmhw5vonCzo。GET /v1/squads
3. 3建立主管使用 manager 角色建立帳號與初始 scope。POST /v1/managers
4. 4保存主管 ID保存回應中的 manager ID，供後續調整 profile 與 roles。response mapping
5. 5回讀驗證確認 email、姓名及外場 Squad manager role。GET /v1/managers

欄位 mapping

業務資料	FREONE 欄位	本例值
主管 Email	email	manager.chen@example.com
主管姓名	name	陳小文副理
權限角色	roles[].role	manager
管理層級	roles[].unit	squad
管理範圍	roles[].scope	sqmmhw5vonCzo（外場 Squad ID）

Request

POST /v1/managers
Content-Type: application/json

{
  "email": "manager.chen@example.com",
  "name": "陳小文副理",
  "roles": [
    {
      "scope": "sqmmhw5vonCzo",
      "unit": "squad",
      "role": "manager"
    }
  ]
}

Response

建立完成後會回傳主管 ID 與是否需要重設初始密碼：

{
  "data": {
    "id": "9itv2cd6-702a-owid-876d-mdo28vbna76e",
    "needResetPassword": true
  }
}

再以 GET /v1/managers 回讀權限：

{
  "data": [
    {
      "id": "9itv2cd6-702a-owid-876d-mdo28vbna76e",
      "email": "manager.chen@example.com",
      "title": "外場主管",
      "name": "陳小文副理",
      "nickname": "Love",
      "portrait": "https://example.com/portraits/manager-chen-002.png",
      "roles": [
        {"scope": "sqmmhw5vonCzo", "role": "manager", "unit": "squad"}
      ]
    }
  ]
}

驗收結果

• 已保存 9itv2cd6-702a-owid-876d-mdo28vbna76e 作為後續角色更新識別。
• 回讀只有預期的 squad/sqmmhw5vonCzo/manager 初始權限。
• Service Account 本身有權管理該 Squad scope。

能力邊界

公開 POST /v1/managers 目前只接受 Merchant 或 Squad scope。若要新增不存在的 Organization 主管，請到 FREONE 後台操作；不要改呼叫內部 Backstage API。