feat(api): replace integer PK with UUID v4 for Player entity (#66)

- Add HyphenatedUUID custom TypeDecorator storing UUIDs as CHAR(36) in
  SQLite and returning uuid.UUID objects in Python
- Split PlayerModel into PlayerRequestModel (no id, for POST/PUT) and
  PlayerResponseModel (includes id: UUID, for GET/POST responses)
- Update all route path parameters and service signatures from int to UUID
- Add retrieve_by_squad_number_async() service method; expose via
  GET /players/squadnumber/{squad_number} route
- Change POST conflict detection from ID lookup to squad_number uniqueness
- Return created Player from create_async() after session refresh
- Add migration_001_starting_eleven.py: recreates players table with UUID
  PK and seeds 11 starters with deterministic UUID v5 values
- Add migration_002_substitutes.py: seeds 14 substitutes with deterministic
  UUID v5 values (requires migration 001 to run first)
- Update player_stub.py with UUID-based fixtures; unknown_player() now uses
  a nil-style UUID instead of an integer
- Update test suite to assert UUID presence and version (UUID v4 for
  API-created records); DELETE resolves target UUID via squad number lookup

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: nanotaboada

.github/copilot-instructions.md

@@ -26,6 +26,8 @@ schemas/        — SQLAlchemy ORM models (database schema)           [data laye
 databases/      — async SQLAlchemy session setup
 models/         — Pydantic models for request/response validation
 storage/        — SQLite database file (players-sqlite3.db, pre-seeded)
+scripts/        — shell scripts for Docker (entrypoint.sh, healthcheck.sh)
+tools/          — standalone seed scripts (run manually, not via Alembic)
 tests/          — pytest integration tests
 ```
 
@@ -37,6 +39,8 @@ tests/          — pytest integration tests
 - **Type hints**: Required everywhere — functions, variables, return types
 - **Async**: All routes and service functions must be `async def`; use `AsyncSession` (never `Session`); use `aiosqlite` (never `sqlite3`); use SQLAlchemy 2.0 `select()` (never `session.query()`)
 - **API contract**: camelCase JSON via Pydantic `alias_generator=to_camel`; Python internals stay snake_case
+- **Models**: `PlayerRequestModel` (no `id`, used for POST/PUT) and `PlayerResponseModel` (includes `id: UUID`, used for GET/POST responses); never use the removed `PlayerModel`
+- **Primary key**: UUID surrogate key (`id`) — opaque, internal, used for all CRUD operations. UUID v4 for API-created records; UUID v5 (deterministic) for migration-seeded records. `squad_number` is the natural key — human-readable, domain-meaningful, preferred lookup for external consumers
 - **Caching**: cache key `"players"` (hardcoded); clear on POST/PUT/DELETE; `X-Cache` header (HIT/MISS)
 - **Errors**: Catch specific exceptions with rollback in services; Pydantic validation returns 422 (not 400)
 - **Logging**: `logging` module only; never `print()`
@@ -90,7 +94,7 @@ Example: `feat(api): add player stats endpoint (#42)`
 
 ### Ask before changing
 
-- Database schema (`schemas/player_schema.py` — no Alembic, manual process)
+- Database schema (`schemas/player_schema.py` — no Alembic, use tools/ seed scripts manually)
 - Dependencies (`requirements*.txt`)
 - CI/CD configuration (`.github/workflows/`)
 - Docker setup

.gitignore

@@ -61,6 +61,9 @@ cover/
 local_settings.py
 db.sqlite3
 db.sqlite3-journal
+*.db-shm
+*.db-wal
+*.db.bak.*
 
 # Flask stuff:
 instance/

.vscode/settings.json

@@ -36,6 +36,7 @@
     "**/htmlcov/**",
     "**/postman_collections/**",
     "**/scripts/**",
+    "**/tools/**",
     "**/storage/**",
     "**/__pycache__/**",
     "**/tests/test_main.py"

CHANGELOG.md

@@ -44,8 +44,21 @@ This project uses famous football coaches as release codenames, following an A-Z
 
 ### Added
 
+- UUID v4 primary key for the `players` table, replacing the previous integer PK (#66)
+- `PlayerRequestModel` Pydantic model for POST/PUT request bodies (no `id` field) (#66)
+- `PlayerResponseModel` Pydantic model for GET/POST response bodies (includes `id: UUID`) (#66)
+- `tools/seed_001_starting_eleven.py`: standalone seed script populating 11 starting-eleven players with deterministic UUID v5 PKs (#66)
+- `tools/seed_002_substitutes.py`: standalone seed script populating 14 substitute players with deterministic UUID v5 PKs (#66)
+- `HyphenatedUUID` custom `TypeDecorator` in `schemas/player_schema.py` storing UUIDs as hyphenated `CHAR(36)` strings in SQLite, returning `uuid.UUID` objects in Python (#66)
+
 ### Changed
 
+- `PlayerModel` split into `PlayerRequestModel` and `PlayerResponseModel` in `models/player_model.py` (#66)
+- All route path parameters and service function signatures updated from `int` to `uuid.UUID` (#66)
+- POST conflict detection changed from ID lookup to `squad_number` uniqueness check (#66)
+- `tests/player_stub.py` updated with UUID-based test fixtures (#66)
+- `tests/test_main.py` updated to assert UUID presence and format in API responses (#66)
+
 ### Deprecated
 
 ### Removed

codecov.yml

@@ -44,6 +44,7 @@ ignore:
   - "^models/.*"
   - "^postman_collections/.*"
   - "^schemas/.*"
+  - "^tools/.*"
   - "^tests/.*"
   - ".*\\.yml$"
   - ".*\\.json$"

models/player_model.py

@@ -2,12 +2,14 @@
 Pydantic models defining the data schema for football players.
 
 - `MainModel`: Base model with common config for camelCase aliasing.
-- `PlayerModel`: Represents a football player with personal and team details.
+- `PlayerRequestModel`: Represents player data for Create and Update operations.
+- `PlayerResponseModel`: Represents player data including UUID for Retrieve operations.
 
 These models are used for data validation and serialization in the API.
 """
 
 from typing import Optional
+from uuid import UUID
 from pydantic import BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel
 
@@ -27,15 +29,17 @@ class MainModel(BaseModel):
             Pydantic models.
     """
 
-    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    model_config = ConfigDict(
+        alias_generator=to_camel, populate_by_name=True, from_attributes=True
+    )
 
 
-class PlayerModel(MainModel):
+class PlayerRequestModel(MainModel):
     """
-    Pydantic model representing a football Player.
+    Pydantic model representing the data required for Create and Update operations
+    on a football Player.
 
     Attributes:
-        id (int): The unique identifier for the Player.
         first_name (str): The first name of the Player.
         middle_name (Optional[str]): The middle name of the Player, if any.
         last_name (str): The last name of the Player.
@@ -50,7 +54,6 @@ class PlayerModel(MainModel):
         if provided.
     """
 
-    id: int
     first_name: str
     middle_name: Optional[str]
     last_name: str
@@ -61,3 +64,14 @@ class PlayerModel(MainModel):
     team: Optional[str]
     league: Optional[str]
     starting11: Optional[bool]
+
+
+class PlayerResponseModel(PlayerRequestModel):
+    """
+    Pydantic model representing a football Player with a UUID for Retrieve operations.
+
+    Attributes:
+        id (UUID): The unique identifier for the Player (UUID v4).
+    """
+
+    id: UUID

pyproject.toml

@@ -13,6 +13,7 @@ exclude = '''
   | htmlcov
   | postman_collections
   | scripts
+  | tools
   | storage
   | __pycache__
   | tests/test_main\.py

routes/player_route.py

@@ -11,19 +11,22 @@
 Endpoints:
 - POST /players/                          : Create a new Player.
 - GET /players/                           : Retrieve all Players.
-- GET /players/{player_id}                : Retrieve Player by ID.
-- GET /players/squadnumber/{squad_number} : Retrieve Player by Squad Number.
+- GET /players/{player_id}                : Retrieve Player by UUID
+                                            (surrogate key, internal).
+- GET /players/squadnumber/{squad_number} : Retrieve Player by Squad Number
+                                            (natural key, domain).
 - PUT /players/{player_id}                : Update an existing Player.
 - DELETE /players/{player_id}             : Delete an existing Player.
 """
 
 from typing import List
+from uuid import UUID
 from fastapi import APIRouter, Body, Depends, HTTPException, status, Path, Response
 from sqlalchemy.ext.asyncio import AsyncSession
 from aiocache import SimpleMemoryCache
 
 from databases.player_database import generate_async_session
-from models.player_model import PlayerModel
+from models.player_model import PlayerRequestModel, PlayerResponseModel
 from services import player_service
 
 api_router = APIRouter()
@@ -37,38 +40,45 @@
 
 @api_router.post(
     "/players/",
+    response_model=PlayerResponseModel,
     status_code=status.HTTP_201_CREATED,
     summary="Creates a new Player",
     tags=["Players"],
 )
 async def post_async(
-    player_model: PlayerModel = Body(...),
+    player_model: PlayerRequestModel = Body(...),
     async_session: AsyncSession = Depends(generate_async_session),
 ):
     """
     Endpoint to create a new player.
 
     Args:
-        player_model (PlayerModel): The Pydantic model representing the Player to
-        create.
+        player_model (PlayerRequestModel): The Pydantic model representing the Player
+        to create.
         async_session (AsyncSession): The async version of a SQLAlchemy ORM session.
 
+    Returns:
+        PlayerResponseModel: The created Player with its generated UUID.
+
     Raises:
         HTTPException: HTTP 409 Conflict error if the Player already exists.
     """
-    player = await player_service.retrieve_by_id_async(async_session, player_model.id)
-    if player:
+    existing = await player_service.retrieve_by_squad_number_async(
+        async_session, player_model.squad_number
+    )
+    if existing:
         raise HTTPException(status_code=status.HTTP_409_CONFLICT)
-    await player_service.create_async(async_session, player_model)
+    player = await player_service.create_async(async_session, player_model)
     await simple_memory_cache.clear(CACHE_KEY)
+    return player
 
 
 # GET --------------------------------------------------------------------------
 
 
 @api_router.get(
     "/players/",
-    response_model=List[PlayerModel],
+    response_model=List[PlayerResponseModel],
     status_code=status.HTTP_200_OK,
     summary="Retrieves a collection of Players",
     tags=["Players"],
@@ -83,7 +93,7 @@ async def get_all_async(
         async_session (AsyncSession): The async version of a SQLAlchemy ORM session.
 
     Returns:
-        List[PlayerModel]: A list of Pydantic models representing all players.
+        List[PlayerResponseModel]: A list of Pydantic models representing all players.
     """
     players = await simple_memory_cache.get(CACHE_KEY)
     response.headers["X-Cache"] = "HIT"
@@ -96,27 +106,27 @@ async def get_all_async(
 
 @api_router.get(
     "/players/{player_id}",
-    response_model=PlayerModel,
+    response_model=PlayerResponseModel,
     status_code=status.HTTP_200_OK,
-    summary="Retrieves a Player by its Id",
+    summary="Retrieves a Player by its UUID",
     tags=["Players"],
 )
 async def get_by_id_async(
-    player_id: int = Path(..., title="The ID of the Player"),
+    player_id: UUID = Path(..., title="The UUID of the Player"),
     async_session: AsyncSession = Depends(generate_async_session),
 ):
     """
-    Endpoint to retrieve a Player by its ID.
+    Endpoint to retrieve a Player by its UUID.
 
     Args:
-        player_id (int): The ID of the Player to retrieve.
+        player_id (UUID): The UUID of the Player to retrieve.
         async_session (AsyncSession): The async version of a SQLAlchemy ORM session.
 
     Returns:
-        PlayerModel: The Pydantic model representing the matching Player.
+        PlayerResponseModel: The Pydantic model representing the matching Player.
 
     Raises:
-        HTTPException: Not found error if the Player with the specified ID does not
+        HTTPException: Not found error if the Player with the specified UUID does not
         exist.
     """
     player = await player_service.retrieve_by_id_async(async_session, player_id)
@@ -127,7 +137,7 @@ async def get_by_id_async(
 
 @api_router.get(
     "/players/squadnumber/{squad_number}",
-    response_model=PlayerModel,
+    response_model=PlayerResponseModel,
     status_code=status.HTTP_200_OK,
     summary="Retrieves a Player by its Squad Number",
     tags=["Players"],
@@ -144,7 +154,7 @@ async def get_by_squad_number_async(
         async_session (AsyncSession): The async version of a SQLAlchemy ORM session.
 
     Returns:
-        PlayerModel: The Pydantic model representing the matching Player.
+        PlayerResponseModel: The Pydantic model representing the matching Player.
 
     Raises:
         HTTPException: HTTP 404 Not Found error if the Player with the specified
@@ -168,27 +178,27 @@ async def get_by_squad_number_async(
     tags=["Players"],
 )
 async def put_async(
-    player_id: int = Path(..., title="The ID of the Player"),
-    player_model: PlayerModel = Body(...),
+    player_id: UUID = Path(..., title="The UUID of the Player"),
+    player_model: PlayerRequestModel = Body(...),
     async_session: AsyncSession = Depends(generate_async_session),
 ):
     """
     Endpoint to entirely update an existing Player.
 
     Args:
-        player_id (int): The ID of the Player to update.
-        player_model (PlayerModel): The Pydantic model representing the Player to
-        update.
+        player_id (UUID): The UUID of the Player to update.
+        player_model (PlayerRequestModel): The Pydantic model representing the Player
+        to update.
         async_session (AsyncSession): The async version of a SQLAlchemy ORM session.
 
     Raises:
-        HTTPException: HTTP 404 Not Found error if the Player with the specified ID
+        HTTPException: HTTP 404 Not Found error if the Player with the specified UUID
         does not exist.
     """
     player = await player_service.retrieve_by_id_async(async_session, player_id)
     if not player:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
-    await player_service.update_async(async_session, player_model)
+    await player_service.update_async(async_session, player_id, player_model)
     await simple_memory_cache.clear(CACHE_KEY)
 
 
@@ -202,18 +212,18 @@ async def put_async(
     tags=["Players"],
 )
 async def delete_async(
-    player_id: int = Path(..., title="The ID of the Player"),
+    player_id: UUID = Path(..., title="The UUID of the Player"),
     async_session: AsyncSession = Depends(generate_async_session),
 ):
     """
     Endpoint to delete an existing Player.
 
     Args:
-        player_id (int): The ID of the Player to delete.
+        player_id (UUID): The UUID of the Player to delete.
         async_session (AsyncSession): The async version of a SQLAlchemy ORM session.
 
     Raises:
-        HTTPException: HTTP 404 Not Found error if the Player with the specified ID
+        HTTPException: HTTP 404 Not Found error if the Player with the specified UUID
         does not exist.
     """
     player = await player_service.retrieve_by_id_async(async_session, player_id)