# 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 本地開發設定

#### 前端開發伺服器
```bash
cd frontend
npm run dev
# 運行於: http://localhost:3000
```

#### 後端開發伺服器
```bash
cd backend
dotnet run --project DramaLing.Api
# 運行於: http://localhost:5008
```

### 6.2 環境變數

#### 後端環境變數
```bash
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
```

#### 前端環境變數
```bash
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
**維護負責**: 開發團隊
**更新頻率**: 架構變更時即時更新

> 📋 此文檔為系統架構總覽，詳細技術規格請參考：
> - [後端架構詳細說明](./backend-architecture.md)
> - [前端架構詳細說明](./frontend-architecture.md)
> - [詞卡 API 規格](./flashcard-api-specification.md)