feat: implement repository layer and cost-overview endpoint

Add DailyProgressRepository with aggregation methods for efficient data
access layer. Implement cost-overview endpoint that returns profile cost
summary and daily breakdown for a date range.

Repository Features:
- get_by_date: Query progress for profile on specific date with select_related
- get_aggregates_by_profile: Aggregate totals, averages, and counts for date range
- Explicit None handling with ternary operators (no implicit defaults)

Endpoint Features:
- Date range validation with proper YYYY-MM-DD format checking
- Summary statistics: total days, total feet/ice/cost, averages
- Daily breakdown showing only days with actual progress
- Uses repository layer for clean separation of concerns

Tests:
- 7 unit tests for repository methods (filtering, aggregation, edge cases)
- 6 integration tests for cost-overview endpoint (success, validation, errors)

All code passes ruff and mypy with zero violations.

apps/profiles/repositories.py

@@ -0,0 +1,63 @@
+"""Repository layer for Profile app data access."""
+
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+
+from django.db.models import Avg, Count, QuerySet, Sum
+
+from apps.profiles.models import DailyProgress
+
+
+class DailyProgressRepository:
+    """Data access layer for DailyProgress model."""
+
+    def get_by_date(self, profile_id: int, target_date: date) -> QuerySet[DailyProgress]:
+        """Retrieve all progress records for a profile on a specific date.
+
+        Args:
+            profile_id: Profile ID to filter by
+            target_date: Date to retrieve progress for
+
+        Returns:
+            QuerySet of DailyProgress records with wall_section pre-fetched
+        """
+        return DailyProgress.objects.filter(wall_section__profile_id=profile_id, date=target_date).select_related("wall_section")
+
+    def get_aggregates_by_profile(self, profile_id: int, start_date: date, end_date: date) -> dict[str, Decimal | int]:
+        """Get aggregated statistics for a profile within date range.
+
+        Args:
+            profile_id: Profile ID to aggregate for
+            start_date: Start date of range (inclusive)
+            end_date: End date of range (inclusive)
+
+        Returns:
+            Dictionary with aggregated statistics:
+                - total_feet: Sum of feet_built
+                - total_ice: Sum of ice_cubic_yards
+                - total_cost: Sum of cost_gold_dragons
+                - avg_feet: Average feet_built per day
+                - record_count: Number of records in range
+        """
+        result = DailyProgress.objects.filter(
+            wall_section__profile_id=profile_id,
+            date__gte=start_date,
+            date__lte=end_date,
+        ).aggregate(
+            total_feet=Sum("feet_built"),
+            total_ice=Sum("ice_cubic_yards"),
+            total_cost=Sum("cost_gold_dragons"),
+            avg_feet=Avg("feet_built"),
+            record_count=Count("id"),
+        )
+
+        # Explicit None handling - no implicit defaults
+        return {
+            "total_feet": Decimal("0") if result["total_feet"] is None else result["total_feet"],
+            "total_ice": Decimal("0") if result["total_ice"] is None else result["total_ice"],
+            "total_cost": Decimal("0") if result["total_cost"] is None else result["total_cost"],
+            "avg_feet": Decimal("0") if result["avg_feet"] is None else result["avg_feet"],
+            "record_count": result["record_count"],
+        }

apps/profiles/views.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timedelta
 from decimal import Decimal
 
 from django.db.models import Sum
@@ -13,6 +13,7 @@ from rest_framework.request import Request
 from rest_framework.response import Response
 
 from apps.profiles.models import DailyProgress, Profile, WallSection
+from apps.profiles.repositories import DailyProgressRepository
 from apps.profiles.serializers import (
     DailyProgressSerializer,
     ProfileSerializer,
@@ -85,6 +86,96 @@ class ProfileViewSet(viewsets.ModelViewSet[Profile]):
             }
         )
 
