# Frontend API Contract（memberapi）

Base URL：`https://memberapi.ose.tw`

## 0. OIDC 登入
- `GET /auth/oidc/url?redirect_uri=...`
- `POST /auth/oidc/exchange`

## 1. 使用者資訊
- `GET /me`
- `GET /me/permissions/snapshot`

`permissions` item:
```json
{
  "scope_type": "company|site",
  "scope_id": "company_key_or_site_key",
  "system": "mkt",
  "module": "mkt.campaign",
  "action": "view"
}
```

## 2. 權限（User 直接授權）
Headers:
- `X-Client-Key`
- `X-API-Key`

### POST `/admin/permissions/grant`
```json
{
  "authentik_sub": "authentik-sub",
  "email": "user@example.com",
  "display_name": "User",
  "scope_type": "company",
  "scope_id": "ose-main",
  "system": "mkt",
  "module": "campaign",
  "action": "view"
}
```

### POST `/admin/permissions/revoke`
```json
{
  "authentik_sub": "authentik-sub",
  "scope_type": "site",
  "scope_id": "tw-main",
  "system": "mkt",
  "module": "campaign",
  "action": "view"
}
```

說明：
- `module` 可省略，代表系統層權限，後端會使用 `system.__system__`。
- `module` 有值時會組成 `{system}.{module}` 存入（例如 `mkt.campaign`）。

## 3. 主資料管理（admin）
Headers:
- `X-Client-Key`
- `X-API-Key`

- `GET/POST/PATCH /admin/systems`
- `GET/POST/PATCH /admin/modules`
- `GET/POST/PATCH /admin/companies`
- `GET/POST/PATCH /admin/sites`
- `GET /admin/members`
- `POST /admin/members/upsert`
- `PATCH /admin/members/{authentik_sub}`

## 4. 會員與群組關聯（由會員頁管理）
Headers:
- `X-Client-Key`
- `X-API-Key`

- `GET /admin/members/{authentik_sub}/permission-groups`
- `PUT /admin/members/{authentik_sub}/permission-groups`
```json
{
  "group_keys": ["site-ops", "mkt-admin"]
}
```

## 5. 權限群組（一組權限可綁多個 user）
Headers:
- `X-Client-Key`
- `X-API-Key`

- `GET/POST/PATCH /admin/permission-groups`
- `GET /admin/permission-groups/{group_key}/permissions`
- `POST /admin/permission-groups/{group_key}/permissions/grant`
- `POST /admin/permission-groups/{group_key}/permissions/revoke`

群組授權 payload 與 user 授權 payload 相同（用 `system/module/scope/action`）。

## 6. 直接授權列表（權限管理頁）
Headers:
- `X-Client-Key`
- `X-API-Key`

- `GET /admin/permissions/direct?keyword=&scope_type=&limit=&offset=`
- `DELETE /admin/permissions/direct/{permission_id}`

## 7. Internal 查詢 API（其他系統）
Headers:
- `X-Internal-Secret`

- `GET /internal/systems`
- `GET /internal/modules`
- `GET /internal/companies`
- `GET /internal/sites`
- `GET /internal/members`
- `GET /internal/permissions/{authentik_sub}/snapshot`

## 8. 常見錯誤
- `401 invalid_client`
- `401 invalid_api_key`
- `401 invalid_internal_secret`
- `404 system_not_found`
- `404 company_not_found`
- `404 site_not_found`
- `400 invalid_permission_id`