Warren Chen 5752d649e0 feat: Enhance member center functionalities and API scopes

- Added subscription management for logged-in users, allowing them to view and unsubscribe from newsletters directly.
- Introduced profile maintenance features, enabling users to update personal information and manage addresses.
- Expanded API scopes for profile access, including read/write permissions for basic info, addresses, and subscriptions.
- Updated installation documentation to reflect new audience settings for authentication resources.
- Improved OpenAPI documentation with new profile scopes and authorization models.
- Created a comprehensive member upgrade plan outlining system settings, email verification, account roles, and subscription management.

2026-04-16 06:14:01 +09:00

20 KiB

Raw Blame History

會員中心升級規劃

此文件整理會員中心的目標升級架構，包含設定畫面、Email 驗證與忘記密碼、帳號分級與角色管理、會員主資料、訂閱管理，以及作為外部服務 Token / Auth 中心的整體模型。此文件以一次到位的最終設計為準，不再以過渡方案或分階段落地作為主軸。

目標

增加管理者可操作的系統設定畫面，涵蓋 SMTP、Send Engine 與 Auth 資源設定。
補齊 Email 驗證與忘記密碼的完整寄信流程。
建立帳號分級規則，明確區分 superuser、admin 與一般會員。
確立會員認證狀態模型，以「已認證 / 未認證」為會員狀態基礎。
第三方登入以 Google 為唯一支援 provider。
將「會員中心作為 Token / Auth 中心」的外部服務授權模型文件化，納入 Send Engine 與 File Access。
擴充會員個人資料、地址簿與會員端訂閱管理能力，並同步定義可供其他服務使用的 profile scopes。
補齊帳號生命週期、審計紀錄、rate limit 與 MFA 的基礎治理規則。

現況盤點

已存在

MemberCenter.Web 與 MemberCenter.Api 已有本地註冊、登入、忘記密碼、重設密碼、Email 驗證入口。
MemberCenter.Web/Controllers/AccountController.cs 已有：
- ForgotPassword
- ResetPassword
- VerifyEmail
- ExternalLogin / ExternalLoginCallback
MemberCenter.Api/Controllers/AuthController.cs 已有：
- POST /auth/register
- POST /auth/password/forgot
- POST /auth/password/reset
- GET /auth/email/verify
Google external login 已在 src/MemberCenter.Web/Program.cs 接入，並已支援同 email auto-link。
Installer 已可建立初始管理帳號，但角色模型仍需調整為文件定義的 superuser。
管理後台已有 /admin/security 畫面，目前僅提供 token 時效設定：
- AccessTokenMinutes
- RefreshTokenDays
MemberCenter.Web 已有 /profile 頁面，但目前僅顯示：
- Email
- Email 驗證狀態
- 建立時間
MemberCenter.Api 已有 GET /user/profile，但目前只提供基礎欄位，不足以支撐其他服務查詢完整會員資料。
docs/DESIGN.md / docs/FLOWS.md 已定義 File Access 流程：
- upload: client_credentials 取得 upload token 後由外部服務直連 file space
- download: 由業務服務驗權後再簽發短效 delegated download token
TokenController.ResolveResources() 已依 scope 決定 token audience，目前內建：
- member_center_api
- send_engine_api

部分實作

忘記密碼與 Email 驗證目前已有 token 產生與驗證邏輯，但尚未接入實際郵件寄送。
SendEngine__BaseUrl、SendEngine__WebhookSecret 已有設定來源與 options binding，但尚未進入可編輯的管理畫面。
系統目前已有 admin role policy，但尚未明確拆出 superuser 與「由 superuser 指派 admin」的完整流程。

待補項

SMTP 設定的持久化、管理 UI 與寄信服務抽象。
Email 驗證信與忘記密碼信的正式寄送流程。
會員狀態與角色管理規則文件化，並同步到 UI/API/Installer 行為。
帳號管理畫面與權限控制。
File Access 的 OAuth client usage、scope、audience 與 delegated token 發放流程尚未落地到程式。
Token resource / audience 的設定方式目前仍偏硬編碼，尚未抽象成可擴充模型。
會員個人資料欄位、地址簿、個人資料 API 與 scope 尚未定義。
會員端缺少「我的訂閱」頁面，無法在登入後集中管理已訂閱的電子報。

