[FEATURE] Implement PATCH method for partial player updates

[nanotaboada]

Problem

Currently, the API only supports PUT operations for updating player data, which requires sending the entire player object even when only one or two fields need to be modified. This is inefficient and doesn't follow REST best practices for partial resource updates. Users need a way to update specific player fields without having to provide all player data.

Proposed Solution

Implement HTTP PATCH method endpoints to allow partial updates of player resources. The API should accept a PlayerPartialUpdateRequestModel and update only the fields provided in the request, leaving other fields unchanged.

Important constraint: Partial updates should allow modifying team-related data (position, squad number, team, league) but NOT personal details (FirstName, MiddleName, LastName, DateOfBirth). Personal information should only be modified via PUT (full update).

Endpoint to implement:

• PATCH /players/squadnumber/{squadNumber} - Update specific fields of a player by squad number

Note: We use squad number (natural identifier) instead of internal ID, as squad numbers are unique and user-facing. The ID-based endpoint is admin-only.

Suggested Approach

1. Route/Controller Definition (Controllers/PlayerController.cs)

• Add [HttpPatch("squadnumber/{squadNumber}")] endpoint with PatchBySquadNumberAsync(int squadNumber, PlayerPartialUpdateRequestModel model) method
• Return TypedResults.Ok() (200), TypedResults.NotFound() (404), TypedResults.BadRequest() (400), or TypedResults.Conflict() (409)
• Use primary constructor for dependency injection

2. Service Layer (Services/PlayerService.cs)

• Create Task<PlayerResponseModel?> PatchBySquadNumberAsync(int squadNumber, PlayerPartialUpdateRequestModel model) method
• If updating SquadNumber field itself, validate new squad number doesn't create duplicates
• Clear cache after successful updates (_cache.Remove(CacheKey_RetrieveAsync))
• Use repository layer to fetch, update, and save entity
• Use AutoMapper to transform PlayerPartialUpdateRequestModel to entity updates
• Add structured logging with ILogger<PlayerService>

3. Repository Layer (Repositories/PlayerRepository.cs)

• Reuse existing repository method GetBySquadNumberAsync and UpdateAsync
• Apply partial updates to entity using AutoMapper or manual property mapping
• Ensure only non-null properties from request model are applied to entity

4. Model Definition (Models/)

• Refactor existing models to follow Request/Response pattern:
  • Rename PlayerRequestModel to PlayerCreateRequestModel (for POST)
  • Create PlayerUpdateRequestModel class (for PUT - full replacement, all fields)
  • Create PlayerPartialUpdateRequestModel class with only team-related fields as nullable:

    public class PlayerPartialUpdateRequestModel
    {
        public int? SquadNumber { get; set; }
        public string? AbbrPosition { get; set; }
        public string? Team { get; set; }
        public string? League { get; set; }
        // Excludes: FirstName, MiddleName, LastName, DateOfBirth
    }

  • Keep PlayerResponseModel as is - already demonstrates data transformations:

    // Entity (Player) → Response (PlayerResponseModel) transformations:
    // - FirstName + MiddleName + LastName → FullName (concatenation)
    // - DateOfBirth (DateTime) → Birth (formatted string)
    // - SquadNumber → Dorsal (different naming)
    // - Team → Club (different naming)
    // - Starting11 (bool) → Starting11 ("Yes"/"No" string)

• All models follow PascalCase with Model suffix
• AutoMapper handles all transformations (configured in PlayerMappingProfile)

5. Validation (Validators/)

• Create PlayerPartialUpdateRequestModelValidator with FluentValidation rules
• Validate squad number range and uniqueness (async validator checking repository)
• Validate position abbreviation using Position.FromAbbr() if position is provided
• Register validator in ServiceCollectionExtensions.AddValidation()

6. AutoMapper Configuration (Mappings/PlayerMappingProfile.cs)