+    @action(detail=True, methods=["get"], url_path="cost-overview")
+    def cost_overview(self, request: Request, pk: int) -> Response:
+        """Get cost overview for a profile within a date range."""
+        profile = get_object_or_404(Profile, pk=pk)
+        start_date_str = request.query_params.get("start_date")
+        end_date_str = request.query_params.get("end_date")
+
+        if not start_date_str:
+            return Response(
+                {"error": "start_date parameter is required"},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        if not end_date_str:
+            return Response(
+                {"error": "end_date parameter is required"},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Validate date formats (YYYY-MM-DD)
+        try:
+            start_date = datetime.strptime(start_date_str, "%Y-%m-%d").date()
+        except ValueError:
+            return Response(
+                {"error": "start_date must be in YYYY-MM-DD format"},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        try:
+            end_date = datetime.strptime(end_date_str, "%Y-%m-%d").date()
+        except ValueError:
+            return Response(
+                {"error": "end_date must be in YYYY-MM-DD format"},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Get aggregated statistics using repository
+        repo = DailyProgressRepository()
+        aggregates = repo.get_aggregates_by_profile(profile.id, start_date, end_date)
+
+        # Calculate total days in range
+        total_days = (end_date - start_date).days + 1
+
+        # Calculate average cost per day
+        total_cost = aggregates["total_cost"]
+        record_count = aggregates["record_count"]
+        average_cost_per_day = total_cost / record_count if record_count > 0 else Decimal("0")
+
+        # Build daily breakdown - only include days with actual progress
+        daily_breakdown = []
+        current_date = start_date
+        while current_date <= end_date:
+            day_progress = repo.get_by_date(profile.id, current_date)
+            if day_progress.exists():
+                day_aggregates = day_progress.aggregate(
+                    total_feet=Sum("feet_built"),
+                    total_ice=Sum("ice_cubic_yards"),
+                    total_cost=Sum("cost_gold_dragons"),
+                )
+                # Since day_progress.exists() is True, aggregates cannot be None
+                daily_breakdown.append(
+                    {
+                        "date": current_date.isoformat(),
+                        "feet_built": str(day_aggregates["total_feet"]),
+                        "ice_cubic_yards": str(day_aggregates["total_ice"]),
+                        "cost_gold_dragons": str(day_aggregates["total_cost"]),
+                    }
+                )
+            current_date += timedelta(days=1)
+
+        return Response(
+            {
+                "profile_id": profile.id,
+                "profile_name": profile.name,
+                "date_range": {
+                    "start": start_date_str,
+                    "end": end_date_str,
+                },
+                "summary": {
+                    "total_days": total_days,
+                    "total_feet_built": str(aggregates["total_feet"]),
+                    "total_ice_cubic_yards": str(aggregates["total_ice"]),
+                    "total_cost_gold_dragons": str(aggregates["total_cost"]),
+                    "average_feet_per_day": str(aggregates["avg_feet"]),
+                    "average_cost_per_day": str(average_cost_per_day),
+                },
+                "daily_breakdown": daily_breakdown,
+            }
+        )
+
 
 class WallSectionViewSet(viewsets.ModelViewSet[WallSection]):
     """ViewSet for WallSection CRUD operations."""

tests/integration/test_profile_api.py

@@ -272,3 +272,100 @@ class TestProfileAPI:
         response = api_client.get(url)
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST
+
+    def test_cost_overview_success(self, api_client: APIClient) -> None:
+        """Test cost overview endpoint returns aggregated data for date range."""
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+        section = WallSection.objects.create(
+            profile=profile,
+            section_name="Tower 1-2",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 1),
+            feet_built=Decimal("10.00"),
+            ice_cubic_yards=Decimal("1950.00"),
+            cost_gold_dragons=Decimal("3705000.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 2),
+            feet_built=Decimal("15.00"),
+            ice_cubic_yards=Decimal("2925.00"),
+            cost_gold_dragons=Decimal("5557500.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 3),
+            feet_built=Decimal("20.00"),
+            ice_cubic_yards=Decimal("3900.00"),
+            cost_gold_dragons=Decimal("7410000.00"),
+        )
+
+        url = reverse("profile-cost-overview", kwargs={"pk": profile.id})
+        response = api_client.get(url, {"start_date": "2025-10-01", "end_date": "2025-10-03"})
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data["profile_id"] == profile.id
+        assert response.data["profile_name"] == "Northern Watch"
+        assert response.data["date_range"]["start"] == "2025-10-01"
+        assert response.data["date_range"]["end"] == "2025-10-03"
+        assert response.data["summary"]["total_days"] == 3
+        assert response.data["summary"]["total_feet_built"] == "45.00"
+        assert response.data["summary"]["total_ice_cubic_yards"] == "8775.00"
+        assert response.data["summary"]["total_cost_gold_dragons"] == "16672500.00"
+        assert response.data["summary"]["average_feet_per_day"] == "15.00"
+        assert response.data["summary"]["average_cost_per_day"] == "5557500.00"
+        assert len(response.data["daily_breakdown"]) == 3
+
+    def test_cost_overview_no_data_for_range(self, api_client: APIClient) -> None:
+        """Test cost overview when no progress exists for given date range."""
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+
+        url = reverse("profile-cost-overview", kwargs={"pk": profile.id})
+        response = api_client.get(url, {"start_date": "2025-10-01", "end_date": "2025-10-15"})
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data["summary"]["total_feet_built"] == "0.00"
+        assert response.data["summary"]["total_ice_cubic_yards"] == "0.00"
+        assert response.data["summary"]["total_cost_gold_dragons"] == "0.00"
+        assert response.data["summary"]["average_feet_per_day"] == "0.00"
+        assert response.data["summary"]["average_cost_per_day"] == "0.00"
+        assert response.data["daily_breakdown"] == []
+
+    def test_cost_overview_invalid_profile(self, api_client: APIClient) -> None:
+        """Test cost overview with non-existent profile returns 404."""
+        url = reverse("profile-cost-overview", kwargs={"pk": 9999})
+        response = api_client.get(url, {"start_date": "2025-10-01", "end_date": "2025-10-15"})
+
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+    def test_cost_overview_missing_start_date_param(self, api_client: APIClient) -> None:
+        """Test cost overview without start_date parameter returns 400."""
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+
+        url = reverse("profile-cost-overview", kwargs={"pk": profile.id})
+        response = api_client.get(url, {"end_date": "2025-10-15"})
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST
+
+    def test_cost_overview_missing_end_date_param(self, api_client: APIClient) -> None:
+        """Test cost overview without end_date parameter returns 400."""
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+
+        url = reverse("profile-cost-overview", kwargs={"pk": profile.id})
+        response = api_client.get(url, {"start_date": "2025-10-01"})
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST
+
+    def test_cost_overview_invalid_date_format(self, api_client: APIClient) -> None:
+        """Test cost overview with invalid date format returns 400."""
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+
+        url = reverse("profile-cost-overview", kwargs={"pk": profile.id})
+        response = api_client.get(url, {"start_date": "2025/10/01", "end_date": "2025-10-15"})
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST

tests/unit/test_models.py

@@ -1,4 +1,4 @@
-"""Unit tests for Profile models."""
+"""Unit tests for Profile models and repositories."""
 
 from __future__ import annotations
 
@@ -9,6 +9,7 @@ import pytest
 from django.db import IntegrityError
 
 from apps.profiles.models import DailyProgress, Profile, WallSection
+from apps.profiles.repositories import DailyProgressRepository
 
 
 @pytest.mark.django_db
@@ -152,3 +153,229 @@ class TestDailyProgressModel:
         )
 
         assert str(progress) == "Tower 1-2: 10.00 ft on 2025-10-20"
+
+
+@pytest.mark.django_db
+class TestDailyProgressRepository:
+    """Test DailyProgressRepository data access methods."""
+
+    def test_get_by_date_returns_progress_for_profile_and_date(self) -> None:
+        """Test retrieving all progress records for a profile on a specific date."""
+        repo = DailyProgressRepository()
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+        section1 = WallSection.objects.create(
+            profile=profile,
+            section_name="Tower 1-2",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+        section2 = WallSection.objects.create(
+            profile=profile,
+            section_name="Tower 2-3",
+            start_position=Decimal("500.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+
+        target_date = date(2025, 10, 15)
+        DailyProgress.objects.create(
+            wall_section=section1,
+            date=target_date,
+            feet_built=Decimal("12.50"),
+            ice_cubic_yards=Decimal("2437.50"),
+            cost_gold_dragons=Decimal("4631250.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section2,
+            date=target_date,
+            feet_built=Decimal("16.25"),
+            ice_cubic_yards=Decimal("3168.75"),
+            cost_gold_dragons=Decimal("6020625.00"),
+        )
+
+        results = repo.get_by_date(profile.id, target_date)
+
+        assert results.count() == 2
+        assert all(r.date == target_date for r in results)
+        assert all(r.wall_section.profile_id == profile.id for r in results)
+
+    def test_get_by_date_returns_empty_when_no_data(self) -> None:
+        """Test get_by_date returns empty queryset when no progress exists."""
+        repo = DailyProgressRepository()
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+        target_date = date(2025, 10, 15)
+
+        results = repo.get_by_date(profile.id, target_date)
+
+        assert results.count() == 0
+
+    def test_get_by_date_filters_by_profile(self) -> None:
+        """Test get_by_date only returns progress for specified profile."""
+        repo = DailyProgressRepository()
+        profile1 = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+        profile2 = Profile.objects.create(name="Eastern Defense", team_lead="Tormund")
+        section1 = WallSection.objects.create(
+            profile=profile1,
+            section_name="Tower 1-2",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+        section2 = WallSection.objects.create(
+            profile=profile2,
+            section_name="Tower 5-6",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+
+        target_date = date(2025, 10, 15)
+        DailyProgress.objects.create(
+            wall_section=section1,
+            date=target_date,
+            feet_built=Decimal("12.50"),
+            ice_cubic_yards=Decimal("2437.50"),
+            cost_gold_dragons=Decimal("4631250.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section2,
+            date=target_date,
+            feet_built=Decimal("20.00"),
+            ice_cubic_yards=Decimal("3900.00"),
+            cost_gold_dragons=Decimal("7410000.00"),
+        )
+
+        results = repo.get_by_date(profile1.id, target_date)
+
+        assert results.count() == 1
+        first_result = results.first()
+        assert first_result is not None
+        assert first_result.wall_section.profile_id == profile1.id
+
+    def test_get_aggregates_by_profile_returns_summary_stats(self) -> None:
+        """Test aggregated statistics for a profile within date range."""
+        repo = DailyProgressRepository()
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+        section = WallSection.objects.create(
+            profile=profile,
+            section_name="Tower 1-2",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 1),
+            feet_built=Decimal("10.00"),
+            ice_cubic_yards=Decimal("1950.00"),
+            cost_gold_dragons=Decimal("3705000.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 2),
+            feet_built=Decimal("15.00"),
+            ice_cubic_yards=Decimal("2925.00"),
+            cost_gold_dragons=Decimal("5557500.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 3),
+            feet_built=Decimal("20.00"),
+            ice_cubic_yards=Decimal("3900.00"),
+            cost_gold_dragons=Decimal("7410000.00"),
+        )
+
+        result = repo.get_aggregates_by_profile(profile.id, date(2025, 10, 1), date(2025, 10, 3))
+
+        assert result["total_feet"] == Decimal("45.00")
+        assert result["total_ice"] == Decimal("8775.00")
+        assert result["total_cost"] == Decimal("16672500.00")
+        assert result["avg_feet"] == Decimal("15.00")
+        assert result["record_count"] == 3
+
+    def test_get_aggregates_by_profile_filters_date_range(self) -> None:
+        """Test aggregates only include data within specified date range."""
+        repo = DailyProgressRepository()
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+        section = WallSection.objects.create(
+            profile=profile,
+            section_name="Tower 1-2",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 9, 30),
+            feet_built=Decimal("10.00"),
+            ice_cubic_yards=Decimal("1950.00"),
+            cost_gold_dragons=Decimal("3705000.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 1),
+            feet_built=Decimal("15.00"),
+            ice_cubic_yards=Decimal("2925.00"),
+            cost_gold_dragons=Decimal("5557500.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section,
+            date=date(2025, 10, 4),
+            feet_built=Decimal("20.00"),
+            ice_cubic_yards=Decimal("3900.00"),
+            cost_gold_dragons=Decimal("7410000.00"),
+        )
+
+        result = repo.get_aggregates_by_profile(profile.id, date(2025, 10, 1), date(2025, 10, 3))
+
+        assert result["total_feet"] == Decimal("15.00")
+        assert result["record_count"] == 1
+
+    def test_get_aggregates_by_profile_returns_zeros_when_no_data(self) -> None:
+        """Test aggregates return explicit zeros when no data exists."""
+        repo = DailyProgressRepository()
+        profile = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+
+        result = repo.get_aggregates_by_profile(profile.id, date(2025, 10, 1), date(2025, 10, 15))
+
+        assert result["total_feet"] == Decimal("0")
+        assert result["total_ice"] == Decimal("0")
+        assert result["total_cost"] == Decimal("0")
+        assert result["avg_feet"] == Decimal("0")
+        assert result["record_count"] == 0
+
+    def test_get_aggregates_by_profile_filters_by_profile(self) -> None:
+        """Test aggregates only include data for specified profile."""
+        repo = DailyProgressRepository()
+        profile1 = Profile.objects.create(name="Northern Watch", team_lead="Jon Snow")
+        profile2 = Profile.objects.create(name="Eastern Defense", team_lead="Tormund")
+        section1 = WallSection.objects.create(
+            profile=profile1,
+            section_name="Tower 1-2",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+        section2 = WallSection.objects.create(
+            profile=profile2,
+            section_name="Tower 5-6",
+            start_position=Decimal("0.00"),
+            target_length_feet=Decimal("500.00"),
+        )
+
+        target_date = date(2025, 10, 1)
+        DailyProgress.objects.create(
+            wall_section=section1,
+            date=target_date,
+            feet_built=Decimal("10.00"),
+            ice_cubic_yards=Decimal("1950.00"),
+            cost_gold_dragons=Decimal("3705000.00"),
+        )
+        DailyProgress.objects.create(
+            wall_section=section2,
+            date=target_date,
+            feet_built=Decimal("50.00"),
+            ice_cubic_yards=Decimal("9750.00"),
+            cost_gold_dragons=Decimal("18525000.00"),
+        )
+
+        result = repo.get_aggregates_by_profile(profile1.id, target_date, target_date)
+
+        assert result["total_feet"] == Decimal("10.00")
+        assert result["record_count"] == 1