From db0b4545cb50c00170356bab1ad8c69d01b01ce0 Mon Sep 17 00:00:00 2001
From: Chris <wtc.justin82@gmail.com>
Date: Sun, 29 Mar 2026 23:29:49 +0800
Subject: [PATCH] docs: add frontend and backend task plans

---
 docs/ARCHITECTURE_AND_CONFIG.md |  4 ++++
 docs/TASKPLAN_BACKEND.md        | 35 +++++++++++++++++++++++++++++++++
 docs/TASKPLAN_FRONTEND.md       | 33 +++++++++++++++++++++++++++++++
 docs/index.md                   |  4 ++++
 4 files changed, 76 insertions(+)
 create mode 100644 docs/TASKPLAN_BACKEND.md
 create mode 100644 docs/TASKPLAN_FRONTEND.md

diff --git a/docs/ARCHITECTURE_AND_CONFIG.md b/docs/ARCHITECTURE_AND_CONFIG.md
index 9126d33..ac1ae3e 100644
--- a/docs/ARCHITECTURE_AND_CONFIG.md
+++ b/docs/ARCHITECTURE_AND_CONFIG.md
@@ -19,6 +19,10 @@
   - 前端 API request/response 契約
 - `docs/FRONTEND_IMPLEMENTATION_CHECKLIST.md`
   - 前端實作與交付核對清單
+- `docs/TASKPLAN_FRONTEND.md`
+  - 前端任務進度與驗收條件
+- `docs/TASKPLAN_BACKEND.md`
+  - 後端任務進度與驗收條件
 - `docs/API_CLIENTS_SQL.sql`
   - `api_clients` 白名單表與初始資料 SQL
 
diff --git a/docs/TASKPLAN_BACKEND.md b/docs/TASKPLAN_BACKEND.md
new file mode 100644
index 0000000..efebef4
--- /dev/null
+++ b/docs/TASKPLAN_BACKEND.md
@@ -0,0 +1,35 @@
+# Backend TaskPlan
+
+## 目標
+提供可被前端穩定串接的 memberapi，包含身份驗證、權限快照、權限管理與 Authentik 同步能力。
+
+## 已完成
+- [x] FastAPI 專案骨架與分層（api/service/repository/model）
+- [x] `GET /healthz`
+- [x] `GET /me`
+- [x] `GET /me/permissions/snapshot`
+- [x] `POST /admin/permissions/grant`
+- [x] `POST /admin/permissions/revoke`
+- [x] `POST /internal/users/upsert-by-sub`
+- [x] `GET /internal/permissions/{authentik_sub}/snapshot`
+- [x] `POST /internal/authentik/users/ensure`
+- [x] API client 驗證（`X-Client-Key` + `X-API-Key`）
+- [x] Authentik JWT 驗證（JWKS）
+- [x] DB schema 初始化 SQL + migration SQL
+- [x] 基本測試與 lint
+
+## 進行中（建議近期）
+- [ ] 增加 Alembic migration 正式流程
+- [ ] 補齊更多 API 測試（admin/internal success + fail cases）
+- [ ] 增加 request id / logging 格式
+
+## 待辦（上線前）
+- [ ] 加入 rate limit（依 client 或 IP）
+- [ ] 針對 admin API 加 audit log（授權/撤銷行為）
+- [ ] 加上 CORS 白名單與反向代理配置驗證
+- [ ] 製作部署腳本（systemd / container）
+
+## 驗收條件
+- [ ] 前端可完成 `/me` + `/me/permissions/snapshot` + grant/revoke 全流程
+- [ ] 401/403/404/503 錯誤碼與文件一致
+- [ ] 至少一輪 staging smoke test 通過
diff --git a/docs/TASKPLAN_FRONTEND.md b/docs/TASKPLAN_FRONTEND.md
new file mode 100644
index 0000000..3dfc864
--- /dev/null
+++ b/docs/TASKPLAN_FRONTEND.md
@@ -0,0 +1,33 @@
+# Frontend TaskPlan
+
+## 目標
+完成 member.ose.tw 前端（Vue3 + JS + Vite + Element Plus + Tailwind），可獨立完成登入、查看個人資料、查看權限、管理授權。
+
+## 已完成（依目前程式）
+- [x] Vite + Vue3 專案結構
+- [x] Element Plus + Tailwind 基礎接入
+- [x] Router 與頁面骨架
+- [x] `LoginPage`（token 輸入）
+- [x] `MePage`（`GET /me`）
+- [x] `PermissionSnapshotPage`（`GET /me/permissions/snapshot`）
+- [x] `PermissionAdminPage`（grant/revoke）
+- [x] Pinia store（auth + permission）
+- [x] Axios 分離 user/admin client
+- [x] Production build 可通過
+
+## 進行中（建議近期）
+- [ ] 補路由守衛策略（是否限制 `/admin/permissions` 需登入）
+- [ ] 錯誤訊息 i18n 與統一顯示格式
+- [ ] 新增操作完成後自動刷新快照的 UX
+
+## 待辦（上線前）
+- [ ] 增加 e2e / UI smoke 測試
+- [ ] 優化 bundle size（目前 main chunk 偏大）
+- [ ] 加入環境切換策略（dev/staging/prod）
+- [ ] 加入登入來源與 token 取得說明頁
+
+## 驗收條件
+- [ ] 未登入時導向登入頁行為正確
+- [ ] 登入後可穩定讀取 `/me` 與快照
+- [ ] 管理頁 grant/revoke 成功與錯誤提示完整
+- [ ] 與後端契約文件一致（`FRONTEND_API_CONTRACT.md`）
diff --git a/docs/index.md b/docs/index.md
index 8e06ba7..e6e7937 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,6 +10,10 @@
 - `docs/BACKEND_ARCHITECTURE.md`
 - `docs/BACKEND_BOOTSTRAP.md`
 
+## 任務管理
+- `docs/TASKPLAN_FRONTEND.md`
+- `docs/TASKPLAN_BACKEND.md`
+
 ## SQL 與配置
 - `docs/API_CLIENTS_SQL.sql`