185 lines
6.0 KiB
Markdown
185 lines
6.0 KiB
Markdown
# 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) |