設計給 go-nunu 使用的 rules

go-nunu.mdc

# go-nunu 框架開發優化規則

## 🚀 核心原則
- **框架優先**：優先使用 nunu CLI 工具建立檔案骨架，再進行內容填充
- **減少手動建立**：避免手動建立 handler、service、repository、model 檔案
- **結構一致性**：確保所有組件遵循 nunu 框架的標準結構
- **依賴注入**：正確使用 Wire 進行依賴注入配置

## 🛠️ 建立檔案工作流程

### 建立單一組件
當需要建立新的業務模組時，按以下順序執行：

1. **建立 Model**：
   ```bash
   nunu create model [model-name]
   ```

2. **建立 Repository**：
   ```bash
   nunu create repository [repository-name]
   ```

3. **建立 Service**：
   ```bash
   nunu create service [service-name]
   ```

4. **建立 Handler**：
   ```bash
   nunu create handler [handler-name]
   ```

### 建立完整模組
對於新的業務模組，建議使用：
```bash
nunu create all [module-name]
```

### Wire 依賴注入編譯
每次新增組件後必須執行：
```bash
nunu wire all
```

## 📁 檔案結構規範

### Model 檔案 (internal/model/)
- 定義資料結構和資料庫模型
- 包含 GORM 標籤和 JSON 標籤
- 遵循現有的命名慣例（如 User、Agent、Product 等）

### Repository 檔案 (internal/repository/)
- 實作資料存取層
- 包含介面定義和具體實作
- 使用 GORM 進行資料庫操作

### Service 檔案 (internal/service/)
- 實作業務邏輯層
- 依賴 Repository 介面
- 包含錯誤處理和業務驗證

### Handler 檔案 (internal/handler/)
- 實作 HTTP 處理層
- 包含 Swagger 文檔註解
- 處理請求驗證和回應格式化

## 🔧 開發最佳實踐

### 1. 新增業務模組流程
```bash
# 步驟 1: 建立完整模組
nunu create all [module-name]

# 步驟 2: 編譯 Wire 依賴
nunu wire all

# 步驟 3: 修改生成的檔案內容
# - 更新 model 結構
# - 實作 repository 方法
# - 實作 service 業務邏輯
# - 實作 handler HTTP 端點

# 步驟 4: 更新路由配置 (internal/server/http.go)
# 步驟 5: 更新 Wire 配置 (cmd/server/wire/wire.go)
```

### 2. API 結構定義
在 `api/v1/` 目錄下建立對應的 API 結構定義：
- Request 結構
- Response 結構
- 驗證規則

### 3. 錯誤處理
在 `api/v1/errors.go` 中定義業務相關的錯誤碼。

## 🎯 Agent 開發指導

### 當需要建立新的業務功能時：

1. **不要手動建立 Go 檔案**
2. **先詢問用戶模組名稱**
3. **執行 nunu create all [module-name]**
4. **執行 nunu wire all**
5. **然後修改生成的檔案內容**

### 修改現有檔案時：
- 確保遵循現有的程式碼風格
- 保持與框架結構的一致性
- 正確處理錯誤和日誌記錄

## 📋 檢查清單

### 建立新模組後必須檢查：
- [ ] Model 結構是否正確定義
- [ ] Repository 介面和實作是否完整
- [ ] Service 業務邏輯是否正確
- [ ] Handler HTTP 端點是否正確
- [ ] API 結構是否在 api/v1/ 中定義
- [ ] 路由是否在 http.go 中註冊
- [ ] Wire 依賴是否正確配置
- [ ] 是否執行了 nunu wire all

### 編譯檢查：
- [ ] `go build` 是否成功
- [ ] 是否有未使用的變數或導入
- [ ] 是否有語法錯誤

## 🚨 常見錯誤避免

1. **不要跳過 nunu CLI 工具**：總是使用框架工具建立檔案
2. **不要忘記 Wire 編譯**：每次新增組件後都要執行 `nunu wire all`
3. **不要破壞現有結構**：保持與現有程式碼的一致性
4. **不要忽略錯誤處理**：確保所有業務邏輯都有適當的錯誤處理

## 🔄 開發週期

```
需求 → nunu create → 編譯 wire → 填充內容 → 測試 → 部署
```

每個步驟都要確保框架規範的遵循和程式碼品質的維護。

## 📚 參考資源

- nunu CLI 文檔：https://go-nunu.github.io/nunu/cli
- 專案現有程式碼結構和慣例
- Wire 依賴注入最佳實踐