member-platform/docs/FRONTEND_ARCHITECTURE.md

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*）
  • 登入用 POST /auth/login（帳號密碼）取得 access token
  • header: Authorization: Bearer <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