dramaling-vocab-learning/docs/04_technical/system-architecture.md

DramaLing 系統架構總覽

1. 系統架構概要

1.1 整體架構圖

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│                 │    │                 │    │                 │
│   前端 (React)  │◄──►│  後端 API       │◄──►│   外部服務      │
│   Next.js 15    │    │  ASP.NET Core   │    │   Google AI     │
│   TypeScript    │    │  C# .NET 8      │    │   Azure Speech  │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │                 │
                       │   資料存儲       │
                       │   SQLite DB     │
                       │   本地檔案      │
                       │                 │
                       └─────────────────┘

1.2 核心組件

🖥️ 前端層 (Client)

• 技術棧: Next.js 15 + TypeScript + Tailwind CSS
• 部署: http://localhost:3000 (開發環境)
• 主要職責: 用戶介面、用戶互動、API 呼叫

⚙️ 後端層 (Server)

• 技術棧: ASP.NET Core 8.0 + C#
• 部署: http://localhost:5008 (開發環境)
• 主要職責: 業務邏輯、API 服務、資料處理

💾 資料層 (Data)

• 資料庫: SQLite + Entity Framework Core
• 檔案位置: dramaling_test.db
• 主要職責: 資料持久化、關聯管理

🌐 外部服務層 (External)

• AI 服務: Google Gemini API
• 語音服務: Azure Speech Service
• 主要職責: AI 分析、語音合成

2. 技術棧詳細說明

2.1 前端技術棧

技術組件	版本	用途	檔案位置
Next.js	15.x	React 框架	/frontend
TypeScript	5.x	型別安全	.tsx, .ts 檔案
Tailwind CSS	3.x	樣式框架	tailwind.config.js
React	18.x	UI 組件	/components

2.2 後端技術棧

技術組件	版本	用途	檔案位置
ASP.NET Core	8.0	Web API 框架	/backend/DramaLing.Api
Entity Framework	8.0	ORM 框架	/Data
SQLite	3.x	資料庫	dramaling_test.db
JWT	-	身份驗證	/Services/AuthService.cs

2.3 開發工具

工具	用途	配置檔案
npm	前端套件管理	package.json
dotnet	後端專案管理	*.csproj
Git	版本控制	.gitignore

3. 服務間通信

3.1 前後端通信

• 協議: HTTP/HTTPS
• 格式: JSON
• 認證: JWT Token
• CORS: 配置允許 localhost:3000-3002

3.2 API 基礎規範

• 基礎路徑: http://localhost:5008/api
• 內容類型: application/json
• 錯誤格式: 標準化錯誤回應
• 成功格式: {success: boolean, data?: T, error?: string}

4. 資料流架構

4.1 典型請求流程

用戶操作 → React Component → API Service → HTTP Request → ASP.NET Controller → Business Service → Entity Framework → SQLite
    ↓                                                                                                                     ↑
Response ← State Update ← API Response ← HTTP Response ← JSON Serialization ← Business Logic ← Database Query ←────────┘

4.2 錯誤處理流程

異常發生 → Exception Handling → Error Response → Frontend Error State → User Feedback

5. 安全架構

5.1 認證機制

• JWT Token: 用戶身份驗證
• Token 來源: Supabase 相容格式
• 驗證位置: ASP.NET Core Middleware

5.2 資料保護

• 輸入驗證: 前端 + 後端雙重驗證
• SQL 注入防護: Entity Framework 參數化查詢
• XSS 防護: React 內建保護機制

6. 開發環境

6.1 本地開發設定

前端開發伺服器

cd frontend
npm run dev
# 運行於: http://localhost:3000

後端開發伺服器

cd backend
dotnet run --project DramaLing.Api
# 運行於: http://localhost:5008

6.2 環境變數

後端環境變數

DRAMALING_DB_CONNECTION=Data Source=dramaling_test.db
DRAMALING_SUPABASE_URL=https://localhost
DRAMALING_SUPABASE_JWT_SECRET=dev-secret-minimum-32-characters-long-for-jwt-signing-in-development-mode-only
USE_INMEMORY_DB=false

前端環境變數

NEXT_PUBLIC_API_URL=http://localhost:5008

7. 部署架構

7.1 開發環境

• 前端: npm run dev (Hot Reload)
• 後端: dotnet run (Hot Reload)
• 資料庫: 本地 SQLite 檔案

7.2 生產環境 (未來)

• 前端: Vercel / Netlify
• 後端: Azure App Service / AWS EC2
• 資料庫: PostgreSQL / Azure SQL

8. 監控與維護

8.1 日誌系統

• 前端: Console.log (開發), Sentry (生產)
• 後端: ILogger, 結構化日誌
• API: HTTP 請求/回應日誌

8.2 效能監控

• 前端: Next.js 內建分析
• 後端: ASP.NET Core 效能計數器
• 資料庫: EF Core 查詢分析

---

文檔版本: v1.0 建立日期: 2025-09-24 維護負責: 開發團隊 更新頻率: 架構變更時即時更新

📋 此文檔為系統架構總覽，詳細技術規格請參考：

• 後端架構詳細說明
• 前端架構詳細說明
• 詞卡 API 規格