功能規劃

1. 系統設定畫面

1.1 主要新增項

新增獨立的「系統設定」或「整合設定」畫面。
第一批可編輯設定：
- SMTP Host
- SMTP Port
- SMTP Username
- SMTP Password
- SMTP From Name
- SMTP From Address
- SMTP Enable SSL / TLS
- SendEngine__BaseUrl
- SendEngine__WebhookSecret

1.2 可一併納入的既有設定

目前 /admin/security 已有的 token 時效設定可整併進同一個設定體系：
- Access token 分鐘數
- Refresh token 天數
SendEngineWebhookOptions.SubscriptionEventsPath 目前已有預設值 /webhooks/subscriptions，若未來有多環境或反向代理差異，可評估是否也納入設定畫面。

1.3 暫不建議放入設定畫面的項目

ConnectionStrings__Default
Auth__Issuer
PathBase
Google OAuth Client Secret

以上屬部署層級或高風險設定，建議仍以環境變數或部署設定管理，不在一般管理 UI 直接編輯。

1.4 設定保存策略

所有可運行期調整的設定統一收斂到 DB，例如沿用 system_flags 或新增專用設定表。
敏感值至少需要：
- UI 遮罩顯示
- 審計紀錄
- 更新權限限制
Secret 類設定需明確區分：
- 可明文顯示的設定
- 僅能覆寫、不可回顯的 secret 類設定

2. Email 驗證與忘記密碼

2.1 目標狀態

註冊後自動寄送 Email 驗證信。
使用者可重新發送驗證信。
忘記密碼送出後寄送 reset password email。
Web UI 與 API 共享同一套 token 與寄信服務邏輯。

2.2 目前已有的基礎

Identity token provider 已可產生：
- email confirmation token
- password reset token
Web 與 API 已有 verify/reset endpoint。
View 已存在：
- ForgotPassword
- ResetPassword
- VerifyEmailResult

2.3 待補實作

郵件發送 abstraction，例如 IEmailSender。
SMTP provider 實作與設定綁定。
註冊後觸發發送驗證信。
忘記密碼改為寄送信件，而不是在畫面或 API 直接回傳 token。
Email 樣板：
- 驗證信
- 忘記密碼信
重送驗證信入口。

2.4 安全與產品規則

忘記密碼 API 與 UI 都應避免暴露帳號是否存在。
Reset token 與 verify token 的 URL 應統一由設定的 public base URL 組出。
驗證信與重設密碼信都應記錄 audit log。
會員未驗證時是否允許登入與可操作範圍，需在實作時明確固定為單一規則，不保留模糊狀態。

3. 帳號分級與角色管理

3.1 角色模型

superuser
- 只能透過 installer 建立或提升。
- 可管理所有帳號角色。
- 可授予或移除 admin。
admin
- 必須先以一般會員身分註冊。
- 再由 superuser 手動授權。
- 不可自行提升其他帳號為 admin，除非後續明確擴權。
member
- 預設註冊身分。
- 依 Email 驗證狀態再分為：
  - unverified
  - verified

3.2 會員分級原則

會員狀態以「已認證 / 未認證」為基礎。
若未來擴充，可在不破壞既有角色模型下新增：
- VIP / 付費會員
- 停權 / 凍結
- 企業帳號等級

3.3 對現行實作的調整方向

現行 admin role 應重新定義：
- Installer 建立的高權限帳號應直接改為 superuser。
- 管理後台中的角色治理操作應為 superuser 專屬。
需要新增帳號管理頁面，至少包含：
- 查詢帳號
- 檢視 Email 驗證狀態
- 指派或移除 admin
- 顯示是否為 installer 建立之 superuser

3.4 權限規則