• Add mapping from PlayerPartialUpdateRequestModel to Player entity
• Configure to ignore null values (Condition(src => src != null))
• Update existing mappings to reflect renamed models (PlayerCreateRequestModel, PlayerUpdateRequestModel)
• Verify existing Player → PlayerResponseModel mapping demonstrates data transformations:
  • FullName computed from FirstName + MiddleName + LastName
  • Birth formatted from DateOfBirth
  • Dorsal mapped from SquadNumber
  • Club mapped from Team
  • Starting11 converted from bool to "Yes"/"No" string
• This mapping demonstrates AutoMapper's transformation capabilities

7. Testing (test/Dotnet.Samples.AspNetCore.WebApi.Tests/)

• Create PlayerServiceTests test methods for PATCH operations using Given-When-Then pattern
• Create PlayerControllerTests test methods for PATCH endpoint
• Test partial updates (single field, multiple fields)
• Test squad number uniqueness validation when updating to new squad number
• Test 404 response for non-existent player by squad number
• Test that personal details cannot be modified via PATCH
• Test cache invalidation after PATCH operations
• Use PlayerFakes and PlayerMocks utilities for test data
• Add [Trait("Category", "Unit")] attributes
• Follow AAA pattern (Arrange, Act, Assert)

8. Code Style

• Use primary constructors for dependency injection
• Format with CSharpier (opinionated style)
• Follow async/await patterns consistently (async Task<T> return types)
• Use var for local variables when type is obvious
• Add XML documentation comments for public methods
• Use structured logging patterns with Serilog

Acceptance Criteria

• Models refactored to use Request/Response pattern:
  • PlayerResponseModel for GET operations
  • PlayerCreateRequestModel for POST operations (renamed from PlayerRequestModel)
  • PlayerUpdateRequestModel for PUT operations (new)
  • PlayerPartialUpdateRequestModel for PATCH operations (excludes personal details)
• PATCH endpoint /players/squadnumber/{squadNumber} successfully updates team-related player fields
• Personal details (FirstName, MiddleName, LastName, DateOfBirth) cannot be modified via PATCH
• Only fields provided in request body are updated (other fields remain unchanged)
• Squad number uniqueness is validated when updating to new squad number via FluentValidation
• Appropriate HTTP status codes returned (200 OK, 404 Not Found, 400 Bad Request, 409 Conflict)
• Cache is invalidated after successful PATCH operations
• All tests pass with dotnet test
• Test coverage includes new service and controller method
• Code formatted with CSharpier
• Swagger/OpenAPI documentation reflects new model names and PATCH endpoint
• Structured logging includes relevant context (squad numbers)

References

• RFC 5789 - PATCH Method for HTTP
• ASP.NET Core - HTTP PATCH
• AutoMapper - Conditional Mapping
• FluentValidation - Async Validation

[coderabbitai]

🤖 CodeRabbit Planning

Planning is in progress. This will take a moment...

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#189 - feat(data)!: implement Repository pattern [merged]
#194 - feat(service)!: migrate to AutoMapper for Model mapping [merged]
#206 - refactor(tests): more idiomatic Fake methods and result assertions [merged]
#208 - feature/identifiers [merged]
#334 - feat: add 15 substitute players to database via migration [merged]

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Implement HTTP PATCH endpoint for partial player updates to allow modifying team-related fields (squad number, position, team, league) without requiring full player data, while preventing updates to personal information. Additionally, refactor existing models to follow a clearer Request/Response naming pattern.

Observations

This is an ASP.NET Core Web API project with a three-layer architecture (Controller → Service → Repository) using Entity Framework Core with SQLite. The codebase follows modern C# 12 patterns including primary constructors, uses AutoMapper for DTO transformations, FluentValidation for request validation, and IMemoryCache with purge-on-write invalidation. Controllers return IResult via TypedResults helpers, and tests follow AAA pattern with Moq and FluentAssertions.

Assumptions

Assumption 1: Squad Number Uniqueness Validation During PATCH

Options Considered:

• Check if the new squad number exists on any player (including current player)
• Check if the new squad number exists on any OTHER player (excluding the current player being updated)

Chosen Option: 2

