# Admin / Client UI 拆分工作計劃

## 目標

- 在同一個 `MemberCenter.Web` 專案中，將會員端與管理端 UI 明確分區。
- 保持單一登入入口與單一帳號系統。
- 讓具有 `admin` 權限的帳號同時可使用會員功能與管理功能。
- 將目前偏向後台的共用介面，調整為 client-first 的會員中心體驗。
- 補齊會員註冊、Google 第三方登入與訂閱資料銜接流程。

## 已確認決策

### 帳號與登入

- `Admin` 與 `Client` 共用同一個登入入口。
- `Admin` 帳號同時也是會員帳號，可使用會員介面功能。
- 不拆成兩套認證系統，不建立獨立 admin login。

### UI 與導覽

- 會員端為主介面。
- 功能選單採分組方式呈現。
- 一般會員只看到會員功能。
- 具有 `admin` role 的帳號，額外看到 `Admin` 功能分類。
- `Admin` 分類展開後顯示管理功能連結。
- 目前先以 `admin` role 做整包顯示，不先做細權限切分。

### 未授權存取

- 非 admin 使用者存取 `/admin/*` 時，回應 `404`。
- 不使用 `403` 頁面暴露後台存在。

## 目標範圍

### 本次要做

- 調整 `MemberCenter.Web` 路由與結構，將管理端移入 `Areas/Admin`。
- 將現有共用 layout 改為 client-first 導覽。
- 將 admin 功能從全站共用導覽中抽離，改成 role-based 顯示。
- 建立 admin 路由未授權時回 `404` 的處理方式。
- 補上會員註冊、第三方登入與訂閱綁定的工作規劃。

### 本次不做

- 細粒度權限模型，例如依功能模組拆 `tenant.read`、`audit.read`。
- 獨立的 `AdminWeb` / `ClientWeb` 專案拆分。
- 大幅重做視覺設計。
- API 權限模型重構。
- 註冊確認信寄送實作。

## 實作策略

### 策略原則

- 先切 UI 邊界，再保留既有 Identity 與 role policy。
- 先做低風險結構重整，不同時引入細權限與大幅 UI redesign。
- 保持既有 URL 慣例，避免不必要的 route breakage。

### 預期結構

```text
src/MemberCenter.Web/
├── Areas/
│   └── Admin/
│       ├── Controllers/
│       └── Views/
├── Controllers/              # client only
├── Views/
│   ├── Shared/
│   │   ├── _Layout.cshtml    # client-first layout
│   │   └── ...
│   └── ...
```

## 分階段計劃

### Phase 0: 會員註冊與帳號銜接規格補齊

狀態：已完成

目標：先將會員建立、第三方登入與訂閱資料綁定的規則固定，避免後續 UI 與 auth 重構互相衝突。

#### 需求規則

- 會員帳號以 `email` 為主要識別。
- `UserName` 強制等於 `Email`。
- 不提供獨立 username。
- 本地註冊完成後，帳號標記為未認證。
- 本階段先不寄送確認信。
- 未認證帳號仍可登入。
- 後續功能完整後，未認證帳號將可被限制部分功能；本階段先保留此狀態與擴充空間。
- 支援 Google 作為第一個第三方登入/註冊 provider。
- Google 第一次登入時，若系統已存在相同 email 的本地帳號，直接 auto-link。
- Google 回傳 email 即使未驗證，仍允許建立帳號或連接既有帳號。
- 使用者若先以本地帳號註冊，之後再以 Google 同 email 登入，應連接到同一個帳號，不建立第二個 user。
- 註冊成功後，若系統中已有相同 email 的訂閱資料，需將相關 `newsletter_subscriptions.user_id` 補上。
- 訂閱綁定時必須保留既有訂閱狀態與偏好，不可覆蓋。
- 訂閱綁定完成後需補一筆 audit log。
- 後續若導入事件，保留發送 `subscription.linked_to_user` 的擴充空間。

#### 子工作

- 已完成：定義本地註冊後的帳號狀態與登入規則。
- 已完成：定義 Google external login / register / auto-link 流程。
- 已完成：定義訂閱資料綁定與 audit log 寫入時機。
- 已完成：將上述規則同步反映到目前的 Web / API 實作階段。
- 已完成：`subscription.linked_to_user` 事件發送。
- 註記：未認證帳號的功能限制屬後續能力擴充，不阻擋本 phase 完成。
- 註記：Google 實際整合驗證仍需提供 Google OAuth 設定，屬外部驗證條件，不阻擋本 phase 完成。

完成條件：

- 註冊、Google 登入、同 email 帳號連接、訂閱綁定規則均有明確定義。
- 後續 Phase 1 之後的 UI 與 auth 重構可直接依規則實作。

### Phase 1: Route 與目錄切分

狀態：已完成

目標：先建立清楚的 UI 邊界。

- 將現有 `Controllers/Admin/*` 移入 `Areas/Admin/Controllers/*`。
- 將現有 `Views/Admin/*` 移入 `Areas/Admin/Views/*`。
- 調整 route 設定，讓 `/admin/*` 由 area route 處理。
- 確認既有 admin URL 可維持不變。

完成條件：

- 所有 admin 頁面由 `Areas/Admin` 提供。
- 會員端 controller 不再與 admin controller 混在同一層。

