docs: add frontend handoff architecture and index

docs/FRONTEND_ARCHITECTURE.md

@@ -1,55 +1,81 @@
-# member.ose.tw 前端架構（Vue）
+# member.ose.tw 前端架構（可直接開工版）
 
-## 1. 角色定位
-- 網域：`member.ose.tw`
-- 功能：會員中心前台（管理 users/公司/站台/權限）
-- 注意：密碼流程不在這裡做，自動導 Authentik flow
+## 1. 前端責任邊界
+- 站點：`member.ose.tw`
+- 主要責任：
+  - 顯示目前登入使用者資訊
+  - 顯示目前使用者權限快照
+  - 透過管理 API 執行 grant/revoke
+- 不處理：
+  - Authentik 管理 API 直連
+  - 密碼重設流程（導向 Authentik）
 
-## 2. 技術棧
-- `Vue 3 + Vite`
-- `Element Plus`
-- `Tailwind CSS`
-- `Vue Router`
-- `Pinia`（建議）
+## 2. 建議技術堆疊
+- Vue 3 + Vite + TypeScript
+- Vue Router
+- Pinia
+- Axios
+- Element Plus + Tailwind
 
-## 3. 建議目錄
+## 3. 建議目錄結構
 - `frontend/src/main.ts`
-- `frontend/src/router/`
+- `frontend/src/router/index.ts`
 - `frontend/src/stores/`
-- `frontend/src/api/`（axios client + modules）
+  - `auth.ts`：token、me、登入狀態
+  - `permission.ts`：snapshot 與快取
+- `frontend/src/api/`
+  - `http.ts`：axios instance + interceptor
+  - `me.ts`
+  - `permission-admin.ts`
 - `frontend/src/pages/`
-  - `users/`
-  - `companies/`
-  - `sites/`
-  - `permissions/`
-- `frontend/src/components/`
+  - `profile/MePage.vue`
+  - `permissions/PermissionSnapshotPage.vue`
+  - `permissions/PermissionAdminPage.vue`
+- `frontend/src/types/`
+  - `api.ts`
 
-## 4. 第一版頁面
-- 使用者列表/搜尋
-- 公司列表
-- 站台列表
-- 權限指派（user x scope x module x action）
+## 4. 路由規劃（第一版）
+- `/me`
+  - 顯示 `GET /me` 資料
+- `/me/permissions`
+  - 顯示 `GET /me/permissions/snapshot`
+- `/admin/permissions`
+  - grant/revoke 表單與結果顯示
 
-## 5. 權限與登入
-- 透過 Authentik OIDC 登入
-- 前端持有 backend session/token，不直接操作 Authentik admin API
-- 「修改密碼 / 忘記密碼」按鈕導 Authentik 使用者流程頁
+## 5. Token 與 Header 策略
+- 使用者路由（`/me*`）
+  - header: `Authorization: Bearer <authentik_access_token>`
+- 管理路由（`/admin*`）
+  - headers:
+    - `X-Client-Key`
+    - `X-API-Key`
+- 建議：
+  - 使用 axios request interceptor 統一注入 header
+  - 401 時統一導向登入或刷新流程
 
-## 6. API 串接
-- `VITE_API_BASE_URL=https://memberapi.ose.tw`
-- 所有請求帶上必要 auth header
-- 管理操作走 `memberapi` 的 admin 路由
+## 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. UI/互動規則
-- Element Plus 做表單/表格/對話框
-- Tailwind 做 spacing/layout/快速樣式
-- 權限編輯畫面要清楚顯示：
-  - scope_type（company/site）
-  - scope_id
-  - module
-  - action（view/edit）
+## 7. 錯誤處理規則
+- `401`
+  - 使用者 token 過期或無效，導回登入
+- `403`
+  - API client 白名單限制（origin/ip/path）
+- `404`
+  - revoke 時 user 不存在
+- `503`
+  - 後端必要設定缺失（例如 internal secret / authentik admin）
 
-## 8. 第一版不做項目
-- 不做密碼重設畫面
-- 不做複雜儀表板
-- 不做跨系統 SSO 管理 UI
+## 8. 開工順序（建議）
+1. 建立 axios client 與 interceptor
+2. 完成 `/me` 與 `/me/permissions` 畫面
+3. 完成 grant/revoke 表單
+4. 補通知、loading、錯誤提示
+
+詳細 request/response 契約請看 `docs/FRONTEND_API_CONTRACT.md`。