Rationale: The validator should exclude the current player when checking uniqueness, since we're identifying the player by their current squad number in the route and potentially changing it in the request body. This allows updating other fields without requiring a squad number change, and properly validates only when the squad number is actually changing to a value used by someone else.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Model Refactoring and Creation

This phase establishes clearer API semantics by renaming existing models and creating new ones for different operation types. This affects the Models directory, all validators, AutoMapper profiles, and test utilities.

Task 1: Create New Model Classes

Create three new model classes to replace and complement the existing PlayerRequestModel

• Create PlayerCreateRequestModel in src/Dotnet.Samples.AspNetCore.WebApi/Models/ with identical structure to current PlayerRequestModel (FirstName, MiddleName, LastName, DateOfBirth, SquadNumber, AbbrPosition, Team, League)
• Create PlayerUpdateRequestModel in same directory with same properties as PlayerCreateRequestModel (represents full replacement via PUT)
• Create PlayerPartialUpdateRequestModel in same directory with only nullable team-related fields: int? SquadNumber, string? AbbrPosition, string? Team, string? League (excludes personal details intentionally)

Task 2: Update Model References in Controller

Update PlayerController to use the new model naming throughout all endpoints

• Update PostAsync method signature in src/Dotnet.Samples.AspNetCore.WebApi/Controllers/PlayerController.cs to accept PlayerCreateRequestModel instead of PlayerRequestModel
• Update PutAsync method signature to accept PlayerUpdateRequestModel instead of PlayerRequestModel
• Update primary constructor to inject IValidator<PlayerCreateRequestModel> instead of IValidator<PlayerRequestModel>
• Add new validator parameter IValidator<PlayerPartialUpdateRequestModel> to constructor for future PATCH endpoint

Task 3: Update Model References in Service Layer

Update IPlayerService interface and PlayerService implementation to use new model names

• Update CreateAsync signature in src/Dotnet.Samples.AspNetCore.WebApi/Services/IPlayerService.cs to accept PlayerCreateRequestModel
• Update UpdateAsync signature in same file to accept PlayerUpdateRequestModel
• Update CreateAsync implementation in src/Dotnet.Samples.AspNetCore.WebApi/Services/PlayerService.cs to use PlayerCreateRequestModel
• Update UpdateAsync implementation in same file to use PlayerUpdateRequestModel

Task 4: Update Validator References

Rename existing validator and update its model references

• Rename PlayerRequestModelValidator.cs to PlayerCreateRequestModelValidator.cs in src/Dotnet.Samples.AspNetCore.WebApi/Validators/
• Update class declaration to inherit from AbstractValidator<PlayerCreateRequestModel>
• Update constructor and all validation rules to reference PlayerCreateRequestModel properties
• Update validator registration in src/Dotnet.Samples.AspNetCore.WebApi/Extensions/ServiceCollectionExtensions.cs to use AddValidatorsFromAssemblyContaining<PlayerCreateRequestModelValidator>()

Task 5: Update AutoMapper Profile

Update mapping configurations to use new model names

• Update CreateMap<PlayerRequestModel, Player>() to CreateMap<PlayerCreateRequestModel, Player>() in src/Dotnet.Samples.AspNetCore.WebApi/Mappings/PlayerMappingProfile.cs
• Add CreateMap<PlayerUpdateRequestModel, Player>() with identical configuration
• Keep existing CreateMap<Player, PlayerResponseModel>() unchanged

Task 6: Update Test Utilities and Test Files

Update all test utilities and test cases to use new model names

• Update MakeRequestModelForCreate() method in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/PlayerFakes.cs to return PlayerCreateRequestModel
• Update InitControllerMocks() method in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/PlayerMocks.cs to mock IValidator<PlayerCreateRequestModel>
• Update all test method signatures in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerControllerTests.cs that use PlayerRequestModel to use PlayerCreateRequestModel
• Update all test method signatures in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerServiceTests.cs similarly

🤖 Prompt for AI agents

Refactor model classes to follow clearer Request/Response naming pattern. The
goal is to distinguish between Create, Update, and PartialUpdate operations.

