會員管理前端整合

本文件描述 Cortex Management 串接會員管理後端 MVP 的最小契約。所有 endpoint 都需要 admin Bearer token。

頁面資料流

主列表呼叫 GET /api/admin/members/investment-overview，顯示會員、membership state 與投資資料 counts。
點選會員後，依 tab 分別呼叫 GET /api/admin/members/{member_id}/investment-detail?section=...；不要一次預抓三個 section。
等級管理使用 GET /api/admin/memberships；未來排程時，畫面需同時顯示 effective_tier 與 assigned_tier。
設定等級使用 PUT /api/admin/members/{member_id}/membership，日期必須送含 offset 的 ISO 8601。
權限矩陣先讀 GET /api/admin/membership-tiers?include_inactive=true，保存時把該 tier 的完整 features、rate_limits 與原 updated_at 傳回 PUT。
API 紀錄 tab 沿用 GET /api/admin/access-logs?member_id=...。

Membership 顯示規則

effective_tier：此刻真正授權使用的 tier。
assigned_tier：後端選出的目前／下一筆管理排程；可能是未來 tier。
state=scheduled 時，不可把 assigned_tier 顯示成已生效；例如 effective 為 Advance、assigned 為 Premium。
ends_at 是不含端點；時間一到會立即 fallback free。
PUT response changed=false 代表 idempotent replay，UI 可視為成功，不需警告。

錯誤處理

HTTP / code	UI 行為
400 `INVALID_MEMBERSHIP_TIER`	重新載入 tier 選項並提示不可指派 inactive/reserved tier
404 `MEMBER_NOT_FOUND`	關閉 detail，重新整理列表
409 `MEMBERSHIP_TIER_VERSION_CONFLICT`	重新 GET tier permissions，要求管理員確認後再存
403 `FEATURE_LIMIT_REACHED`	會員操作畫面顯示已達方案上限
503 `MEMBERSHIP_CONFIGURATION_INVALID` / `MEMBERSHIP_SCHEMA_MISSING`	顯示系統設定或 migration 尚未完成，不提供猜測值
422	對應欄位顯示 validation message，特別檢查 timezone 與完整 permission keys

權限欄位

Boolean：ai_analysis、portfolio_export。
Integer limits：max_watchlists、max_watchlist_items；-1 顯示「無限制」。max_watchlist_items 是會員跨所有 groups 的總上限，UI 不可顯示成每個 group 的獨立額度。
Rate-limit settings：requests_per_minute、daily_analyses；本版僅可管理，會員級 distributed counter 尚未啟用。
admin 是 inactive reserved permission set，只能設定功能，不能指派給會員。

Detail 空資料

三個 section 都以 total=0, items=[] 表示空資料。Watchlists 的空 group 不是空資料：它會回一列，item_id、ticker 等 item 欄位為 null。

部署相依

後端上線前必須先在 live PostgreSQL 套用 migration 110，再部署 API 並重啟 scheduler；否則會員授權會依設計 fail-closed 回 503 MEMBERSHIP_SCHEMA_MISSING。若 application rollback，保留 migration 110 與既有 entitlement 資料，不執行 down migration。