V3.Admin.Backend - 後台管理系統後端

English | 繁體中文

現代化的後台管理系統後端 API，基於 ASP.NET Core 10 與 PostgreSQL 構建。本專案配合 V3 Admin Vite 前端專案，快速打造完整的企業級後台管理系統，提供帳號認證、權限管理、角色控制等核心功能。

🎯 專案特色

本專案是配合 V3 Admin Vite 前端框架設計的後端系統，可快速搭建具備以下特色的企業級後台：

• 🚀 開箱即用 - 完整的前後端整合方案，快速啟動專案開發
• 🎨 現代化前端 - Vue 3 + TypeScript + Element Plus 管理介面
• ⚡ 高效能後端 - .NET 10 + PostgreSQL 提供穩定高效的 API 服務
• 🔐 完整權限系統 - RBAC 角色權限控制，細粒度權限管理

✨ 功能特色

• 🔐 JWT 身份驗證 - 基於 Bearer Token 的無狀態身份驗證,支援版本控制
• 👤 帳號管理 - 完整的 CRUD 操作 (新增、查詢、更新、刪除)
• 🔑 密碼管理 - BCrypt 雜湊 (work factor 12) + 用戶自助修改密碼 + 管理員重設密碼
• 🛡️ 權限管理 - 細粒度權限控制 (account.read/update/delete, user.profile.read/update)
• 🔒 安全性 - 輸入驗證、SQL 注入防護、軟刪除機制、密碼強度檢查
• 🔄 並發控制 - 樂觀鎖定 (Optimistic Locking) 防止資料衝突
• 📝 完整日誌 - 結構化日誌記錄與 TraceId 追蹤
• 📚 API 文件 - 內建 Swagger UI 互動式文件
• ✅ 高測試覆蓋 - 39 個單元測試 + 111+ 個整合測試 (150+ 測試通過)
• 🌐 繁體中文 - 完整繁體中文錯誤訊息與文件
• 🐳 Docker 支援 - 容器化部署就緒

� 相關專案

• 前端專案: V3 Admin Vite - Vue 3 + TypeScript + Element Plus 管理後台

本專案提供完整的 RESTful API，可與前端專案無縫整合，快速構建企業級後台管理系統。

�🚀 快速開始

前置需求

• .NET SDK 10.0+
• PostgreSQL 15+
• Docker Desktop (選用,用於整合測試)

安裝步驟

1. 複製專案

   git clone https://github.com/your-org/V3.Admin.Backend.git
   cd V3.Admin.Backend
   git checkout 001-account-management

2. 設定資料庫

   # 建立資料庫
   psql -U postgres -c "CREATE DATABASE v3admin_dev;"
   
   # 執行遷移
   cd Database/Migrations
   Get-ChildItem -Filter "*.sql" | Sort-Object Name | ForEach-Object {
       psql -U postgres -d v3admin_dev -f $_.FullName
   }
   cd ../..
   
   # 插入測試資料
   psql -U postgres -d v3admin_dev -f Database/Scripts/seed.sql

3. 設定組態

   編輯 appsettings.Development.json:

   {
     "ConnectionStrings": {
       "DefaultConnection": "Host=localhost;Port=5432;Database=v3admin_dev;Username=postgres;Password=postgres"
     },
     "JwtSettings": {
       "SecretKey": "YourSecretKeyAtLeast32Characters!!!",
       "Issuer": "V3.Admin.Backend",
       "Audience": "V3.Admin.Frontend",
       "ExpirationMinutes": 60
     }
   }

4. 啟動應用程式

   dotnet run

   瀏覽器開啟 https://localhost:5001/swagger

預設測試帳號

• 帳號: admin / 密碼: Admin@123
• 帳號: testuser / 密碼: Test@123

📖 API 端點

身份驗證

方法	端點	說明	授權
POST	/api/auth/login	使用者登入	❌

帳號管理

方法	端點	說明	授權	權限
GET	/api/account	查詢帳號列表 (分頁)	✅	account.read
GET	/api/account/{id}	查詢單一帳號	✅	account.read
GET	/api/account/me	查詢個人資料	✅	user.profile.read
POST	/api/account	新增帳號	✅	account.create
PUT	/api/account/{id}	更新帳號資訊	✅	account.update
PUT	/api/account/me/password	修改自己的密碼	✅	user.profile.update
PUT	/api/account/{id}/reset-password	管理員重設用戶密碼	✅	account.update
DELETE	/api/account/{id}	刪除帳號 (軟刪除)	✅	account.delete

API 使用範例

登入

curl -X POST https://localhost:5001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"account":"admin","password":"Admin@123"}'

新增帳號

curl -X POST https://localhost:5001/api/account \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"account":"newuser","password":"Secure@123","displayName":"新使用者"}'