Create new model classes:
- `PlayerCreateRequestModel` with all fields (FirstName, MiddleName, LastName,
DateOfBirth, SquadNumber, AbbrPosition, Team, League)
- `PlayerUpdateRequestModel` with same fields as PlayerCreateRequestModel
- `PlayerPartialUpdateRequestModel` with nullable team-related fields only (int?
SquadNumber, string? AbbrPosition, string? Team, string? League)

Update all references from `PlayerRequestModel` to appropriate new model names:
- Controller: Update PostAsync to use PlayerCreateRequestModel, PutAsync to use
PlayerUpdateRequestModel, add IValidator<PlayerPartialUpdateRequestModel> to
constructor
- Service layer: Update IPlayerService and PlayerService method signatures for
CreateAsync and UpdateAsync
- Validators: Rename PlayerRequestModelValidator to
PlayerCreateRequestModelValidator and update class declaration
- AutoMapper: Update mapping profile to use new model names and add mapping for
PlayerUpdateRequestModel
- Tests: Update all test utilities and test files to use new model names

Phase 2: PATCH Endpoint Implementation

This phase adds the new HTTP PATCH endpoint and supporting service/repository methods to enable partial updates of team-related fields while preventing personal information changes.

Task 1: Add PATCH Endpoint to Controller

Add new PATCH endpoint that accepts partial updates by squad number

• Add PatchBySquadNumberAsync(int squadNumber, PlayerPartialUpdateRequestModel model) method in src/Dotnet.Samples.AspNetCore.WebApi/Controllers/PlayerController.cs
• Decorate with [HttpPatch("squadnumber/{squadNumber:int}")] and [ProducesResponseType] attributes for 200/400/404/409 status codes
• Validate request model using injected IValidator<PlayerPartialUpdateRequestModel>
• Call service layer's PatchBySquadNumberAsync method
• Return TypedResults.Ok() with PlayerResponseModel on success, TypedResults.NotFound() if player doesn't exist, TypedResults.BadRequest() for validation errors, TypedResults.Conflict() for squad number conflicts

Task 2: Add Service Method for Partial Updates

Implement business logic for partial player updates with cache invalidation

• Add Task<PlayerResponseModel?> PatchBySquadNumberAsync(int squadNumber, PlayerPartialUpdateRequestModel model) signature to src/Dotnet.Samples.AspNetCore.WebApi/Services/IPlayerService.cs
• Implement method in src/Dotnet.Samples.AspNetCore.WebApi/Services/PlayerService.cs to:
  • Fetch existing player using playerRepository.FindBySquadNumberAsync(squadNumber)
  • Return null if player not found
  • Map partial update model onto fetched entity using AutoMapper's conditional mapping (only non-null properties)
  • Call playerRepository.UpdateAsync(player) to persist changes
  • Invalidate cache with memoryCache.Remove(CacheKey_RetrieveAsync)
  • Map updated entity to PlayerResponseModel and return
  • Add structured logging for fetch, update, and cache invalidation events

🤖 Prompt for AI agents

Add HTTP PATCH endpoint to enable partial updates of team-related fields. The
goal is to allow updating squad number, position, team, and league without
requiring full player data.

Controller:
- Add PatchBySquadNumberAsync method with
[HttpPatch("squadnumber/{squadNumber:int}")] route
- Accept PlayerPartialUpdateRequestModel parameter
- Validate using IValidator<PlayerPartialUpdateRequestModel>
- Return appropriate status codes: 200 Ok (success), 400 BadRequest (validation
errors), 404 NotFound (player not found), 409 Conflict (squad number conflicts)

Service Layer:
- Add PatchBySquadNumberAsync method to IPlayerService interface returning
Task<PlayerResponseModel?>
- Implement method to fetch existing player by squad number, return null if not
found
- Use AutoMapper to map partial update onto existing entity (only non-null
properties)
- Persist changes via repository UpdateAsync
- Invalidate cache
- Map and return updated entity as PlayerResponseModel
- Include structured logging

Phase 3: Validation and Conditional Mapping

This phase adds FluentValidation rules for partial updates and configures AutoMapper to handle null-aware mapping for PATCH operations.

