fix(api): enforce squad number immutability on PUT

[nanotaboada]

Summary

• Add mismatch guard in put_async: if squad_number in the request body
  does not match the path parameter, return HTTP 400 Bad Request
• Document the single-model design decision in PlayerRequestModel module
  docstring, explaining why one model covers both POST and PUT
• Add test test_request_put_player_squadnumber_mismatch_response_status_bad_request

Test plan

• PUT /players/squadnumber/23 with body squadNumber: 999 → 400 Bad Request
• PUT /players/squadnumber/23 with body squadNumber: 23 → 204 No Content
• PUT /players/squadnumber/999 (unknown) with matching body → 404 Not Found
• PUT /players/squadnumber/23 with empty body → 422 Unprocessable Entity
• All existing tests pass, coverage remains at 100%

Closes #529

🤖 Generated with Claude Code

---

This change is 

Summary by CodeRabbit

• Bug Fixes
  • The player update endpoint now validates that the squad number in the request body matches the path parameter, returning a 400 Bad Request error if they differ.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5eb105c0-f22b-4cfb-8dc1-befd3b826a52

📥 Commits

Reviewing files that changed from the base of the PR and between 2beb177 and a5ccfa4.

📒 Files selected for processing (3)

• models/player_model.py
• routes/player_route.py
• tests/test_main.py

---

Walkthrough

This PR implements squad number immutability enforcement on the PUT endpoint. When a client submits a PUT request with a squad_number in the request body that differs from the path parameter, the endpoint now validates the mismatch and returns HTTP 400 Bad Request. The implementation adds a validation check in the route layer, documents the design rationale in the model module, and includes a test case covering the mismatch scenario.

Changes

Cohort / File(s)	Summary
Request Model Documentation models/player_model.py	Added module-level documentation clarifying the "single model for both POST and PUT" design decision, explaining that PlayerRequestModel is intentionally shared with behavioral differences handled at the route layer. Documented observable expectations: POST validates squad_number uniqueness; PUT requires request body squad_number to match the path parameter and treats the path parameter as authoritative for identity.
Route Layer Validation routes/player_route.py	Added mismatch guard in put_async endpoint that compares player_model.squad_number from request body against the squad_number path parameter, raising HTTP 400 Bad Request if they differ. Updated endpoint docstring to document the new 400 error condition.
Test Coverage tests/test_main.py	Added new test case test_request_put_player_squadnumber_mismatch_response_status_bad_request that verifies the endpoint returns HTTP 400 when request body squad_number does not match the path parameter.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Assessment against linked issues

Objective	Addressed	Explanation
PUT returns 400 if squad_number in body does not match path parameter [#529]	✅
PlayerRequestModel remains unchanged (single model for POST and PUT) [#529]	✅
New test covers the mismatch scenario [#529]	✅

Possibly related PRs

• PR #524: Modifies the same PUT endpoint in routes/player_route.py to use squad_number as the endpoint parameter; this PR complements it by adding validation to ensure request body squad_number matches the path parameter.

📋 Issue Planner

Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).

View plan for ticket: #529

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/put-squad-number-mismatch-validation

• 🛠️ sync documentation: Commit on current branch
• 🛠️ sync documentation: Create PR
• 🛠️ enforce http error handling: Commit on current branch
• 🛠️ enforce http error handling: Create PR
• 🛠️ idiomatic review: Commit on current branch
• 🛠️ idiomatic review: Create PR
• 🛠️ verify api contract: Commit on current branch
• 🛠️ verify api contract: Create PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (2beb177) to head (a5ccfa4).

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #531   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         3           
  Lines          111       113    +2     
=========================================
+ Hits           111       113    +2     

Components	Coverage Δ
Services	100.00% <ø> (ø)
Routes	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.