修改自己的密碼

curl -X PUT https://localhost:5001/api/account/me/password \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"oldPassword":"Admin@123","newPassword":"NewSecure@123","version":1}'

管理員重設用戶密碼

curl -X PUT https://localhost:5001/api/account/{userId}/reset-password \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"newPassword":"ResetSecure@123","version":1}'

完整的 API 文件與範例請參閱 Swagger UI 或 Quickstart Guide。

🏗️ 技術架構

技術堆疊

• 框架: ASP.NET Core 10.0 (Web API)
• 語言: C# 14
• 資料庫: PostgreSQL 15+
• ORM: Dapper (Micro-ORM)
• 身份驗證: JWT Bearer Token
• 密碼雜湊: BCrypt.Net-Next
• 輸入驗證: FluentValidation
• API 文件: Swagger/OpenAPI
• 測試框架: xUnit + Moq + FluentAssertions + Testcontainers

專案結構

V3.Admin.Backend/
├── Controllers/          # API 控制器
│   ├── AuthController.cs
│   ├── AccountController.cs
│   ├── RoleController.cs
│   ├── PermissionController.cs
│   └── BaseApiController.cs
├── Services/             # 業務邏輯層
│   ├── AuthService.cs
│   ├── AccountService.cs
│   ├── JwtService.cs
│   └── Interfaces/       # 服務介面
├── Repositories/         # 資料存取層
│   ├── UserRepository.cs
│   ├── RoleRepository.cs
│   ├── PermissionRepository.cs
│   └── Interfaces/       # Repository 介面
├── Models/               # 資料模型
│   ├── Entities/         # 資料庫實體
│   ├── Dtos/             # 資料傳輸物件
│   ├── Requests/         # API 請求模型
│   └── Responses/        # API 回應模型
├── Validators/           # FluentValidation 驗證器
├── Middleware/           # 中介軟體
│   ├── ExceptionHandlingMiddleware.cs
│   ├── TraceIdMiddleware.cs
│   └── PermissionAuthorizationMiddleware.cs
├── Configuration/        # 組態模型
├── Database/             # 資料庫腳本
│   ├── Migrations/       # 遷移腳本
│   └── Scripts/          # 種子資料
└── Tests/                # 測試專案
    ├── Unit/             # 單元測試 (39 tests)
    └── Integration/      # 整合測試 (111+ tests)

架構設計

• 三層架構: Controller → Service → Repository
• 依賴注入: 使用 ASP.NET Core DI 容器
• DTO 模式: 分離內部模型與 API 合約
• Repository 模式: 抽象資料存取邏輯
• 中介軟體管道: 集中處理例外與 TraceId
• 統一回應格式: ApiResponseModel<T> 包裝所有回應

API 回應格式

所有 API 回應遵循統一格式:

{
  "success": true,
  "code": "SUCCESS",
  "message": "操作成功",
  "data": { ... },
  "timestamp": "2025-10-28T10:30:00Z",
  "traceId": "7d3e5f8a-2b4c-4d9e-8f7a-1c2d3e4f5a6b"
}

HTTP 狀態碼與業務代碼對照:

HTTP	業務代碼	說明
200	SUCCESS	操作成功
201	CREATED	資源建立成功
400	VALIDATION_ERROR	輸入驗證錯誤
401	UNAUTHORIZED / INVALID_CREDENTIALS	未授權 / 憑證錯誤
404	NOT_FOUND	資源不存在
409	CONCURRENT_UPDATE_CONFLICT	並發更新衝突
422	USERNAME_EXISTS / ...	業務邏輯錯誤
500	INTERNAL_ERROR	系統內部錯誤

🧪 測試

執行測試

# 執行所有測試 (150+ tests)
dotnet test

# 僅執行單元測試 (39 tests)
dotnet test --filter "FullyQualifiedName!~Integration"

# 僅執行整合測試 (111+ tests, 需要 Docker)
dotnet test --filter "FullyQualifiedName~Integration"

# 執行特定控制器的整合測試
dotnet test --filter "FullyQualifiedName~AccountControllerIntegrationTests"

# 詳細輸出
dotnet test --logger "console;verbosity=detailed"

測試覆蓋率

類別	測試數	狀態
Validators	28	✅
Services (單元測試)	11	✅
Integration (AccountController)	17	✅ (1 skipped)
Integration (AuthController)	4	✅
Integration (Other Controllers)	90+	✅
總計	150+	✅ 通過

整合測試

整合測試使用 Testcontainers 自動啟動 PostgreSQL 容器,無需手動設定測試資料庫:

# 確保 Docker Desktop 正在執行
docker ps