只有 superuser 可變更角色。
admin 可進入既有管理後台，但不可升降他人權限。
一般會員不可看見 /admin/*。
未來若導入更多後台功能，建議區分：
- 後台使用權限
- 帳號治理權限

3.5 帳號生命週期

帳號狀態至少包含：
- active
- disabled
- locked
Email 驗證狀態獨立於帳號狀態，維持：
- unverified
- verified
Email 為對外主識別 key，不允許修改。
若使用者要更換 email，採重新註冊新帳號，不提供原帳號改 email 流程。
後台需保留帳號停用能力；停用後不得再登入與取得新 token。
建議記錄帳號治理欄位：
- last_login_at
- last_seen_at
- disabled_at
- disabled_by
superuser 重設他人密碼、停用帳號、解除停用等治理規則，先記入規劃，細節待後續檢討。

4. 第三方登入

只支援 Google。
目前 Google external login 已存在，後續只補齊與整體權限模型的一致性。
若 Google 回傳 email 已驗證，可直接把會員標記為 verified；目前 AccountProvisioningService 已有依 external login provider 回填 EmailConfirmed 的基礎邏輯。

5. 會員基本資料與地址簿

5.1 會員基本資料

會員可自行維護的基本資料欄位包含：
- last_name
- first_name
- nick_name
- mobile_phone
- landline_phone
- date_of_birth
- gender
- 公司名稱
- 部門
- 職稱
- 公司電話
- 統一編號
- 發票抬頭
- remark
Email 為固定欄位，不提供變更流程；如需更換 email，採重新註冊。
Email 同時作為對外 API 的主 key。

建議必填欄位：

last_name
first_name

建議選填欄位：

nick_name
mobile_phone
landline_phone
date_of_birth
gender
company_name
department
job_title
company_phone
tax_id
invoice_title
remark

建議 enum：

gender
- male
- female
- other
- unspecified

欄位驗證建議：

first_name、last_name
- 必填
- 長度 1-100
nick_name
- 長度 0-100
mobile_phone、landline_phone、company_phone
- 儲存標準化字串
- 盡量接近 E.164，市話可接受本地格式輸入後正規化
company_name、department、job_title
- 長度 0-200
tax_id
- 長度 0-32
- 驗證以台灣統編規則為主，但 schema 保留國際延展空間
invoice_title
- 長度 0-200
remark
- 長度 0-1000
date_of_birth
- 使用 date 型別，不使用 datetime

資料使用原則：

first_name + last_name 為正式姓名來源
nick_name 為顯示用途，不作為唯一鍵
mobile_phone 優先於 landline_phone 作為主要聯絡電話

5.2 地址簿 / 收貨地址清單

新增會員地址簿概念，支援一位會員維護多筆地址。
地址欄位包含：
- label
- 收件人姓名
- 收件人電話
- country_code
- postal_code
- state_region
- city
- district
- address_line1
- address_line2
- 公司名稱（可選）
- 是否預設地址
- 地址用途
- address_meta_json
地址用途建議先預留列舉：
- shipping
- billing
- both
資料格式規則：
- 以台灣使用情境為主
- 國碼、電話、郵遞區號、國家碼等欄位盡量符合國際格式
- 統編以台灣統編規則為主
- 地址採「結構化欄位 + address_meta_json 補充資料」混合設計，不採純 JSON
刪除規則：
- 若會員只剩最後一筆地址，不允許刪除
- 若刪除的是預設地址，系統需自動補選新的預設地址

建議必填欄位：

user_id
label
recipient_name
recipient_phone
country_code
address_line1
usage
is_default

建議選填欄位：

postal_code
state_region
city
district
address_line2
company_name
address_meta_json

建議 enum：

usage
- shipping
- billing
- both

欄位驗證建議：

label
- 長度 1-100
recipient_name
- 必填
- 長度 1-100
recipient_phone
- 必填
- 儲存標準化字串
country_code
- 必填
- 使用 ISO 3166-1 alpha-2
- 固定 2 碼大寫
postal_code
- 長度 0-20
state_region、city、district
- 長度各 0-100
address_line1
- 必填
- 長度 1-255
address_line2
- 長度 0-255
company_name
- 長度 0-200
address_meta_json
- 可為 null

資料規則：

同一個 user_id + usage 最好限制只能有一筆 is_default = true
label 可為自由文字，不先做 enum
地址至少保留一筆，因此最後一筆不可刪除

5.3 資料治理原則

會員基本資料與地址簿屬於會員中心主資料，可供其他服務查詢，但寫入權限需嚴格控管。
會員本人可編輯自己的基本資料與地址簿。
其他服務預設只有讀取權限。
若其他服務需要代會員寫入，必須有額外 scope 與審計規則。

6. 會員資料 API 與 Auth Scope 規範

6.1 規劃目的

讓其他服務可透過 API 取得會員中心的基本資料與地址資料。
在一開始就把 scope 邊界定清楚，避免未來 profile API 無限制外放。

6.2 建議 scopes

profile:basic.read
- 讀取會員基本資料
profile:basic.write
- 更新會員基本資料
profile:addresses.read
- 讀取會員地址簿
profile:addresses.write
- 新增、修改、刪除會員地址簿
profile:subscriptions.read
- 讀取會員已訂閱電子報清單
profile:subscriptions.write
- 透過已登入會員介面取消訂閱或調整會員自己的訂閱狀態

6.3 API 邊界建議

其他服務 API：
- 目前規劃以 service API 為主
- 只要 Auth 設定有授與對應 scope，該服務即可存取對應資料
- 讀寫能力完全由 scope 控制
- 預設以最小權限授權，不因 client 類型自動放寬資料邊界
會員本人 UI / API：
- 可讀寫自己的 profile 與地址
- 可查看自己的訂閱清單
- 可對自己的訂閱直接退訂，不需再次 email token 確認
管理後台：
- 可查詢會員資料，但是否可編輯應另行定義，不與一般會員本人編輯權混用

6.4 與 OIDC 標準 scope 的關係

目前 openid email profile 中的 profile scope 太寬泛，不足以承載業務上需要的個資與地址簿授權控制。
建議保留 OIDC profile 作為基本 claims 用途，但業務資料改由自訂 scope 控制。

7. 會員端訂閱管理（我的訂閱）

7.1 目標

會員登入後，可集中查看自己目前已訂閱的電子報清單。
會員可直接從此介面取消訂閱，不需要再次透過 email token 驗證。
此流程與 email 內的一鍵退訂屬不同入口：
- email 退訂：適用未登入或直接從信件操作
- 會員中心退訂：適用已登入且已確認是本人

7.2 UI 能力

顯示已訂閱清單：
- 所屬 tenant / 站台
- 電子報清單名稱
- 訂閱狀態
- 訂閱建立時間
- 最後更新時間
可執行：
- 直接取消訂閱
- 未來可擴充為偏好調整或重新訂閱

7.3 流程規則

已登入會員對自己的訂閱執行退訂時，不需 email token 二次確認。
系統仍需：
- 驗證 subscription 確實屬於目前登入會員
- 寫入 audit log
- 發送 subscription.unsubscribed 事件
若該 email 已在黑名單中，行為需與既有退訂規則一致。
即使已綁定 user_id，仍保留既有以 list_id + email 進行訂閱 / 退訂的 public 流程。
會員可重新訂閱已退訂的電子報，規則與既有 public subscribe 流程保持一致。

7.4 與現行訂閱 API 的差異

現行 /newsletter/preferences 偏向以 list_id + email 操作，主要照顧跨站 API 邊界。
新的「我的訂閱」介面應改以登入者身份為主體，不再要求使用者自行輸入 email。
建議新增一組以 current user 為主體的 API，而不是把既有未登入流程硬改成同一支。

7.5 訂閱識別原則

Email 是訂閱領域的主 key。
user_id 為已註冊會員與訂閱資料的關聯鍵，不取代 email 在訂閱流程中的角色。
因此系統同時保留：
- public flow：list_id + email
- member flow：current user
兩種入口最終都回到同一組 subscription 資料。

8. 會員中心作為外部服務的 Token / Auth 中心

8.1 共通模型

Send Engine 與 File Access 本質上是同一套模型：
- 由 Member Center 簽發 access token
- 外部服務以 Member Center JWKS 驗簽
- 依 iss/aud/exp/scope/tenant_id 做授權與租戶邊界控制
差異只在資源類型不同：
- Send Engine 偏向 service-to-service API 呼叫
- File Access 除了 upload 的 S2S token 外，download 還需要 delegated short-lived token

8.2 File Access 納入規劃

新增 OAuth client usage，建議至少區分：
- file_api
- 或更明確拆成 file_upload_api / file_download_delegate
新增 scopes：
- files:upload.write
- files:download.read
- files:download.delegate
- files:delete
- files:metadata.read
新增 audience：
- file_access_api
新增 delegated token 規則：
- 下載 token 必須短效
- 必須綁定 tenant_id
- 必須綁定 file_id 或 object_key
- 必須綁定 method
- 不可直接重用一般 S2S access token 給 client

8.3 目標設計

Auth 資源設定採 resource registry，不再以一組一組 Auth__XAudience 擴充。
每個外部資源服務都以統一結構註冊：
- resource name
- audience
- scopes
- client usages
- 是否需要 tenant_id
- 是否允許 delegated token
新增資源服務時，只擴充 registry 與授權規則，不再修改硬編碼 audience 分支。
所有外部資料存取均以 scope 作為唯一授權依據。

8.4 授權模型

OAuth client usage 與 resource 綁定：
- tenant_api -> member_center_api
- send_api -> send_engine_api
- file_api -> file_access_api
scope 用於細粒度權限控制。
TokenController 依 scope 與 usage 對照 resource registry 計算 resources/audiences。
delegated token 與一般 S2S token 共用同一套 token issuing abstraction。

9. 審計紀錄

下列事件必須寫入 audit log：
- 註冊
- Email 驗證成功
- 忘記密碼申請
- 密碼重設成功
- 已登入修改密碼
- Google external login 綁定
- 角色變更
- 帳號停用 / 啟用
- profile 修改
- 地址簿新增 / 編輯 / 刪除 / 預設地址切換
- 會員端直接退訂
- 系統設定修改
- OAuth client 建立
- OAuth client secret 旋轉
OAuth client secret 顯示一次、旋轉與治理能力視為既有基線；細節之後再檢討。

10. Rate Limit 與防濫用

下列入口必須有 rate limit：
- login
- forgot password
- resend verification
- register
- public subscribe
- unsubscribe token 申請
- one-click unsubscribe token 申請
lockout 與 rate limit 需能區分：
- 人類使用者登入
- service API token 申請

11. MFA 與非本期項目

在 Email 寄送能力完成後，可規劃 Email-based MFA / challenge 驗證。
其餘先明確列為未來可補項：
- consent / terms acceptance
- 資料匯出 / 刪除
- login history / device management
- 通知偏好中心

一次到位的實作範圍

設定中心：
- SMTP
- Send Engine
- Auth 資源設定
- token lifetime
Identity 與通知：
- Email 驗證寄信
- 忘記密碼寄信
- 重送驗證信
會員主資料：
- 基本資料
- 地址簿
- Profile UI / API
訂閱管理：
- 我的訂閱頁
- current-user 型訂閱 API
- 直接退訂流程
權限與角色：
- superuser
- admin
- member + verified / unverified
- 帳號管理與角色指派
Auth 中心：

resource registry
profile scopes
file access scopes
delegated token

安全治理：
- audit log
- rate limit
- MFA 預留
文件、測試與 installer 同步調整

影響範圍

Web

新增設定畫面與表單。
新增帳號管理畫面。
調整註冊成功後導引與驗證提醒文案。
新增會員 profile 編輯頁、地址簿頁與我的訂閱頁。

API

若設定畫面走 API，需新增設定讀寫端點。
若帳號管理後台走 API，需新增角色管理與帳號查詢端點。
若要支援 File Access，需新增或擴充：
- resource / audience mapping
- file scopes 註冊
- delegated download token issuing
需新增 current-user 型 profile / addresses / subscriptions API 與對應 scopes。

Infrastructure

新增 SMTP sender 與設定存取服務。
調整帳號 provisioning 與角色管理服務。
抽出 token resource resolver / delegated token issuer，避免 audience 與 scope 判斷散落在 controller。
新增會員基本資料與地址簿的資料模型與服務層。

Installer

建立或提升 superuser。
視命名策略決定是否保留 add-admin，或改名為更貼近語意的指令。

文件與實作同步原則

文件中的「已存在」代表已有 controller / route / view / 基礎邏輯，不代表整體功能已完成產品化。
本規劃完成後，應同步回寫：
- docs/UI.md
- docs/FLOWS.md
- docs/INSTALL.md
- README.md

20 KiB Raw Blame History Unescape Escape