Swagger API 文檔
完整 API 規格、參數說明，可直接測試各端點
MCC（Member Control Center） 是一套多租戶會員管理中心， 專為需要管理多個獨立組織、企業、單位或社群（統稱 Group）的平台營運者所設計。 每個 Group 代表一個獨立的租戶，旗下可建立多個 Service（應用程式或前台服務）； 每個 Service 可自行啟用不同的第三方身分提供者（IdP），讓各自的使用者以 Google、LINE、Facebook、Apple、Microsoft 或 GitHub 帳號登入。
MCC 的核心職責是：代理 IdP 驗證流程、建立並管理會員身分、發放 Token、驗證 Session。 您的前後端只需與 MCC 對接，無需自行串接各 IdP 的 OAuth 細節。
⚠️ 會員身分以 Group 為隔離單位：相同 email 在不同 Group 下屬於完全獨立的會員，資料互不共用。
MCC_CLIENT_ID、MCC_CLIENT_SECRET，並把前端回調網址加入 Redirect 白名單。{issuer}/.well-known/openid-configuration——換票 / session / refresh 全交給它自動處理。GROUP_JWT + SERVICE_CODE 呼叫 POST /member/check 確認 session 有效，並以 id_token 的 sub 當帳號主鍵。member_suuid（= id_token 的 sub），此為判斷「同一使用者」的唯一依據。sub（= member_suuid），不要用 emailsub 是會員的穩定全域唯一 ID，同一會員每次登入都不變 → 用它當你系統裡的帳號主鍵 / 外鍵。sub（路徑 A：id_token）＝ member_suuid（路徑 B：exchange 回傳），是同一個值。sub。sub）——這是設計上的預期行為。❌ findUser({ where: { email } }) // 同一人可能被建成多個帳號
✅ findUser({ where: { mccSub } }) // 找不到才建立；email / name 只當「可更新屬性」| 你會看到的名字 | 實際是什麼 | 用在哪 |
|---|---|---|
service_suuid ＝ MCC_CLIENT_ID ＝ client_id | 同一個 UUID（服務的 suuid） | 前端啟動登入 / 後端 OAuth 換票 |
member_suuid ＝ id_token 的 sub | 同一個值（會員唯一 ID） | 當你系統的帳號主鍵 |
GROUP_JWT ＋ SERVICE_CODE | 一組後端專用憑證（成對使用） | 後端呼叫 /member/check、/auth/idp/exchange |
本文件是前後端整合的主要參考。整合前請確認：
GROUP_JWT、SERVICE_CODE、MCC_CLIENT_ID、MCC_CLIENT_SECRETresponse_mode=diag，登入失敗會直接在 MCC 端 render 完整錯誤頁（含修正建議），不會被前端框架吞成 generic error。詳見路徑 A 整合指南的「整合除錯模式」
串接 MCC 一律使用正式網址：https://members.managers.center。
測試與正式不是用不同網址區分，而是用不同 group 區分：
| 用途 | 怎麼做 |
|---|---|
| 測試 | 開一個「測試 group」，你所有產品都在這個 group 底下測試 |
| 正式 | 另開一個「正式 group」 |
兩個 group 各自有獨立的 MCC_CLIENT_ID / MCC_CLIENT_SECRET / GROUP_JWT / SERVICE_CODE，資料與會員完全隔離；切換時只換這組憑證即可，網址不變。
MCC 為標準 OIDC Provider（RFC 6749 + OIDC Core 1.0）。NextAuth、oidc-client-ts、AppAuth 等任何 OIDC 函式庫皆可直接對接。
/.well-known/openid-configurationGET /oauth/authorizePOST /oauth/token（Basic auth）client_id = ServiceClient.suuid（UUID，全域唯一）前端直接呼叫 /auth/idp/{provider}/start，MCC 完成 IdP 驗證後帶一次性 code 導回前端，再由後端持 Group Bearer 兌換 accessToken。
GET /auth/idp/{provider}/startPOST /auth/idp/exchange（Group Bearer）response_mode=diag，
MCC 會直接顯示完整診斷頁（含上游 IdP 原始錯誤與修正建議）。僅整合期使用，正式環境一律 code。
詳見 路徑 A 整合指南。
登入完成後，前端取得 member_suuid 與 access_token。
【後端】每次呼叫重要 API 時，後端必須向 MCC 驗證會員 session 仍有效——MCC 是 session 的唯一真實來源。
Authorization: Bearer {access_token} 及 X-Member-Suuid: {member_suuid}
POST /member/check，帶上
GROUP_JWT + SERVICE_CODE + 會員憑證，確認 session 是否存活
{ success, data: { member_suuid, email, display_name, ttl } }；
ttl 為 session 剩餘秒數，success: false 表示已登出或 token 無效
ServiceClient.expires_at。
合約到期後，POST /oauth/token（路徑 A）與 POST /member/check（兩條路徑）
分別回傳 invalid_grant / group_contract_expired，前端應呼叫 signOut。
登入 MCC Manager，建立群組與服務後點「產生 Bearer Token」（同步更新 ServiceClient.expires_at 合約期）。
SERVICE_CODE、GROUP_JWT、合約有效期redirect_uri 加入白名單（需完全匹配，含協定+域名+路徑）MCC_CLIENT_ID（= service.suuid，UUID）與 MCC_CLIENT_SECRET；
明文僅顯示一次，請立即存入環境變數
MCC 支援以下六種第三方登入。在 MCC Manager 服務 → IdP 設定頁面啟用並填入各 provider 的 Client ID 與 Secret。
https://members.managers.center/auth/callbackresponse_mode=form_post，callback 是 HTTP POST 而非 GET。在 Apple Developer 後台將此 URL 加入 Return URLs 時須選 POST。路徑 A（推薦）：設定 NextAuth（或任何 OIDC client）指向 MCC discovery URL； OIDC client 自動處理 redirect / 換票 / session / refresh。
路徑 B：前端導向 /auth/idp/{provider}/start?service_suuid=...&redirect_uri=...&response_mode=code，
回調頁取得 code 後傳給後端兌換。
【前端】呼叫後端時帶 access_token（路徑 A：Bearer token；路徑 B：從 session 取出）與 member_suuid。
【後端】執行業務邏輯前，以 Group Bearer 呼叫 POST /member/check 確認 session 有效。
| 參數 | 說明 | 使用位置 |
|---|---|---|
MCC_CLIENT_ID |
OIDC client_id（= ServiceClient.suuid，全域唯一 UUID） | 後端環境變數 |
MCC_CLIENT_SECRET |
OIDC client_secret（重設後僅顯示一次） | 後端環境變數 |
GROUP_JWT |
群組 Bearer Token（用於 /member/check、/auth/idp/exchange；不用於 /oauth/token） | 後端環境變數 |
SERVICE_CODE |
服務代碼（X-Service-Code，與 GROUP_JWT 搭配） | 後端環境變數 |
service_suuid |
服務識別碼（路徑 B 啟動登入用，值等於 MCC_CLIENT_ID） | 前端可見 |
⚠️ MCC_CLIENT_SECRET、GROUP_JWT、SERVICE_CODE 為高敏感資訊，
務必僅存於後端環境變數，絕不暴露於瀏覽器或前端原始碼。
client_id 必須使用 service.suuid（UUID 字串），不可用人類可讀的 service.aud。
跨群組同名 aud 時 /oauth/token 會回 ambiguous_client_id。