# member.ose.tw 前端架構（可直接開工版）

## 1. 前端責任邊界
- 站點：`member.ose.tw`
- 主要責任：
  - 顯示目前登入使用者資訊
  - 顯示目前使用者權限快照
  - 透過管理 API 執行 grant/revoke
- 不處理：
  - Authentik 管理 API 直連
  - 密碼重設流程（導向 Authentik）

## 2. 建議技術堆疊
- Vue 3 + Vite + JavaScript
- Vue Router
- Pinia
- Axios
- Element Plus + Tailwind

## 3. 建議目錄結構
- `frontend/src/main.js`
- `frontend/src/router/index.js`
- `frontend/src/stores/`
  - `auth.js`：token、me、登入狀態
  - `permission.js`：snapshot 與快取
- `frontend/src/api/`
  - `http.js`：axios instance + interceptor
  - `me.js`
  - `permission-admin.js`
- `frontend/src/pages/`
  - `profile/MePage.vue`
  - `permissions/PermissionSnapshotPage.vue`
  - `permissions/PermissionAdminPage.vue`
- `frontend/src/types/`
  - `api.js`

## 4. 路由規劃（第一版）
- `/me`
  - 顯示 `GET /me` 資料
- `/me/permissions`
  - 顯示 `GET /me/permissions/snapshot`
- `/admin/permissions`
  - grant/revoke 表單與結果顯示

## 5. Token 與 Header 策略
- 使用者路由（`/me*`）
  - header: `Authorization: Bearer <authentik_access_token>`
- 管理路由（`/admin*`）
  - headers:
    - `X-Client-Key`
    - `X-API-Key`
- 建議：
  - 使用 axios request interceptor 統一注入 header
  - 401 時統一導向登入或刷新流程

## 6. 狀態管理最小模型
- `auth store`
  - `accessToken: string | null`
  - `me: { sub, email, display_name } | null`
  - actions: `setToken`, `fetchMe`, `logout`
- `permission store`
  - `snapshot: { authentik_sub, permissions[] } | null`
  - actions: `fetchMySnapshot`, `grantPermission`, `revokePermission`

## 7. 錯誤處理規則
- `401`
  - 使用者 token 過期或無效，導回登入
- `403`
  - API client 白名單限制（origin/ip/path）
- `404`
  - revoke 時 user 不存在
- `503`
  - 後端必要設定缺失（例如 internal secret / authentik admin）

## 8. 開工順序（建議）
1. 建立 axios client 與 interceptor
2. 完成 `/me` 與 `/me/permissions` 畫面
3. 完成 grant/revoke 表單
4. 補通知、loading、錯誤提示

詳細 request/response 契約請看 `docs/FRONTEND_API_CONTRACT.md`。

## 9. 本地開發環境
- Vite 會自動讀取 `frontend/.env.development`
- 已預設：
  - `VITE_API_BASE_URL=http://127.0.0.1:8000`