Task 1: Create Partial Update Validator

Implement validation rules specific to partial updates with conditional async checks

• Create PlayerPartialUpdateRequestModelValidator.cs in src/Dotnet.Samples.AspNetCore.WebApi/Validators/
• Inherit from AbstractValidator<PlayerPartialUpdateRequestModel> with primary constructor injecting IPlayerRepository
• Add validation rules:
  • SquadNumber: When provided (not null), validate GreaterThan(0) and async uniqueness via custom method
  • AbbrPosition: When provided, validate using Position.IsValidAbbr() with Must() rule
  • Team and League: No specific validation beyond implicit null acceptance
• For squad number uniqueness: Implement async validator that checks if the new squad number exists on any player except one with matching current squad number (handle this in service layer instead - validator doesn't have context of which player is being updated)

Task 2: Configure AutoMapper for Partial Updates

Add conditional mapping configuration to update only non-null properties

• Add CreateMap<PlayerPartialUpdateRequestModel, Player>() in src/Dotnet.Samples.AspNetCore.WebApi/Mappings/PlayerMappingProfile.cs
• Configure each property mapping with .Condition(src => src.[Property] != null) to skip null values:
  • SquadNumber with condition checking for non-null int?
  • AbbrPosition with condition and Position.FromAbbr() transformation
  • Team with null condition
  • League with null condition
• Ensure Position mapping uses MapFrom(src => Position.FromAbbr(src.AbbrPosition ?? string.Empty)) wrapped in condition

🤖 Prompt for AI agents

Add validation and conditional mapping for partial updates. The goal is to
validate only provided fields and map only non-null properties.

Validator:
- Create PlayerPartialUpdateRequestModelValidator inheriting from
AbstractValidator<PlayerPartialUpdateRequestModel>
- Inject IPlayerRepository via primary constructor
- Add conditional validation rules:
  - SquadNumber: When not null, validate GreaterThan(0) and async uniqueness
  - AbbrPosition: When not null, validate using Position.IsValidAbbr()
  - Team and League: Allow nulls without additional validation
- Note: Squad number uniqueness should exclude the current player being updated
(handle in service layer as validator lacks context)

AutoMapper:
- Add CreateMap<PlayerPartialUpdateRequestModel, Player> to PlayerMappingProfile
- Configure conditional mapping for each property to skip null values:
  - SquadNumber with .Condition(src => src.SquadNumber != null)
  - AbbrPosition with .Condition() and Position.FromAbbr() transformation
  - Team with .Condition()
  - League with .Condition()
- Ensures only provided fields are updated on existing entity

Phase 4: Testing Coverage

This phase adds comprehensive unit tests for the new PATCH functionality covering success scenarios, error cases, validation, and cache behavior.

Task 1: Add Service Layer Tests for PATCH

Create test methods for PatchBySquadNumberAsync covering all scenarios

• Add test methods in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerServiceTests.cs:
  • GivenPatchBySquadNumberAsync_WhenSingleFieldUpdated_ThenOnlyThatFieldChanges - verify partial update with SquadNumber only
  • GivenPatchBySquadNumberAsync_WhenMultipleFieldsUpdated_ThenAllProvidedFieldsChange - verify partial update with multiple fields
  • GivenPatchBySquadNumberAsync_WhenPlayerNotFound_ThenReturnsNull - verify 404 scenario
  • GivenPatchBySquadNumberAsync_WhenSuccessful_ThenCacheInvalidated - verify cache removal
  • GivenPatchBySquadNumberAsync_WhenNullFieldsProvided_ThenThoseFieldsUnchanged - verify null fields are ignored
• Use PlayerFakes.MakeFromStarting11() for test data and PlayerMocks.InitServiceMocks() for dependency setup
• Follow AAA pattern with Given-When-Then naming and [Trait("Category", "Unit")] attributes

Task 2: Add Controller Tests for PATCH Endpoint

Create test methods for PatchBySquadNumberAsync endpoint covering HTTP responses

• Add test methods in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/PlayerControllerTests.cs:
  • GivenPatchBySquadNumberAsync_WhenValidRequest_ThenReturns200Ok - verify successful partial update
  • GivenPatchBySquadNumberAsync_WhenPlayerNotFound_ThenReturns404NotFound - verify 404 response
  • GivenPatchBySquadNumberAsync_WhenValidationFails_ThenReturns400BadRequest - verify validation error handling
  • GivenPatchBySquadNumberAsync_WhenSquadNumberConflict_ThenReturns409Conflict - verify conflict detection
• Mock IPlayerService.PatchBySquadNumberAsync() and IValidator<PlayerPartialUpdateRequestModel>.ValidateAsync() using Moq
• Use PlayerMocks.InitControllerMocks() and extend it to include the new validator
• Verify service method is called with correct parameters and not called when validation fails

Task 3: Add Test Utility Support for PATCH

Extend test utilities to support partial update scenarios

• Add MakePartialUpdateRequestModel() method in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/PlayerFakes.cs returning PlayerPartialUpdateRequestModel with sample team-related data
• Add overloads for creating partial models with specific field combinations (single field, multiple fields, null fields)
• Update InitControllerMocks() in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Utilities/PlayerMocks.cs to return tuple including Mock<IValidator<PlayerPartialUpdateRequestModel>>

Task 4: Add Validator Tests for Partial Update Model

Create test methods verifying validation rules for partial updates

• Add test file PlayerPartialUpdateRequestModelValidatorTests.cs in test/Dotnet.Samples.AspNetCore.WebApi.Tests/Unit/Validators/ directory
• Test squad number validation: invalid range, null (should pass), valid value
• Test position abbreviation validation: invalid abbreviation, null (should pass), valid abbreviation
• Test async squad number uniqueness when applicable
• Use Moq to setup IPlayerRepository responses for existence checks
• Follow existing validator test patterns with AAA and Given-When-Then naming

🤖 Prompt for AI agents

Add comprehensive unit tests for PATCH endpoint functionality. The goal is to
ensure correct behavior for all scenarios including success, errors, validation,
and cache invalidation.

Service Layer Tests:
- Test PatchBySquadNumberAsync with single field update (only SquadNumber
changes)
- Test multiple fields updated simultaneously
- Test player not found returns null
- Test cache invalidation on successful update
- Test null fields are ignored and don't change existing values
- Use PlayerFakes and PlayerMocks for test setup
- Follow AAA pattern with Given-When-Then naming

Controller Tests:
- Test valid request returns 200 Ok with PlayerResponseModel
- Test player not found returns 404 NotFound
- Test validation failures return 400 BadRequest
- Test squad number conflicts return 409 Conflict
- Mock IPlayerService.PatchBySquadNumberAsync and
IValidator<PlayerPartialUpdateRequestModel>
- Verify service method called with correct parameters

Test Utilities:
- Add MakePartialUpdateRequestModel() to PlayerFakes with sample team-related
data
- Add overloads for various field combinations
- Extend InitControllerMocks() to include
Mock<IValidator<PlayerPartialUpdateRequestModel>>

Validator Tests:
- Create PlayerPartialUpdateRequestModelValidatorTests
- Test SquadNumber validation: invalid range, null (pass), valid value
- Test AbbrPosition validation: invalid abbreviation, null (pass), valid
abbreviation
- Test async squad number uniqueness
- Mock IPlayerRepository for existence checks

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Refactor model classes to follow clearer Request/Response naming pattern. The
goal is to distinguish between Create, Update, and PartialUpdate operations.

Create new model classes:
- `PlayerCreateRequestModel` with all fields (FirstName, MiddleName, LastName,
DateOfBirth, SquadNumber, AbbrPosition, Team, League)
- `PlayerUpdateRequestModel` with same fields as PlayerCreateRequestModel
- `PlayerPartialUpdateRequestModel` with nullable team-related fields only (int?
SquadNumber, string? AbbrPosition, string? Team, string? League)

Update all references from `PlayerRequestModel` to appropriate new model names:
- Controller: Update PostAsync to use PlayerCreateRequestModel, PutAsync to use
PlayerUpdateRequestModel, add IValidator<PlayerPartialUpdateRequestModel> to
constructor
- Service layer: Update IPlayerService and PlayerService method signatures for
CreateAsync and UpdateAsync
- Validators: Rename PlayerRequestModelValidator to
PlayerCreateRequestModelValidator and update class declaration
- AutoMapper: Update mapping profile to use new model names and add mapping for
PlayerUpdateRequestModel
- Tests: Update all test utilities and test files to use new model names
===============================================================================

Task: 2

Add HTTP PATCH endpoint to enable partial updates of team-related fields. The
goal is to allow updating squad number, position, team, and league without
requiring full player data.

Controller:
- Add PatchBySquadNumberAsync method with
[HttpPatch("squadnumber/{squadNumber:int}")] route
- Accept PlayerPartialUpdateRequestModel parameter
- Validate using IValidator<PlayerPartialUpdateRequestModel>
- Return appropriate status codes: 200 Ok (success), 400 BadRequest (validation
errors), 404 NotFound (player not found), 409 Conflict (squad number conflicts)

Service Layer:
- Add PatchBySquadNumberAsync method to IPlayerService interface returning
Task<PlayerResponseModel?>
- Implement method to fetch existing player by squad number, return null if not
found
- Use AutoMapper to map partial update onto existing entity (only non-null
properties)
- Persist changes via repository UpdateAsync
- Invalidate cache
- Map and return updated entity as PlayerResponseModel
- Include structured logging
===============================================================================

Task: 3

Add validation and conditional mapping for partial updates. The goal is to
validate only provided fields and map only non-null properties.

Validator:
- Create PlayerPartialUpdateRequestModelValidator inheriting from
AbstractValidator<PlayerPartialUpdateRequestModel>
- Inject IPlayerRepository via primary constructor
- Add conditional validation rules:
  - SquadNumber: When not null, validate GreaterThan(0) and async uniqueness
  - AbbrPosition: When not null, validate using Position.IsValidAbbr()
  - Team and League: Allow nulls without additional validation
- Note: Squad number uniqueness should exclude the current player being updated
(handle in service layer as validator lacks context)

AutoMapper:
- Add CreateMap<PlayerPartialUpdateRequestModel, Player> to PlayerMappingProfile
- Configure conditional mapping for each property to skip null values:
  - SquadNumber with .Condition(src => src.SquadNumber != null)
  - AbbrPosition with .Condition() and Position.FromAbbr() transformation
  - Team with .Condition()
  - League with .Condition()
- Ensures only provided fields are updated on existing entity
===============================================================================

Task: 4

Add comprehensive unit tests for PATCH endpoint functionality. The goal is to
ensure correct behavior for all scenarios including success, errors, validation,
and cache invalidation.

Service Layer Tests:
- Test PatchBySquadNumberAsync with single field update (only SquadNumber
changes)
- Test multiple fields updated simultaneously
- Test player not found returns null
- Test cache invalidation on successful update
- Test null fields are ignored and don't change existing values
- Use PlayerFakes and PlayerMocks for test setup
- Follow AAA pattern with Given-When-Then naming

Controller Tests:
- Test valid request returns 200 Ok with PlayerResponseModel
- Test player not found returns 404 NotFound
- Test validation failures return 400 BadRequest
- Test squad number conflicts return 409 Conflict
- Mock IPlayerService.PatchBySquadNumberAsync and
IValidator<PlayerPartialUpdateRequestModel>
- Verify service method called with correct parameters

Test Utilities:
- Add MakePartialUpdateRequestModel() to PlayerFakes with sample team-related
data
- Add overloads for various field combinations
- Extend InitControllerMocks() to include
Mock<IValidator<PlayerPartialUpdateRequestModel>>

Validator Tests:
- Create PlayerPartialUpdateRequestModelValidatorTests
- Test SquadNumber validation: invalid range, null (pass), valid value
- Test AbbrPosition validation: invalid abbreviation, null (pass), valid
abbreviation
- Test async squad number uniqueness
- Mock IPlayerRepository for existence checks

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!