AGENTS.md

Project Overview (專案概述)

這是一個採用 Domain-Driven Design (DDD) 分層架構的電子商務後端系統。 主要目標是構建高內聚、低耦合的企業級應用，提供商品檢索與結帳服務。

Tech Stack (技術堆疊)

• Framework: .NET 8 SDK (ASP.NET Core Web API)
• Language: C# 12
• Database: SQL Server 17
• ORM: Entity Framework Core
• Object Mapping: AutoMapper
• Validation: FluentValidation
• Testing: NUnit, Moq

Architecture & Directory Structure (架構與目錄結構)

本專案嚴格遵循 DDD 四層架構，依賴方向由外向內（Presentation -> Infrastructure -> Application -> Domain）：

• /src/Domain (核心層 - 無依賴)

  • 包含 Entities, Value Objects, Aggregates, Domain Events, Repository Interfaces。
  • 禁止 依賴任何外部庫或基礎設施。

• /src/Application (應用層)

  • 包含 DTOs, Services (Use Cases), Validators, Interface Implementations (非 DB)。
  • 負責協調 Domain Object 完成業務邏輯。

• /src/Infrastructure (基礎設施層)

  • 包含 EF Core DbContext, Repositories 實作, External API Clients。
  • 負責 MySQL 資料庫連接與第三方服務串接。

• /src/API (表現層)

  • 包含 Controllers, Middleware, Filters, Program.cs。
  • 僅負責接收 HTTP 請求並呼叫 Application Service，不包含 業務邏輯。

Coding Conventions (編碼規範)

• Naming:
  • Class, Method, Property 使用 PascalCase (e.g., ProductService, GetByIdAsync).
  • Private Field 使用 _camelCase (e.g., _repository).
  • Local Variable 使用 camelCase.
  • Interface 必須以此 I 開頭 (e.g., IProductRepository).
• Async:
  • 所有 I/O 操作必須使用 async/await。
  • Method 名稱必須以 Async 結尾 (e.g., SaveOrderAsync).
• Dependency Injection:
  • 優先使用 Constructor Injection (建構子注入)。
• Entity Guidelines:
  • Entity 屬性應設為 private set，透過 Method 修改狀態 (封裝性)。
  • 避免在 Domain Entity 中使用 Data Annotations，應在 Infrastructure 使用 Fluent API 配置。

Testing Protocols (測試規範)

• Unit Tests: 針對 Domain 與 Application 層邏輯進行單元測試 (使用 xUnit)。
• Mocking: 外部依賴 (如 Database, Email) 必須使用 Moq 進行模擬。
• Commit Rule: 提交代碼前請運行 dotnet test 確保所有測試通過。

Pull Request Guidelines (PR 指南)

• PR 標題請遵循 Conventional Commits (e.g., feat(order): implement checkout domain logic).
• 必須確認沒有破壞 DDD 的依賴原則（例如 Domain 層不能引用 Infrastructure 層）。