Collfa 系統架構說明 (System Architecture)
本頁面定義 Collfa 的服務的技術核心包含資料模型、API 規範以及異常處理機制，核心運作邏輯、路由守護機制以及家庭群組的權限控制。
1. 基礎開發規範
API Base URL: https://api.collfa.com
認證機制: 除 Login 與 Register 接口外，其餘請求均須於 Header 帶入：
Authorization: Bearer {JWT_TOKEN}
時間規範: 系統統一採用 UTC (ISO-8601) 格式處理時間（如：Instant）。
2. 資料模型架構 (Data Models)
Collfa 的核心邏輯圍繞在「用戶」與「家庭群組」的關聯。
2.1 用戶體系 (User System)
UserAccount: 存儲核心帳號資訊（Email, Bcrypt 雜湊密碼）。
機制：Email 在存入資料庫前會強制執行 toLowerCase 與 trim 以避免重複。
UserProfile: 存儲個人化資訊，與 UserAccount 採 1:1 關聯。
欄位：姓名 (Name, 限制 30 字)、大頭貼 (Avatar URL)。
2.2 家庭群組 (Family Group)
FamilyGroup: 家庭群組核心實體。
關鍵機制：具備專屬的 joinCode (加入碼) 與 JoinPolicy (審核機制)。
角色鏈結：包含一名 Owner (擁有者)，目前規劃朝向多對多關聯發展。
限制：免費版 (FREE) 成員上限為 30 人。
3. 用戶訪問與路由邏輯 (Routing & Auth Flow)
系統採用 Token 進行身份驗證，前端須根據 API 回傳狀態執行以下導向邏輯：
初始進入流程
Token 檢查：
無 Token：進入「產品介紹主首頁」(Landing Page)。
有 Token：調用 GET /api/user/me 取得用戶資訊。
狀態分支：
尚未註冊/登入：導向「註冊/登入頁」。
登入成功但無群組：導向主功能頁的「群組」/app/my-group (提供建立或加入選項)。
已有群組：進入應用程式主功能頁（預設顯示行事曆）。
註冊與登入規範
註冊流程：填寫資料 → 送出 → 彈窗提示 [註冊成功，即將導向登入頁] → 導向登入頁。
登入流程：輸入帳密 → 取得 Token → 執行「取得用戶資訊」。
4. 家庭群組管理機制 (Group Management)
角色權限矩陣
為了確保家庭資料安全，系統嚴格區分三種角色權限：
| 功能權限 | 擁有者 (Owner) | 管理員 (Admin) | 成員 (Member) |
| 更改群組名稱 / 頭像 | ✅ | ✅ | ❌ |
| 顯示群組 ID | ✅ | ✅ | ✅ |
| 新增「成員」 | ✅ | ✅ | ❌ |
| 指派「管理員」 | ✅ | ❌ | ❌ |
| 移除「成員」 | ✅ | ✅ | ❌ |
| 移除「管理員」 | ✅ | ❌ | ❌ |
| 轉移「擁有者」 | ✅ (轉移後會變成員) | ❌ | ❌ |
| 解散群組 (Dissolve) | ✅ | ❌ | ❌ |
| 離開群組 (Leave) | ❌ (須先解散) | ✅ | ✅ |
5. 頁面詳細規格 (Page Specifications)
設定頁面 (Settings)
分為 個人 與 群組 兩大模組。
個人設定 (Settings)
頭像管理：支援 .png, .jpg, .gif, .webp 格式，大小限制 3MB。
姓名修改：限制 30 字元以內。
帳號資訊：顯示註冊 Email（不可修改）。
安全性：提供更改密碼與忘記密碼。
群組設定 (Group Settings)
群組資訊：顯示群組 ID 與名稱。
群組編輯：限「擁有者」與「管理者」修改名稱與頭像（規範同個人設定）。
成員清單：顯示所有成員之頭像、名稱、Email 及角色標籤。
異動操作：
刪除成員、解散群組、離開群組時，必須跳出二次確認 Dialog。
6. 核心功能模組 (Core Modules)
行事曆 (Calendar)
家庭事件同步顯示。
支援新增、編輯、刪除事件。
待辦事項 (ToDo)
狀態流轉：勾選後立即移動至「已完成」區塊。
便條紙 (Note)
牆式排版：以小方塊卡片顯示，依編輯時間「由新到舊」排序。
操作：支援即時新增、編輯與刪除。