member-platform/docs/INTERNAL_API_HANDOFF.md

Internal API Handoff（新模型）

Base URL

• Local: http://127.0.0.1:8000
• Prod: 由部署環境提供

Auth Headers（/internal/*）

• X-Client-Key: <client_key>
• X-API-Key: <api_key>

Common Error Response

{ "detail": "error_code" }

已實作端點

1. GET /internal/companies
2. GET /internal/sites
3. GET /internal/systems
4. GET /internal/roles
5. GET /internal/members
6. POST /internal/users/upsert-by-sub
7. GET /internal/users/{user_sub}/roles
8. POST /internal/provider/users/ensure

角色聚合回應（GET /internal/users/{user_sub}/roles）

{
  "user_sub": "xxxxxxxx",
  "roles": [
    {
      "site_key": "ST20260402X1234",
      "site_display_name": "OSE Main",
      "company_key": "CP20260402X5678",
      "company_display_name": "OSE",
      "system_key": "SY20260402X0001",
      "system_name": "Marketing",
      "role_key": "RL20260402X0002",
      "role_code": "mkt:marketing_card:edit",
      "role_name": "campaign_edit"
    }
  ]
}

注意事項

• 不提供 user direct role 寫入 API。
• User 最終角色由 user_sites + site_roles 推導。
• role_key 是唯一識別鍵；業務語意解析請使用 role_code。