# 資料庫命名規範統一計劃

## 📋 計劃概述

本計劃旨在解決 DramaLing 專案中資料庫欄位命名不一致的問題，將所有資料庫欄位統一為 `snake_case` 命名規範。

## 🔍 現況分析

### 問題描述
目前資料庫中同時存在兩種命名方式：
- **PascalCase**: `Example`, `Word`, `Translation`, `Definition`, `Name`, `Color` 等
- **snake_case**: `user_id`, `created_at`, `is_favorite`, `part_of_speech` 等

### 問題根源
1. **歷史遺留**: 早期遷移沒有統一配置欄位命名
2. **不完整配置**: 部分屬性缺少 `.HasColumnName()` 映射
3. **維護疏漏**: 新增欄位時沒有遵循統一規範

### 已修復項目 ✅
- ✅ `Flashcard.Word` → `word`
- ✅ `Flashcard.Translation` → `translation`
- ✅ `Flashcard.Definition` → `definition`
- ✅ `Flashcard.Pronunciation` → `pronunciation`
- ✅ `Flashcard.Example` → `example` (原始問題)

## 🎯 統一規範標準

### 命名規則
| 層級 | 命名方式 | 範例 | 說明 |
|------|----------|------|------|
| **C# 實體屬性** | PascalCase | `UserId`, `CreatedAt`, `ExampleTranslation` | 符合 C# 慣例 |
| **資料庫欄位** | snake_case | `user_id`, `created_at`, `example_translation` | 符合資料庫慣例 |
| **表格名稱** | snake_case | `flashcards`, `user_profiles`, `daily_stats` | 保持一致性 |

### 映射規則
```csharp
// 所有屬性都需要明確映射
entity.Property(e => e.PropertyName).HasColumnName("property_name");
```

## 📝 待修復項目清單

### 1. Tag 實體
```csharp
// 目前缺少的映射：
public Guid Id { get; set; }           // → "id"
public string Name { get; set; }       // → "name"
public string Color { get; set; }      // → "color"
```

### 2. ErrorReport 實體
```csharp
// 目前缺少的映射：
public Guid Id { get; set; }           // → "id"
public string? Description { get; set; } // → "description"
public string Status { get; set; }     // → "status"
```

### 3. DailyStats 實體
```csharp
// 目前缺少的映射：
public Guid Id { get; set; }           // → "id"
public DateTime Date { get; set; }     // → "date"
```

### 4. 其他實體
需要檢查以下實體是否有遺漏的映射：
- `SentenceAnalysisCache`
- `WordQueryUsageStats`
- `ExampleImage`
- `ImageGenerationRequest`
- `OptionsVocabulary`

### 5. 通用 Id 欄位
所有實體的 `Id` 屬性都應該映射為 `id`

## 🚀 執行步驟

### 階段一：DbContext 配置更新
1. **補充 Tag 實體配置**
   ```csharp
   private void ConfigureTagEntities(ModelBuilder modelBuilder)
   {
       var tagEntity = modelBuilder.Entity<Tag>();
       tagEntity.Property(t => t.Id).HasColumnName("id");
       tagEntity.Property(t => t.Name).HasColumnName("name");
       tagEntity.Property(t => t.Color).HasColumnName("color");
       // 其他現有配置...
   }
   ```

2. **補充其他實體配置**
   - 更新 `ConfigureErrorReportEntity`
   - 更新 `ConfigureDailyStatsEntity`
   - 新增其他實體的配置方法

### 階段二：資料庫遷移
1. **建立遷移**
   ```bash
   dotnet ef migrations add CompleteSnakeCaseNaming
   ```

2. **套用遷移**
   ```bash
   dotnet ef database update
   ```

### 階段三：驗證與測試
1. **檢查資料庫結構**
   ```sql
   .schema table_name
   ```

2. **測試應用程式功能**
   - API 端點測試
   - 資料查詢測試
   - 完整功能驗證

## 📋 檢核清單

### 配置檢核
- [ ] 所有實體的 `Id` 屬性都有 `.HasColumnName("id")`
- [ ] 所有多單字屬性都使用 snake_case（如 `CreatedAt` → `created_at`）
- [ ] 所有布林屬性都使用 `is_` 前綴（如 `IsActive` → `is_active`）
- [ ] 外鍵屬性都使用 `_id` 後綴（如 `UserId` → `user_id`）

### 遷移檢核
- [ ] 遷移檔案正確生成
- [ ] SQL 指令正確（RENAME COLUMN）
- [ ] 沒有資料遺失風險
- [ ] 回滾計劃準備完成

### 測試檢核
- [ ] 所有 API 端點正常運作
- [ ] 資料查詢結果正確
- [ ] 無效能退化
- [ ] 前端功能正常

## 🔧 長期維護建議

### 1. 編碼規範
建立明確的編碼規範文檔：
```markdown
## 資料庫命名規範
- 所有新增的實體屬性都必須配置 `.HasColumnName()`
- 資料庫欄位名稱統一使用 snake_case
- 布林欄位使用 `is_` 前綴
- 外鍵欄位使用 `_id` 後綴
```

### 2. Code Review 檢查點
在 PR 審查時檢查：
- 新增實體是否有完整的欄位映射配置
- 遷移檔案是否符合命名規範
- 是否需要更新相關文檔

### 3. 自動化檢查
考慮實施：
- **Pre-commit Hook**: 檢查新增的 DbContext 配置
- **CI/CD 檢查**: 驗證遷移檔案的正確性
- **單元測試**: 確保所有實體都有正確的欄位映射

### 4. 全局慣例配置（進階選項）
可以考慮使用 EF Core 的全局慣例：
```csharp
protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Properties<string>()
        .HaveColumnName(propertyInfo => propertyInfo.Name.ToSnakeCase());
}
```

## 📊 影響評估

### 優點
- ✅ 統一的命名規範
- ✅ 更好的可維護性
- ✅ 避免開發混淆
- ✅ 符合業界標準

### 風險
- ⚠️ 需要資料庫遷移
- ⚠️ 可能影響現有查詢
- ⚠️ 需要充分測試

### 緩解措施
- 📋 充分的測試計劃
- 🔄 準備回滾方案
- 📝 詳細的變更文檔
- 👥 團隊溝通協調

## 🗓️ 執行時間表

| 階段 | 預估時間 | 責任人 | 狀態 |
|------|----------|--------|------|
| 現況分析 | 0.5 天 | 開發團隊 | ✅ 完成 |
| 配置更新 | 1 天 | 後端開發 | 🚧 進行中 |
| 遷移建立 | 0.5 天 | 後端開發 | ⏳ 待執行 |
| 測試驗證 | 1 天 | 全團隊 | ⏳ 待執行 |
| 部署上線 | 0.5 天 | DevOps | ⏳ 待執行 |

## 📞 聯絡資訊

如有問題或需要協助，請聯絡：
- **技術負責人**: [待填入]
- **專案經理**: [待填入]
- **QA 負責人**: [待填入]

---

**文件版本**: v1.0
**最後更新**: 2025-09-30
**建立人**: Claude Code Assistant