siesa-agents 2.1.25 → 2.1.26-dev.1

package/bmad-core/data/backend-standards.md

@@ -1,332 +1,648 @@
 # Backend Development Standards
 
-> **Note**: For architecture patterns and principles (Hexagonal Architecture, DDD, folder structure), see [architecture-patterns.md](./architecture-patterns.md)
+> **Note**: For architecture patterns and principles (Clean Architecture, DDD, folder structure), see [architecture-patterns.md](./architecture-patterns.md)
 
 ## Technology Stack Standards
 
 ### Core Technologies
-- **NestJS**: 10+ with TypeScript and decorators
-- **TypeScript**: Strict mode enabled, no `any` types
-- **Prisma**: ORM for database operations (no raw queries allowed)
-- **Jest + Supertest**: Unit, integration, and E2E testing
-- **Class-validator + Class-transformer**: DTO validation
+- **.NET 10**: Main framework with C#
+- **C# Minimal API**: Lightweight and modern approach for APIs
+- **Entity Framework Core 10**: ORM for database operations
+- **xUnit**: Unit and integration testing framework
+- **FluentValidation**: Validation for DTOs and models
 
 ### Framework Standards
-- **Default Framework**: NestJS 10+ with TypeScript
-- **Database**: Prisma ORM only - no raw SQL queries
-- **Testing**: TDD approach with comprehensive test coverage
-- **Documentation**: Swagger/OpenAPI auto-generated from decorators
-- **Messaging**: NestJS Microservices (Redis, RabbitMQ, or gRPC)
+- **Default Framework**: .NET 10 with C# Minimal API
+- **Database**: PostgreSQL with Entity Framework Core 10 (mandatory)
+- **ORM Extensions**: 
+  - **linq2db**: For highly optimized complex queries requiring maximum performance
+  - **DynamicLinq**: For runtime dynamic filters from user input or configurable scenarios
+  - **LinqKit**: For composable type-safe predicates in DDD repositories with complex business rules
+- **Testing**: TDD approach with xUnit and high test coverage
+- **Documentation**: Scalar (NO Swagger) auto-generated
+- **Primary Keys**: UUID (Guid) for all entities
+
+## CRITICAL: DateTime Type Standards
+
+### ⚠️ Mandatory Rule: Use DateTimeOffset for Timestamps
+
+**ALWAYS use `DateTimeOffset` instead of `DateTime`** for all timestamp fields in entities, DTOs, and database models.
+
+#### Why DateTimeOffset?
+
+- **PostgreSQL Compatibility**: PostgreSQL uses `TIMESTAMP WITH TIME ZONE` which maps correctly to `DateTimeOffset` but NOT to `DateTime`
+- **Timezone Awareness**: `DateTimeOffset` preserves timezone information, preventing timezone conversion issues
+- **UTC Consistency**: Store all timestamps in UTC for consistency across different timezones
+- **Avoiding Bugs**: Using `DateTime` with PostgreSQL causes:
+  - Data loss during timezone conversions
+  - Inconsistent timestamp comparisons
+  - Ambiguous datetime values during DST transitions
+
+#### Correct Usage
+
+```csharp
+// ✅ CORRECT - Use DateTimeOffset for timestamps
+public class UserEntity : AggregateRoot
+{
+    public Guid Id { get; private set; }
+    public string Email { get; private set; }
+    public DateTimeOffset CreatedAt { get; private set; } = DateTimeOffset.UtcNow;
+    public DateTimeOffset UpdatedAt { get; private set; } = DateTimeOffset.UtcNow;
+}
+
+// ✅ CORRECT - Use DateOnly for date-only fields
+public class ExpenseEntity : AggregateRoot
+{
+    public Guid Id { get; private set; }
+    public decimal Amount { get; private set; }
+    public DateOnly ExpenseDate { get; private set; } // Date without time
+    public DateTimeOffset CreatedAt { get; private set; } = DateTimeOffset.UtcNow;
+}
+
+// ❌ WRONG - Never use DateTime for timestamp fields
+public class UserEntity : AggregateRoot
+{
+    public DateTime CreatedAt { get; private set; } // ❌ WRONG - causes PostgreSQL issues
+    public DateTime UpdatedAt { get; private set; } // ❌ WRONG - causes PostgreSQL issues
+}
+```
+
+#### Entity Framework Core Configuration
+
+```csharp
+public class UserEntityConfiguration : IEntityTypeConfiguration<UserEntity>
+{
+    public void Configure(EntityTypeBuilder<UserEntity> builder)
+    {
+        builder.ToTable("users");
+
+        // DateTimeOffset fields - automatically map to TIMESTAMP WITH TIME ZONE
+        builder.Property(u => u.CreatedAt)
+            .IsRequired()
+            .HasDefaultValueSql("NOW()"); // PostgreSQL auto-generates UTC timestamp
+
+        builder.Property(u => u.UpdatedAt)
+            .IsRequired()
+            .HasDefaultValueSql("NOW()");
+    }
+}
+```
+
+#### Type Selection Guide
+
+| Use Case | Type | Example |
+|----------|------|---------|
+| Timestamp with timezone | `DateTimeOffset` | `CreatedAt`, `UpdatedAt`, `DeletedAt`, `LastLoginAt` |
+| Date only (no time) | `DateOnly` | `BirthDate`, `ExpenseDate`, `DueDate` |
+| Time only (no date) | `TimeOnly` | `OpeningTime`, `ClosingTime` |
+| Never use | `DateTime` | ❌ Not compatible with PostgreSQL TIMESTAMP WITH TIME ZONE |
+
+#### Best Practices
+
+1. **Always use `DateTimeOffset`** for `CreatedAt`, `UpdatedAt`, and any timestamp field
+2. **Always use UTC**: Set values with `DateTimeOffset.UtcNow`
+3. **Configure EF Core**: Use `HasDefaultValueSql("NOW()")` for automatic timestamps
+4. **DTOs must match**: DTOs also use `DateTimeOffset` (serializes to ISO 8601 with timezone)
+5. **Never use `DateTime`** for entity timestamp fields in PostgreSQL projects
+
+### ORM Strategy Guidelines
+
+#### When to Use Entity Framework Core 10
+✔ **Primary ORM for:**
+- Standard CRUD operations
+- DDD entities with tracking (Aggregate Roots, Domain Events)
+- Simple to moderate queries
+- Navigation properties and relationships
+- Change tracking scenarios
+
+#### When to Use linq2db
+✔ **Use for maximum performance:**
+- Highly optimized complex queries (subqueries, complex projections, multiple joins)
+- Queries that EF Core cannot translate efficiently
+- High-performance endpoints: dashboards, analytics, reports, high data volumes
+- Pure queries without tracking needs
+- When EF Core generates inefficient SQL
+
+🚫 **Avoid when:**
+- Need complete DDD entities with aggregate lifecycle
+- Query participates in domain events or tracking
+
+#### When to Use DynamicLinq
+✔ **Use for runtime flexibility:**
+- Dynamic filter systems: `?filter=Age > 30 AND Country == "CO"`
+- Simplified OData-style APIs
+- Configurable grids or data explorers
+- Variable column searches
+
+🚫 **Avoid when:**
+- Filters are fully controlled in code
+- Require strict security (needs sanitization)
+- Need maximum performance (use linq2db or LinqKit)
+
+#### When to Use LinqKit
+✔ **Use for type-safe composition:**
+- Complex business rules in queries with composable predicates
+- Dynamic filters with type safety (no strings → expressions)
+- DDD repositories with multiple criteria, conditional searches, reusable queries
+- Enhance EF Core when composing complex expressions
+- 100% compatible with EF Core translation
+
+🚫 **Avoid when:**
+- Filters are extremely simple
+- Query is highly dynamic and text-based (use DynamicLinq)
+- Need maximum raw performance (use linq2db)
 
 ### Development Tools
