Hinagiku 軟體架構
================

1\. 系統概覽
--------

Hinagiku（雛菊）是一個**支援即時語音轉錄、AI 對話輔助與雲端資料儲存／訂閱**的智慧討論平台。使用者可在瀏覽器端取得：

- **即時 Speech-to-Text**：將會議語音即時轉成文字
- **AI 教學助理**：根據語音內容與教材，給出引導式回饋
- **多端同步**：透過 Firestore 訂閱機制，即時看到資料更新

---

2\. 架構風格一覽
----------

| 風格 | 角色 / 特點 |
| --- | --- |
| **Client–Server** | 前端（Browser）負責呈現與互動；後端（Server）集中處理商業邏輯與資料庫存取。 |
| **Layered Architecture** | 嚴謹區分：表現層 → 領域層 → 應用層 → 基礎設施層。 |
| **Component-based UI** | 前端採 **Svelte 元件化**，各畫面可重用。 |
| **File-based Routing** | **SvelteKit** 自動將檔案結構映射至路由，減少手動設定。 |

---

3\. 分層細節
--------

### 3.1 表現層（Presentation）

- **技術**：SvelteKit、TailwindCSS、Flowbite-Svelte、Paraglide (i18n)
- **重點目錄**
- `src/routes/**`：頁面與 API 端點
- `src/lib/components/**`：可重用元件
- `src/lib/stores/**`：全域狀態
- **範例**：`+page.svelte` \+ `+server.ts` 配對，前端呼叫 `/api/session/[id]/.../chat` 完成聊天互動。

### 3.2 領域層（Domain）

- **工具**：Zod schema 驗證
- **位置**：`src/lib/schema/*.ts`
- **範例**：`ConversationSchema` 定義對話欄位，確保 Firestore 與前端資料一致。

### 3.3 應用層（Application）

- **職責**：協調業務流程，串接 LLM 與資料服務
- **位置**：`src/routes/api/**/+server.ts`、`src/lib/server/**`
- **例子**：在 `hooks.server.ts` 進行 **Session Cookie 驗證** \+ **國際化** 統一處理。

### 3.4 基礎設施層（Infrastructure）

- **服務**：Firebase Admin (Auth / Firestore)、Cloudflare R2 (S3 相容)、OpenAI & Gemini API
- **位置**：`src/lib/server/firebase.ts`、`prompt.ts`…
- **重點**：集中封裝外部服務，方便日後替換或擴充。

---

4\. 核心資料流程
----------

1. **Browser → Server**：透過 REST API 傳送使用者請求
2. **Server ↔ Firestore**：讀寫對話、使用者、會議等文件
3. **Server ↔ R2**：上傳/下載音訊與檔案
4. **Browser ↔ Firestore (subscribe)**：前端訂閱文件，獲得即時同步

---

5\. 開發工具與部署
-----------

| 類別 | 主要工具 | 備註 |
| --- | --- | --- |
| **建置** | Vite + SvelteKit | 同構開發、SSR/SSG |
| **樣式** | TailwindCSS | 原子化 CSS |
| **國際化** | Paraglide-SvelteKit | 編譯期與執行期 i18n |
| **測試** | Vitest | Firestore mock |
| **品質** | ESLint、Prettier、lint-staged、husky | Commit 階段檢查 |
| **部署** | Dockerfile + docker-compose | Node 22 Slim，多階段建置 |

---

6\. 測試與維運
---------

- **單元測試**：Vitest 模擬 Firebase 函數，確保商業邏輯正確。
- **CI 前置檢查**：commit 時自動執行 Lint／Prettier，降低格式與語法錯誤。
- **容器化**：Docker 保證可攜性；在 `docker-compose.yml` 中配置環境變數與掛載 Service Account。

---

7\. 亮點與結論
---------

- **全端同一框架**：SvelteKit 讓前後端共用 TypeScript 型別，減少溝通成本。
- **嚴謹分層**：清楚界定責任範圍，有利日後維護與重構。
- **Schema 驗證先行**：Zod 強制型別約束，避免非預期資料進入系統。
- **現代 DevOps**：Vite 快速開發、Docker 免裝依賴、Pre-commit 檢查全面保障品質。
- **擴充彈性高**：外部服務集中於 `src/lib/server`，未來可替換資料庫或多雲端儲存。