### Phase 2: Layout 與導覽切分

狀態：已完成

目標：把 UI 改成 client-first，不再全站露出後台功能。

- 重構共用 layout，移除固定顯示的 admin 連結。
- 建立 client-first 功能選單。
- 若使用者具 `admin` role，顯示 `Admin` 功能分類。
- `Admin` 分類底下先列出既有管理功能：
  - Tenants
  - Newsletter Lists
  - Subscriptions
  - OAuth Clients
  - Audit Logs
  - Security
  - Blacklist

完成條件：

- 一般會員不會在主選單看到 admin 連結。
- admin 使用者可從同一套主介面展開進入管理功能。

### Phase 3: Admin 畫面容器整理

狀態：已完成

目標：讓進入 admin 區後有明確上下文。

- 規劃 admin area 是否使用獨立 layout。
- 若使用獨立 layout，保留回會員區入口。
- 若先共用 layout，至少在 admin 頁面標示目前位於管理區。

建議：

- 第一版可先採用共用主殼 + admin 區塊標示。
- 若後續 admin 功能持續增長，再抽 `_AdminLayout`。

目前進度：

- 已完成：獨立 `Admin` area layout。
- 已完成：保留回會員區入口。
- 已完成：admin shell 基礎結構整理（top bar、side nav、active state、區域標示）。
- 已完成：補上可替換的基礎樣式 hooks，避免後續設計重做時需要拆 route 或 view 結構。
- 註記：後續若需進一步整理 admin/client 的整體體驗、內容層級、表格與表單版型，視為 UI/UX refinement，不阻擋本 phase 完成。

完成條件：

- 使用者進入 admin 頁面時，有清楚的區域辨識。

### Phase 4: 未授權存取改為 404

狀態：已完成

目標：保留授權檢查，同時隱藏 admin surface。

- 保留 `[Authorize(Policy = "Admin")]`。
- 增加 admin 未授權時的統一處理，避免顯示預設 `403`。
- 確認未登入與已登入但非 admin 的行為符合預期。

已定案：

- 未登入進 `/admin/*`：直接回 `404`
- 已登入但非 admin 進 `/admin/*`：直接回 `404`

目前進度：

- 已完成：保留 `[Authorize(Policy = "Admin")]`。
- 已完成：admin 未授權時不顯示預設 `403`，改為 `404`。
- 已完成：目前實作上，未登入與非 admin 存取 `/admin/*` 均回 `404`。
- 已完成：將「未登入也回 `404`」正式定案並同步到工作計劃。

### Phase 5: 驗證與文件更新

狀態：已完成

目標：確保重構後行為可驗證、文件一致。

- 驗證會員端主要頁面仍可正常使用。
- 驗證 admin 帳號可以：
  - 使用會員功能
  - 看見 `Admin` 選單
  - 進入 admin 各頁
- 驗證非 admin 帳號無法看見 admin 選單，且直接進 admin URL 會得到 `404`
- 更新 README / UI 文件中的 web 結構描述

目前進度：

- 已完成：`dotnet build MemberCenter.sln -m:1`
- 已完成：會員端主要頁面可用性驗證（首頁 / login / register）。
- 已完成：admin 帳號操作驗證（可登入、可進 member profile、可進 admin route）。
- 已完成：一般會員登入驗證（可登入、可進 profile、首頁不顯示 admin 群組）。
- 已完成：非 admin / 未登入情境驗證（匿名打 `/admin/*` 回 `404`）。
- 已完成：計劃文件、README、UI / Flow / Use Case / Design / OpenAPI 相關文件更新。
- 註記：Google 真實 round-trip 驗證需提供 Google OAuth 設定，屬外部條件，不阻擋本 phase 完成。

## 影響檔案預估

- `src/MemberCenter.Web/Program.cs`
- `src/MemberCenter.Web/Views/Shared/_Layout.cshtml`
- `src/MemberCenter.Web/Controllers/Admin/*`
- `src/MemberCenter.Web/Views/Admin/*`
- 新增 `src/MemberCenter.Web/Areas/Admin/...`
- 視需要更新 `docs/UI.md`

## 風險與注意事項

- Area 導入後，view 路徑與 route mapping 容易有小錯誤，需要逐頁驗證。
- 若直接共用同一個 layout，需避免 client 與 admin 的語意混亂。
- `404` 偽裝策略要搭配真正的 authorization，不能只靠 route 隱藏。
- 若未登入也直接回 `404`，可能會讓合法 admin 使用者失去登入引導；這點需明確決策。

## 建議執行順序

1. 先完成 Phase 0，確認註冊、Google 登入與訂閱綁定規則。
2. 再完成 Phase 1，做純結構重整。
3. 接著做 Phase 2，修正選單與角色顯示。
4. 然後決定 Phase 3 要共用 layout 還是抽 admin layout。
5. 再做 Phase 4，補齊 `404` 授權行為。
6. 最後做 Phase 5 的驗證與文件更新。

## 本次文件用途

這份計劃作為後續逐步實作的工作底稿。後續每一步都應以「單一階段可驗證完成」為原則，避免一次改太多導致 routing、授權與 UI 問題混在一起。

## 目前總結

- 已完成：Phase 0、Phase 1、Phase 2、Phase 3、Phase 4、Phase 5
- 部分完成：Phase 5