Imported from buidinhminh51122/Sales (.agents/AGENTS.md). Install upstream with npx skills add buidinhminh51122/Sales --skill .agents. Copyright stays with the author.

AGENTS.md – Sales Project Backend Rules

These rules apply specifically to the Backend portion of the project (located in the back_end/ directory). When the Agent works with the C# (.NET) codebase, it must strictly comply with the standards set below.

1. Architecture & Project Structure

• The backend project follows Clean Architecture comprising 4 layers:
  • Sales.Domain – Entities, Enums, Repository Interfaces
  • Sales.Application – DTOs, Services, Mappings, IServices
  • Sales.Infrastructure – DbContext (EF Core), Repositories, Migrations
  • Sales.Api – Controllers, Middleware, Program.cs
• Do not place business logic inside Controllers; logic belongs in Services (Sales.Application).
• Do not directly reference Sales.Infrastructure from Sales.Application or Sales.Domain.

2. Enums

• Every status, type, or state field must use an enum instead of raw int.
• Enums are placed in Sales.Domain/Enums/, one file per enum.
• Each enum value must have a /// <summary> describing its meaning in English.
• EF Core stores enums in the DB as int via .HasConversion<int>() in SalesDbContext.
• Existing Enums:
  • OrderStatus: Draft=0, Confirmed=1, Completed=2, Cancelled=3
  • PaymentStatus: Unpaid=0, PartiallyPaid=1, FullyPaid=2

3. XML Documentation Comments

• Every class and property in Sales.Domain (Entities, Enums) and Sales.Application (DTOs) must have a /// <summary>.
• Comments must be written in English, clear, stating purpose and constraints (e.g., required, unique, max N characters).
• Foreign key properties must explicitly specify the referenced table, e.g., FK → Orders.
• GenerateDocumentationFile=true and NoWarn 1591 must be enabled across all 3 csproj files: Sales.Api, Sales.Application, Sales.Domain.

4. OpenAPI / Scalar (Replacing Swashbuckle starting from .NET 10)

• The project uses Microsoft.AspNetCore.OpenApi (native) combined with Scalar.AspNetCore for UI – do not use Swashbuckle.
• Every Controller action must include:
  • /// <summary> – short description (1 line, displayed as title in Scalar)
  • /// <remarks> – detailed business description, conditions, and rules
  • /// <param name="..."> – parameter description (for route/query parameters)
  • /// <response code="xxx"> – description of each possible HTTP status code returned
  • [ProducesResponseType(StatusCodes.StatusXXX)] – standard ASP.NET Core attribute (replacing [SwaggerResponse])
• Program.cs must configure:
  • builder.Services.AddOpenApi(options => { ... }) with AddDocumentTransformer to set Title/Version/Description
  • app.MapOpenApi() – endpoint producing JSON file at /openapi/v1.json
  • app.MapScalarApiReference(options => { options.Title = ...; options.Theme = ScalarTheme.DeepSpace; }) – UI at /scalar/v1
• Do not use Swashbuckle's [SwaggerOperation], [SwaggerResponse], or [ApiExplorerSettings].
• The package Scalar.AspNetCore must be referenced in Sales.Api.csproj.

5. Database – EF Core & Migrations

• Every table must have HasComment() describing table purpose in SalesDbContext.
• Every critical column (business logic, FK, enum, currency, status) must have .HasComment() in English.
• After modifying SalesDbContext configuration (adding comments, tables, or altering columns), always create a new migration with a clear descriptive name, e.g., AddDatabaseComments, AddCustomerTable.
• Migration naming convention: PascalCase, name must accurately describe the change.

6. Currency Columns & Decimals

• Currency columns (VND): use decimal with .HasPrecision(18, 2).
• Conversion rate columns (ConversionRate): use decimal with .HasPrecision(18, 4).
• Do not use float or double for financial data; only use double for DiscountPercentage (non-financial percentages).

7. Naming Conventions