-- **Nx**: MonoRepo management and build orchestration
-- **ESLint + Prettier**: Code quality and formatting
-- **Husky**: Pre-commit hooks for quality gates
-- **Winston**: Structured logging with log levels
-- **Redis**: Caching, session storage, and message transport
-- **Passport + JWT**: Authentication and authorization
+- **dotnet CLI**: Project management, build, test, and restore
+- **NuGet**: Package manager
+- **EF Core 10 Migrations**: Database schema version control
+- **Docker**: For production only
+- **Code Analyzers**: Static C# code analysis
+- **EditorConfig**: Code formatting standards
 
 ## Domain-Driven Design Implementation
 
 ### Entity Structure
-```typescript
-export class UserEntity extends AggregateRoot {
-  private constructor(
-    public readonly id: UserId,
-    private _email: EmailValueObject,
-    private _name: NameValueObject,
-  ) {
-    super();
-  }
+```csharp
+public class UserEntity : AggregateRoot
+{
+    // Parameterless constructor for EF Core (materialization from DB)
+    private UserEntity() : base(Guid.Empty)
+    {
+        // EF Core needs this to reconstruct the entity from the database
+    }
 
-  static create(props: CreateUserProps): UserEntity {
-    const user = new UserEntity(
-      UserId.generate(),
-      EmailValueObject.create(props.email),
-      NameValueObject.create(props.name),
-    );
-    user.addDomainEvent(new UserCreatedEvent(user.id));
-    return user;
-  }
+    private UserEntity(
+        Guid id,
+        EmailValueObject email,
+        NameValueObject name) : base(id)
+    {
+        Email = email;
+        Name = name;
+    }
 
-  public updateEmail(newEmail: EmailValueObject): void {
-    if (this._email.equals(newEmail)) return;
-    this._email = newEmail;
-    this.addDomainEvent(new UserEmailUpdatedEvent(this.id, newEmail));
-  }
+    public EmailValueObject Email { get; private set; } = null!;
+    public NameValueObject Name { get; private set; } = null!;
+
+    public static UserEntity Create(string email, string name)
+    {
+        var userEmail = EmailValueObject.Create(email);
+        var userName = NameValueObject.Create(name);
+        
+        var user = new UserEntity(Guid.NewGuid(), userEmail, userName);
+        user.AddDomainEvent(new UserCreatedEvent(user.Id));
+        
+        return user;
+    }
 
-  get email(): EmailValueObject {
-    return this._email;
-  }
+    public void UpdateEmail(string newEmail)
+    {
+        var newEmailVO = EmailValueObject.Create(newEmail);
+        if (Email.Equals(newEmailVO)) return;
+        
+        Email = newEmailVO;
+        AddDomainEvent(new UserEmailUpdatedEvent(Id, Email));
+    }
 }
 ```
 
 ### Value Object Structure
-```typescript
-export class EmailValueObject {
-  private constructor(private readonly value: string) {
-    this.validate(value);
-  }
+```csharp
+public class EmailValueObject : ValueObject
+{
+    public string Value { get; }
 
-  static create(value: string): EmailValueObject {
-    return new EmailValueObject(value);
-  }
+    private EmailValueObject(string value)
+    {
+        Value = value;
+    }
 
-  private validate(value: string): void {
-    if (!value || !this.isValidEmail(value)) {
-      throw new InvalidEmailException(value);
+    public static EmailValueObject Create(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            throw new ArgumentException("Email cannot be empty", nameof(value));
+            
+        if (!IsValidEmail(value))
+            throw new InvalidEmailException(value);
+            
+        return new EmailValueObject(value);
     }
-  }
 
-  equals(other: EmailValueObject): boolean {
-    return this.value === other.value;
-  }
+    private static bool IsValidEmail(string email)
+    {
+        // Email validation logic
+        return System.Text.RegularExpressions.Regex.IsMatch(
+            email, 
+            @"^[^@\s]+@[^@\s]+\.[^@\s]+$");
+    }
 
-  toString(): string {
-    return this.value;
-  }
+    protected override IEnumerable<object> GetEqualityComponents()
+    {
+        yield return Value;
+    }
 }
 ```
 
 ### Repository Pattern
-```typescript
-// Interface (in application/ports/repositories)
-export interface UserRepositoryInterface {
-  save(user: UserEntity): Promise<UserEntity>;
-  findById(id: UserId): Promise<UserEntity | null>;
-  findByEmail(email: EmailValueObject): Promise<UserEntity | null>;
-  delete(id: UserId): Promise<void>;
+```csharp
+// Interface (in Application layer)
+public interface IUserRepository
+{
+    Task<UserEntity> SaveAsync(UserEntity user, CancellationToken cancellationToken = default);
+    Task<UserEntity?> FindByIdAsync(Guid id, CancellationToken cancellationToken = default);
+    Task<UserEntity?> FindByEmailAsync(EmailValueObject email, CancellationToken cancellationToken = default);
+    Task DeleteAsync(Guid id, CancellationToken cancellationToken = default);
 }
 
-// Implementation (in infrastructure/repositories)
-@Injectable()
-export class PrismaUserRepository implements UserRepositoryInterface {
-  constructor(private readonly prisma: PrismaService) {}
-
-  async save(user: UserEntity): Promise<UserEntity> {
-    const data = {
-      id: user.id.toString(),
-      email: user.email.toString(),
-      name: user.name.toString(),
-    };
-
-    const savedUser = await this.prisma.user.upsert({
-      where: { id: data.id },
-      update: data,
-      create: data,
-    });
-
-    return this.toDomain(savedUser);
-  }
+// Implementation (in Infrastructure layer)
+public class UserRepository : IUserRepository
+{
+    private readonly ApplicationDbContext _context;
 
-  private toDomain(prismaUser: User): UserEntity {
-    return UserEntity.reconstitute({
-      id: UserId.create(prismaUser.id),
-      email: EmailValueObject.create(prismaUser.email),
-      name: NameValueObject.create(prismaUser.name),
-    });
-  }
+    public UserRepository(ApplicationDbContext context)
+    {
+        _context = context;
+    }
+
+    public async Task<UserEntity> SaveAsync(UserEntity user, CancellationToken cancellationToken = default)
+    {
+        var existingUser = await _context.Users.FindAsync(new object[] { user.Id }, cancellationToken);
+        
+        if (existingUser == null)
+            await _context.Users.AddAsync(user, cancellationToken);
+        else
+            _context.Users.Update(user);
+
+        await _context.SaveChangesAsync(cancellationToken);
+        return user;
+    }
+
+    public async Task<UserEntity?> FindByIdAsync(Guid id, CancellationToken cancellationToken = default)
+    {
+        return await _context.Users.FindAsync(new object[] { id }, cancellationToken);
+    }
+
+    public async Task<UserEntity?> FindByEmailAsync(EmailValueObject email, CancellationToken cancellationToken = default)
+    {
+        return await _context.Users
+            .FirstOrDefaultAsync(u => u.Email.Value == email.Value, cancellationToken);
+    }
+
+    public async Task DeleteAsync(Guid id, CancellationToken cancellationToken = default)
+    {
+        var user = await FindByIdAsync(id, cancellationToken);
+        if (user != null)
+        {
+            _context.Users.Remove(user);
+            await _context.SaveChangesAsync(cancellationToken);
+        }
+    }
 }
 ```
 
-## Use Case Standards
-
-### Use Case Structure
-```typescript
-@Injectable()
-export class CreateUserUseCase {
-  constructor(
-    @Inject(USER_REPOSITORY)
-    private readonly userRepository: UserRepositoryInterface,
-    @Inject(EVENT_BUS)
-    private readonly eventBus: EventBusInterface,
-  ) {}
-
-  async execute(command: CreateUserCommand): Promise<UserResponseDto> {
-    // 1. Validate business rules
-    await this.validateUserDoesNotExist(command.email);
-
-    // 2. Create domain entity
-    const user = UserEntity.create({
-      email: command.email,
-      name: command.name,
-    });
-
-    // 3. Persist entity
-    const savedUser = await this.userRepository.save(user);
-
-    // 4. Publish domain events
-    await this.eventBus.publishAll(savedUser.getUncommittedEvents());
-
-    // 5. Return response DTO
-    return UserResponseDto.fromEntity(savedUser);
-  }
+## Command/Query (CQRS) Standards
 
-  private async validateUserDoesNotExist(email: string): Promise<void> {
-    const emailVO = EmailValueObject.create(email);
-    const existingUser = await this.userRepository.findByEmail(emailVO);
-    if (existingUser) {
-      throw new UserAlreadyExistsException(email);
+### Command Structure
+```csharp
+public record CreateUserCommand(string Email, string Name);
+
+public class CreateUserCommandValidator : AbstractValidator<CreateUserCommand>
+{
+    public CreateUserCommandValidator()
+    {
+        RuleFor(x => x.Email)
+            .NotEmpty().WithMessage("Email is required")
+            .EmailAddress().WithMessage("Email must be valid");
+
+        RuleFor(x => x.Name)
+            .NotEmpty().WithMessage("Name is required")
+            .MaximumLength(100).WithMessage("Name must not exceed 100 characters");
+    }
+}
+
+public class CreateUserCommandHandler
+{
+    private readonly IUserRepository _userRepository;
+    private readonly IValidator<CreateUserCommand> _validator;
+
+    public CreateUserCommandHandler(
+        IUserRepository userRepository,
+        IValidator<CreateUserCommand> validator)
+    {
+        _userRepository = userRepository;
+        _validator = validator;
+    }
+
+    public async Task<UserResponseDto> HandleAsync(
+        CreateUserCommand command, 
+        CancellationToken cancellationToken = default)
+    {
+        // 1. Validate command
+        await _validator.ValidateAndThrowAsync(command, cancellationToken);
+
+        // 2. Validate business rules
+        await ValidateUserDoesNotExistAsync(command.Email, cancellationToken);
+
+        // 3. Create domain entity
+        var user = UserEntity.Create(command.Email, command.Name);
+
+        // 4. Persist entity
+        var savedUser = await _userRepository.SaveAsync(user, cancellationToken);
+
+        // 5. Return response DTO
+        return UserResponseDto.FromEntity(savedUser);
+    }
+
+    private async Task ValidateUserDoesNotExistAsync(string email, CancellationToken cancellationToken)
+    {
+        var emailVO = EmailValueObject.Create(email);
+        var existingUser = await _userRepository.FindByEmailAsync(emailVO, cancellationToken);
+        if (existingUser != null)
+            throw new UserAlreadyExistsException(email);
     }
-  }
 }
 ```
 
-### Command/Query Structure
-```typescript
-export class CreateUserCommand {
-  @IsEmail()
-  @IsNotEmpty()
-  readonly email: string;
-
-  @IsString()
-  @IsNotEmpty()
-  @Length(2, 50)
-  readonly name: string;
+### Query Structure
+```csharp
+public record GetUserByIdQuery(Guid Id);
+
+public class GetUserByIdQueryHandler
+{
+    private readonly IUserRepository _userRepository;
+
+    public GetUserByIdQueryHandler(IUserRepository userRepository)
+    {
+        _userRepository = userRepository;
+    }
+
+    public async Task<UserResponseDto?> HandleAsync(
+        GetUserByIdQuery query, 
+        CancellationToken cancellationToken = default)
+    {
+        var user = await _userRepository.FindByIdAsync(query.Id, cancellationToken);
+        return user != null ? UserResponseDto.FromEntity(user) : null;
+    }
 }
 ```
 
-## Testing Standards
+### DTO Structure
+```csharp
+public record UserResponseDto
+{
+    public Guid Id { get; init; }
+    public string Email { get; init; }
+    public string Name { get; init; }
+
+    public static UserResponseDto FromEntity(UserEntity user)
+    {
+        return new UserResponseDto
+        {
+            Id = user.Id,
+            Email = user.Email.Value,
+            Name = user.Name.Value
+        };
+    }
+}
 
-### Testing Strategy
-- **Unit Tests**: Domain entities, value objects, use cases (isolated logic)
-- **Integration Tests**: Repository implementations, database operations
-- **E2E Tests**: Complete API workflows with Supertest
-- **TDD Approach**: Write tests before implementation
-
-### Test Structure
-```typescript
-describe('CreateUserUseCase', () => {
-  let useCase: CreateUserUseCase;
-  let userRepository: jest.Mocked<UserRepositoryInterface>;
-  let eventBus: jest.Mocked<EventBusInterface>;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [
-        CreateUserUseCase,
-        { provide: USER_REPOSITORY, useValue: { save: jest.fn(), findByEmail: jest.fn() } },
-        { provide: EVENT_BUS, useValue: { publishAll: jest.fn() } },
-      ],
-    }).compile();
-
-    useCase = module.get(CreateUserUseCase);
-    userRepository = module.get(USER_REPOSITORY);
-    eventBus = module.get(EVENT_BUS);
-  });
-
-  it('should create user successfully', async () => {
-    // Arrange
-    const command = new CreateUserCommand();
-    command.email = 'test@example.com';
-    command.name = 'Test User';
-
-    userRepository.findByEmail.mockResolvedValue(null);
-    userRepository.save.mockResolvedValue(UserEntity.create(command));
-
-    // Act
-    const result = await useCase.execute(command);
-
-    // Assert
-    expect(result.email).toBe(command.email);
-    expect(userRepository.save).toHaveBeenCalledWith(expect.any(UserEntity));
-    expect(eventBus.publishAll).toHaveBeenCalled();
-  });
-
-  it('should throw error when user already exists', async () => {
-    // Arrange
-    const command = new CreateUserCommand();
-    command.email = 'existing@example.com';
-
-    userRepository.findByEmail.mockResolvedValue(UserEntity.create(command));
-
-    // Act & Assert
-    await expect(useCase.execute(command)).rejects.toThrow(UserAlreadyExistsException);
-  });
-});
 ```
 
-## API Controller Standards
-
-### Controller Structure
-```typescript
-@Controller('users')
-@ApiTags('Users')
-export class UserController {
-  constructor(
-    private readonly createUserUseCase: CreateUserUseCase,
-    private readonly getUserUseCase: GetUserUseCase,
-  ) {}
-
-  @Post()
-  @ApiOperation({ summary: 'Create a new user' })
-  @ApiResponse({ status: 201, type: UserResponseDto })
-  @ApiResponse({ status: 400, description: 'Bad request' })
-  async createUser(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
-    const command = new CreateUserCommand();
-    Object.assign(command, dto);
-    return this.createUserUseCase.execute(command);
-  }
+## Minimal API Standards
 
-  @Get(':id')
-  @ApiOperation({ summary: 'Get user by ID' })
-  @ApiResponse({ status: 200, type: UserResponseDto })
-  @ApiResponse({ status: 404, description: 'User not found' })
-  async getUser(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
-    return this.getUserUseCase.execute(new GetUserQuery(id));
-  }
+### Endpoint Structure
+```csharp
+// Program.cs or separate endpoint configuration
+public static class UserEndpoints
+{
+    public static void MapUserEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/users")
+            .WithTags("Users")
+            .WithOpenApi();
+
+        group.MapPost("/", CreateUser)
+            .WithName("CreateUser")
+            .WithSummary("Create a new user")
+            .Produces<UserResponseDto>(StatusCodes.Status201Created)
+            .ProducesValidationProblem();
+
+        group.MapGet("/{id:guid}", GetUserById)
+            .WithName("GetUserById")
+            .WithSummary("Get user by ID")
+            .Produces<UserResponseDto>()
+            .Produces(StatusCodes.Status404NotFound);
+    }
+
+    private static async Task<IResult> CreateUser(
+        CreateUserCommand command,
+        CreateUserCommandHandler handler,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            var result = await handler.HandleAsync(command, cancellationToken);
+            return Results.Created($"/api/users/{result.Id}", result);
+        }
+        catch (ValidationException ex)
+        {
+            return Results.ValidationProblem(ex.Errors.ToDictionary(
+                e => e.PropertyName,
+                e => new[] { e.ErrorMessage }));
+        }
+        catch (UserAlreadyExistsException ex)
+        {
+            return Results.Conflict(new { message = ex.Message });
+        }
+    }
+
+    private static async Task<IResult> GetUserById(
+        Guid id,
+        GetUserByIdQueryHandler handler,
+        CancellationToken cancellationToken)
+    {
+        var result = await handler.HandleAsync(new GetUserByIdQuery(id), cancellationToken);
+        return result != null ? Results.Ok(result) : Results.NotFound();
+    }
 }
 ```
 
-## Database Standards
+## Testing Standards
+
+### Testing Strategy
+- **Unit Tests**: Domain entities, value objects, command/query handlers (isolated logic)
+- **Integration Tests**: Repository implementations, database operations with EF Core InMemory or Test Containers
+- **TDD Approach**: Write tests before or alongside implementation
+- **High Coverage**: Aim for >80% code coverage
+
+### Test Structure (xUnit)
+```csharp
+public class CreateUserCommandHandlerTests
+{
+    private readonly Mock<IUserRepository> _userRepositoryMock;
+    private readonly Mock<IValidator<CreateUserCommand>> _validatorMock;
+    private readonly CreateUserCommandHandler _handler;
+
+    public CreateUserCommandHandlerTests()
+    {
+        _userRepositoryMock = new Mock<IUserRepository>();
+        _validatorMock = new Mock<IValidator<CreateUserCommand>>();
+        _handler = new CreateUserCommandHandler(
+            _userRepositoryMock.Object,
+            _validatorMock.Object);
+    }
 
-### Prisma Schema Patterns
-```prisma
-model User {
-  id        String   @id @default(cuid())
-  email     String   @unique
-  name      String
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  orders    Order[]
+    [Fact]
+    public async Task HandleAsync_WithValidCommand_ShouldCreateUser()
+    {
+        // Arrange
+        var command = new CreateUserCommand("test@example.com", "John Doe");
+        _validatorMock
+            .Setup(v => v.ValidateAndThrowAsync(command, It.IsAny<CancellationToken>()))
+            .Returns(Task.CompletedTask);
+        _userRepositoryMock
+            .Setup(r => r.FindByEmailAsync(It.IsAny<EmailValueObject>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync((UserEntity?)null);
+        _userRepositoryMock
+            .Setup(r => r.SaveAsync(It.IsAny<UserEntity>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync((UserEntity u, CancellationToken _) => u);
+
+        // Act
+        var result = await _handler.HandleAsync(command, CancellationToken.None);
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.Equal(command.Email, result.Email);
+        Assert.Equal(command.Name, result.Name);
+        _userRepositoryMock.Verify(r => r.SaveAsync(It.IsAny<UserEntity>(), It.IsAny<CancellationToken>()), Times.Once);
+    }
 
-  @@map("users")
+    [Fact]
+    public async Task HandleAsync_WithExistingUser_ShouldThrowException()
+    {
+        // Arrange
+        var command = new CreateUserCommand("test@example.com", "John Doe");
+        var existingUser = UserEntity.Create("test@example.com", "Existing User");
+        _validatorMock
+            .Setup(v => v.ValidateAndThrowAsync(command, It.IsAny<CancellationToken>()))
+            .Returns(Task.CompletedTask);
+        _userRepositoryMock
+            .Setup(r => r.FindByEmailAsync(It.IsAny<EmailValueObject>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(existingUser);
+
+        // Act & Assert
+        await Assert.ThrowsAsync<UserAlreadyExistsException>(() => 
+            _handler.HandleAsync(command, CancellationToken.None));
+    }
 }
+```
+
+### Integration Test with EF Core InMemory
+```csharp
+public class UserRepositoryIntegrationTests : IDisposable
+{
+    private readonly ApplicationDbContext _context;
+    private readonly UserRepository _repository;
 
-model Order {
-  id       String      @id @default(cuid())
-  total    Decimal     @db.Decimal(10, 2)
-  status   OrderStatus
-  userId   String
-  user     User        @relation(fields: [userId], references: [id])
-  items    OrderItem[]
+    public UserRepositoryIntegrationTests()
+    {
+        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
+            .UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString())
+            .Options;
 
-  @@map("orders")
+        _context = new ApplicationDbContext(options);
+        _repository = new UserRepository(_context);
+    }
+
+    [Fact]
+    public async Task SaveAsync_ShouldPersistUser()
+    {
+        // Arrange
+        var user = UserEntity.Create("test@example.com", "John Doe");
+
+        // Act
+        var savedUser = await _repository.SaveAsync(user);
+
+        // Assert
+        var retrievedUser = await _repository.FindByIdAsync(savedUser.Id);
+        Assert.NotNull(retrievedUser);
+        Assert.Equal(user.Email.Value, retrievedUser.Email.Value);
+    }
+
+    public void Dispose()
+    {
+        _context.Database.EnsureDeleted();
+        _context.Dispose();
+    }
 }
+```
 
-enum OrderStatus {
-  PENDING
-  CONFIRMED
-  SHIPPED
-  DELIVERED
-  CANCELLED
+## EF Core Configuration Standards
+
+### DbContext Configuration
+```csharp
+public class ApplicationDbContext : DbContext
+{
+    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) 
+        : base(options)
+    {
+    }
+
+    public DbSet<UserEntity> Users { get; set; }
+    public DbSet<QuoteEntity> Quotes { get; set; }
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+
+        // Apply all configurations from assembly
+        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
+    }
 }
 ```
 
-### Prisma Best Practices
-- Use enums for fixed value sets
-- Always add indexes on foreign keys
-- Use `@@map` for table naming (plural snake_case)
-- Include `createdAt` and `updatedAt` timestamps
-- Use `cuid()` for primary keys
-- No raw SQL queries - use Prisma Client only
+### Entity Configuration
+```csharp
+public class UserEntityConfiguration : IEntityTypeConfiguration<UserEntity>
+{
+    public void Configure(EntityTypeBuilder<UserEntity> builder)
+    {
+        builder.ToTable("Users");
+        
+        builder.HasKey(u => u.Id);
+        
+        builder.Property(u => u.Id)
+            .HasColumnType("uuid")
+            .IsRequired();
+
+        // Configure Value Object as owned entity
+        builder.OwnsOne(u => u.Email, email =>
+        {
+            email.Property(e => e.Value)
+                .HasColumnName("Email")
+                .HasMaxLength(256)
+                .IsRequired();
+        });
+
+        builder.OwnsOne(u => u.Name, name =>
+        {
+            name.Property(n => n.Value)
+                .HasColumnName("Name")
+                .HasMaxLength(100)
+                .IsRequired();
+        });
+
+        // Ignore domain events (not persisted)
+        builder.Ignore(u => u.DomainEvents);
+    }
+}
+```
 
 ## Security Standards
 
 ### Authentication & Authorization
 - **JWT Tokens**: Proper expiration and refresh token handling
-- **RBAC**: Role-based access control with Guards
-- **Validation**: Input validation on all endpoints (class-validator)
+- **RBAC**: Role-based access control
+- **Validation**: Input validation on all endpoints (FluentValidation)
 - **Rate Limiting**: Throttle public endpoints to prevent abuse
 - **Environment**: HTTPS only in production, secrets in env variables
 
@@ -335,20 +651,21 @@ enum OrderStatus {
 - Never commit secrets to repository
 - Implement audit logging for critical operations
 - OWASP Top 10 compliance
-- Regular dependency security audits
+- Regular dependency security audits with `dotnet list package --vulnerable`
 
 ## Performance Standards
 
 ### Database Optimization
 - Proper indexing on frequently queried fields
-- Connection pooling via Prisma
-- Pagination for large datasets (cursor-based preferred)
-- Avoid N+1 queries with Prisma `include`
+- Connection pooling via EF Core 10
+- Pagination for large datasets (Skip/Take or cursor-based)
+- Avoid N+1 queries with `.Include()` and `.ThenInclude()`
 - Query monitoring and slow query logging
+- Use `AsNoTracking()` for read-only queries
 
 ### Caching Strategy
-- **Redis**: Session data, rate limiting, and frequently accessed data
-- **Application Cache**: In-memory caching for configuration
+- **Distributed Cache**: Redis for session data and frequently accessed data
+- **Memory Cache**: In-memory caching for configuration
 - **TTL Strategy**: Appropriate time-to-live for different data types
 - **Invalidation**: Event-driven cache invalidation
 
@@ -358,15 +675,138 @@ enum OrderStatus {
 - Domain exceptions for business rule violations
 - Application exceptions for use case errors
 - Infrastructure exceptions for external service failures
-- HTTP exception filters for API responses
+- Global exception middleware for API responses
 
-### Error Response Format
-```typescript
+### Error Response Format (Problem Details RFC 7807)
+```csharp
+public record ProblemDetailsResponse
 {
-  "statusCode": 400,
-  "message": "User with email already exists",
-  "error": "UserAlreadyExistsException",
-  "timestamp": "2024-01-15T10:30:00Z",
-  "path": "/api/users"
+    public int Status { get; init; }
+    public string Title { get; init; }
+    public string Detail { get; init; }
+    public string Instance { get; init; }
+    public DateTimeOffset Timestamp { get; init; }
+    public Dictionary<string, string[]>? Errors { get; init; }
 }
-```
+
+// Example response
+{
+  "status": 400,
+  "title": "Validation Error",
+  "detail": "One or more validation errors occurred",
+  "instance": "/api/users",
+  "timestamp": "2025-11-26T10:30:00Z",
+  "errors": {
+    "Email": ["Email is required", "Email must be valid"],
+    "Name": ["Name is required"]
+  }
+}
+```
+
+### Global Exception Middleware
+```csharp
+public class ExceptionHandlingMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<ExceptionHandlingMiddleware> _logger;
+
+    public ExceptionHandlingMiddleware(
+        RequestDelegate next,
+        ILogger<ExceptionHandlingMiddleware> logger)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await _next(context);
+        }
+        catch (ValidationException ex)
+        {
+            await HandleValidationExceptionAsync(context, ex);
+        }
+        catch (DomainException ex)
+        {
+            await HandleDomainExceptionAsync(context, ex);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Unhandled exception occurred");
+            await HandleUnhandledExceptionAsync(context, ex);
+        }
+    }
+
+    private static Task HandleValidationExceptionAsync(HttpContext context, ValidationException exception)
+    {
+        context.Response.StatusCode = StatusCodes.Status400BadRequest;
+        context.Response.ContentType = "application/problem+json";
+
+        var problemDetails = new ProblemDetailsResponse
+        {
+            Status = StatusCodes.Status400BadRequest,
+            Title = "Validation Error",
+            Detail = "One or more validation errors occurred",
+            Instance = context.Request.Path,
+            Timestamp = DateTimeOffset.UtcNow,
+            Errors = exception.Errors.GroupBy(e => e.PropertyName)
+                .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray())
+        };
+
+        return context.Response.WriteAsJsonAsync(problemDetails);
+    }
+}
+```
+
+## Security Standards
+
+### Authentication & Authorization
+- **JWT Tokens**: Proper expiration and refresh token handling
+- **RBAC**: Role-based access control with Authorization Policies
+- **Validation**: Input validation on all endpoints (FluentValidation)
+- **Rate Limiting**: ASP.NET Core Rate Limiting middleware
+- **Environment**: HTTPS only in production, secrets in Azure Key Vault or User Secrets
+
+### Data Protection
+- Encrypt sensitive data at rest and in transit
+- Never commit secrets to repository
+- Implement audit logging for critical operations
+- OWASP Top 10 compliance
+- Regular dependency security audits with `dotnet list package --vulnerable`
+
+## Performance Standards
+
+### Database Optimization
+- Proper indexing on frequently queried fields
+- Connection pooling via EF Core (configured in connection string)
+- Pagination for large datasets (Skip/Take or Keyset pagination)
+- Avoid N+1 queries with `.Include()` and `.ThenInclude()`
+- Query monitoring and slow query logging
+- Use `AsNoTracking()` for read-only queries
+
+### Caching Strategy
+- **Distributed Cache**: Redis or SQL Server for distributed scenarios
+- **Memory Cache**: `IMemoryCache` for single-instance caching
+- **TTL Strategy**: Appropriate time-to-live for different data types
+- **Invalidation**: Event-driven cache invalidation
+- **Response Caching**: Use `[ResponseCache]` attribute for GET endpoints
+
+## Additional Standards
+
+### Logging
+- Use `ILogger<T>` for structured logging
+- Log levels: Trace, Debug, Information, Warning, Error, Critical
+- Include correlation IDs for request tracing
+- Never log sensitive information (passwords, tokens, PII)
+
+### API Versioning
+- Use URL versioning: `/api/v1/users`
+- Support multiple versions simultaneously during migration
+- Deprecation notices in response headers
+
+### Health Checks
+- Implement `/health` endpoint for liveness
+- Implement `/health/ready` for readiness checks
+- Include database, cache, and external service checks