# 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
```json
{ "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. `GET /internal/permissions/{user_sub}/snapshot`（相容路徑，回 role 聚合資料）
9. `POST /internal/provider/users/ensure`
10. `POST /internal/idp/users/ensure`（舊路徑相容，不建議新串接使用）
11. `POST /internal/keycloak/users/ensure`（舊路徑相容，不建議新串接使用）

## 角色聚合回應（`GET /internal/users/{user_sub}/roles`）
```json
{
  "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_name": "campaign_edit",
      "provider_role_name": "campaign_edit"
    }
  ]
}
```

## 注意事項
- 不提供 user direct role 寫入 API。
- User 最終角色由 `user_sites` + `site_roles` 推導。