• Entity: PascalCase, singular (e.g., Order, OrderDetail, Product).
• DTO: Prefix Create for input DTOs; suffix Dto for all (e.g., CreateOrderDto, OrderDto).
• Controller action: use English action names (GetAll, GetById, Create, Update, Delete, Cancel).
• Migration: PascalCase describing changes (e.g., InitialCreate, AddProductUomConversion, AddDatabaseComments).
• Response messages: write in English (e.g., "Order created successfully.").

8. Soft Delete

• Never hard-delete (physically delete) any data in the backend.
• All Entities must implement the ISoftDelete interface (IsDeleted, DeletedDate, DeletedBy).
• Repositories automatically handle calls to Delete(): converting them into UPDATE IsDeleted = true.
• DbContext is configured with a Global Query Filter (HasQueryFilter(e => !e.IsDeleted)) to automatically hide deleted data from standard queries.
• When querying historical data (e.g., viewing details of an old order containing soft-deleted products), pass the parameter ignoreQueryFilters = true in IGenericRepository to bypass the filter and retrieve full data.

9. Standard Entity Template

Every newly created Entity must conform to the standard structure below, ensuring complete XML Comments (English), implementing ISoftDelete, and declaring Audit fields (CreatedDate, UpdatedDate, etc.):

using System;
using System.Collections.Generic;
using Sales.Domain.Interfaces;

namespace Sales.Domain.Entities.Sample
{
    /// <summary>
    /// Summary description of the purpose of this Entity (in English).
    /// </summary>
    public class SampleEntity : ISoftDelete
    {
        /// <summary>Primary Key (UUID).</summary>
        public Guid Id { get; set; }

        /// <summary>Internal unique identifier code, max 50 characters.</summary>
        public string Code { get; set; } = string.Empty;

        /// <summary>Display name, max 150 characters, required.</summary>
        public string Name { get; set; } = string.Empty;

        // --- Audit Properties (Required) ---
        /// <summary>Record creation datetime (UTC).</summary>
        public DateTime CreatedDate { get; set; } = DateTime.UtcNow;

        /// <summary>ID of the user who created the record.</summary>
        public Guid? CreatedBy { get; set; }

        /// <summary>Datetime of latest update (UTC). Null if never updated.</summary>
        public DateTime? UpdatedDate { get; set; }

        /// <summary>ID of the user who performed the last update.</summary>
        public Guid? UpdatedBy { get; set; }

        // --- ISoftDelete (Required) ---
        /// <summary>Soft delete flag: true = soft deleted, hidden from normal queries.</summary>
        public bool IsDeleted { get; set; } = false;

        /// <summary>Datetime of soft deletion (UTC). Null if not deleted.</summary>
        public DateTime? DeletedDate { get; set; }

        /// <summary>ID of the user who performed the soft deletion.</summary>
        public Guid? DeletedBy { get; set; }

        // --- Relationships (Navigation Properties) ---
        // (Use virtual for lazy loading if applicable)
    }
}

10. Feature Development Workflow

• When receiving requests containing keywords like "develop" or "phát triển", you must strictly follow the workflow steps defined in the process/ folder (especially workflow-srs-to-feature.md).
• Start with Phase 1 (BA Review & Concept): Read SRS/PRD, ask critical clarifying questions, finalize approach, and create concept-{module}-{feature}.md.
• STRICTLY DO NOT skip directly to creating an Implementation Plan or writing code without completing Concept, Spec, and Design documents.
• Important: After each phase of the workflow, you MUST stop, output the results for user review, and wait for explicit user confirmation before proceeding to the next step.

11. Frontend & Responsive Design Rules

• Always Prioritize Responsiveness: When developing new features on Frontend (React/Ant Design), the UI must be designed to adapt seamlessly across all screen sizes (mobile, tablet, desktop).
• Never Use Fixed Widths: Do not assign fixed pixel widths (e.g., width={700}, width: 130px) to Modals, Inputs, or Containers unless strictly necessary. Prefer width: '100%' combined with grid systems.
• Use Grid Instead of Space for Complex Layouts: For Forms with multiple fields per row (such as Form.List), use <Row> and <Col> with responsive props (such as xs={24}, sm={12}, md={6}) so components reflow gracefully instead of using <Space> with display: flex which easily leads to layout overflow.