# 執行整合測試 (自動建立 PostgreSQL 容器)
dotnet test --filter "FullyQualifiedName~Integration"

📋 開發指南

編碼規範

• 遵循 C# 編碼慣例
• 使用 XML 註解文件化所有 public 成員
• 所有錯誤訊息使用繁體中文
• 使用 async/await 進行非同步操作
• Repository 方法必須有對應的單元測試

新增功能

1. 從 main 分支建立新 feature branch
2. 實作功能並撰寫測試 (測試優先開發建議)
3. 確保所有測試通過 (dotnet test)
4. 更新 API 文件 (Swagger 註解)
5. 提交 Pull Request

Git 工作流程

# 建立功能分支
git checkout -b feature/your-feature-name

# 提交變更
git add .
git commit -m "feat: 新增 XXX 功能"

# 推送到遠端
git push origin feature/your-feature-name

Commit 訊息格式

遵循 Conventional Commits:

• feat: 新功能
• fix: 錯誤修復
• docs: 文件更新
• test: 測試相關
• refactor: 重構
• perf: 效能改進
• chore: 雜項任務

🔒 安全性

已實作的安全措施

• ✅ JWT Bearer Token 身份驗證
• ✅ BCrypt 密碼雜湊 (work factor 12)
• ✅ SQL 注入防護 (參數化查詢)
• ✅ 輸入驗證 (FluentValidation)
• ✅ 軟刪除機制 (資料審計)
• ✅ 樂觀鎖定 (防止並發衝突)
• ✅ HTTPS 強制
• ✅ 統一錯誤處理 (避免資訊洩漏)

安全建議

• 🔐 生產環境 JWT SecretKey 必須儲存於環境變數或 Azure Key Vault
• 🔐 資料庫連線字串 不應包含在原始碼中
• 🔐 啟用 HTTPS 並使用有效憑證
• 🔐 設定 CORS 限制允許的來源
• 🔐 實作速率限制 防止暴力破解
• 🔐 定期更新 相依套件以修補安全漏洞

📚 文件

• 快速入門指南 - 完整的安裝與使用教學
• 功能規格 - 使用者故事與驗收條件
• 實作計畫 - 詳細實作計畫
• 任務清單 - 80 項任務清單 (66+ 已完成)
• API 規格 - OpenAPI 3.0 規格
• Swagger UI - 互動式 API 文件 (需啟動應用程式)

🤝 貢獻

歡迎貢獻！本專案與 V3 Admin Vite 前端專案共同維護，致力於提供最佳的全端後台解決方案。

請遵循以下步驟:

1. Fork 本專案
2. 建立 feature branch (git checkout -b feature/amazing-feature)
3. 提交變更 (git commit -m 'feat: 新增某功能')
4. 推送至分支 (git push origin feature/amazing-feature)
5. 開啟 Pull Request

請確保:

• 所有測試通過
• 新增功能有對應測試
• 遵循專案編碼規範
• 更新相關文件

📝 版本歷史

v1.1.0 (2025-01-23) - Account 模組重構

新功能:

• ✅ 將 username 欄位重命名為 account
• ✅ 用戶自助修改密碼功能
• ✅ 管理員重設用戶密碼功能
• ✅ 細粒度權限控制系統
• ✅ JWT Token 版本控制 (密碼變更後舊 Token 失效)
• ✅ 150+ 個測試 (單元測試 + 整合測試)
• ✅ 完整的權限管理中介軟體
• ✅ 審計日誌支援 (基礎架構)

重大變更:

• 🔄 資料庫欄位: username → account
• 🔄 API 端點: /api/accounts → /api/account
• 🔄 請求欄位: LoginRequest.username → LoginRequest.account

v1.0.0 (2025-10-28)

功能:

• ✅ JWT 身份驗證系統
• ✅ 帳號新增、查詢、更新、刪除
• ✅ 基本密碼變更功能
• ✅ 軟刪除機制
• ✅ 樂觀鎖定並發控制
• ✅ 完整的輸入驗證
• ✅ 46 個測試 (100% 通過)
• ✅ Swagger API 文件
• ✅ Docker 支援

已知限制:

• ✅ 不支援角色權限管理 (已於 v1.1.0 實作)
• 不支援密碼重設 Email (計畫於 v1.2.0 實作)
• 不支援兩階段驗證 (計畫於 v2.0 實作)

📄 授權

本專案採用 MIT License 授權 - 詳見 LICENSE 檔案

🌟 相關資源

• V3 Admin Vite (前端) - Vue 3 管理後台前端專案
• 線上文件 - 詳細的開發文件
• 問題回報 - 回報問題或功能建議

---

⭐ 如果這個專案對您有幫助，請給我們一個 Star！同時也歡迎查看配套的前端專案！