docs: add frontend handoff architecture and index

docs/FRONTEND_API_CONTRACT.md

@@ -0,0 +1,120 @@
+# Frontend API Contract（memberapi）
+
+Base URL：`https://memberapi.ose.tw`
+
+## 1. 使用者資訊
+### GET `/me`
+Headers:
+- `Authorization: Bearer <access_token>`
+
+200 Response:
+```json
+{
+  "sub": "authentik-sub-123",
+  "email": "user@example.com",
+  "display_name": "User Name"
+}
+```
+
+401 Error:
+```json
+{ "detail": "missing_bearer_token" }
+```
+或
+```json
+{ "detail": "invalid_bearer_token" }
+```
+
+## 2. 我的權限快照
+### GET `/me/permissions/snapshot`
+Headers:
+- `Authorization: Bearer <access_token>`
+
+200 Response:
+```json
+{
+  "authentik_sub": "authentik-sub-123",
+  "permissions": [
+    {
+      "scope_type": "site",
+      "scope_id": "tw-main",
+      "module": "campaign",
+      "action": "view"
+    }
+  ]
+}
+```
+
+## 3. Grant 權限
+### POST `/admin/permissions/grant`
+Headers:
+- `X-Client-Key: <client_key>`
+- `X-API-Key: <plain_api_key>`
+
+Request:
+```json
+{
+  "authentik_sub": "authentik-sub-123",
+  "email": "user@example.com",
+  "display_name": "User Name",
+  "scope_type": "site",
+  "scope_id": "tw-main",
+  "module": "campaign",
+  "action": "view"
+}
+```
+
+200 Response:
+```json
+{
+  "permission_id": "uuid",
+  "result": "granted"
+}
+```
+
+## 4. Revoke 權限
+### POST `/admin/permissions/revoke`
+Headers:
+- `X-Client-Key: <client_key>`
+- `X-API-Key: <plain_api_key>`
+
+Request:
+```json
+{
+  "authentik_sub": "authentik-sub-123",
+  "scope_type": "site",
+  "scope_id": "tw-main",
+  "module": "campaign",
+  "action": "view"
+}
+```
+
+200 Response:
+```json
+{
+  "deleted": 1,
+  "result": "revoked"
+}
+```
+
+404 Response:
+```json
+{ "detail": "user_not_found" }
+```
+
+## 5. Health Check
+### GET `/healthz`
+200 Response:
+```json
+{ "status": "ok" }
+```
+
+## 6. 常見錯誤碼
+- `401 invalid_client`
+- `401 invalid_api_key`
+- `401 client_expired`
+- `403 origin_not_allowed`
+- `403 ip_not_allowed`
+- `403 path_not_allowed`
+- `503 internal_secret_not_configured`
+- `503 authentik_admin_not_configured`