feat: add math engine and puzzle services

backend/contest/views.py

@@ -3,7 +3,8 @@ from rest_framework import permissions, status
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from .models import Contest, ContestAttempt, RealtimeMatch
+from .game_services import game_payload, request_sudoku_hint, start_game, submit_game
+from .models import Contest, ContestAttempt, MathGameAttempt, RealtimeMatch
 from .services import (
     find_match,
     match_payload,
@@ -98,3 +99,59 @@ class LeaderboardView(APIView):
                 for index, attempt in enumerate(attempts, start=1)
             ]
         )
+
+
+class MathGameCatalogView(APIView):
+    permission_classes = [permissions.AllowAny]
+
+    def get(self, request):
+        return Response(
+            [
+                {
+                    "kind": MathGameAttempt.Kind.TWENTY_FOUR,
+                    "title": "24 点",
+                    "summary": "四个数字各用一次，只用四则运算得到 24。",
+                    "ability": "connection",
+                    "estimated_minutes": 3,
+                },
+                {
+                    "kind": MathGameAttempt.Kind.SUDOKU,
+                    "title": "数独",
+                    "summary": "在行、列和九宫格约束中完成 9×9 数字推理。",
+                    "ability": "detection",
+                    "estimated_minutes": 8,
+                },
+            ]
+        )
+
+
+class MathGameStartView(APIView):
+    def post(self, request, kind):
+        payload = start_game(
+            request.user,
+            kind,
+            request.data.get("difficulty", MathGameAttempt.Difficulty.STANDARD),
+        )
+        return Response(payload, status=status.HTTP_201_CREATED)
+
+
+class MathGameSubmitView(APIView):
+    def post(self, request, attempt_id):
+        payload = submit_game(
+            request.user,
+            attempt_id,
+            request.data,
+            request.headers.get("Idempotency-Key"),
+        )
+        return Response(payload)
+
+
+class SudokuHintView(APIView):
+    def post(self, request, attempt_id):
+        return Response(request_sudoku_hint(request.user, attempt_id))
+
+
+class MathGameHistoryView(APIView):
+    def get(self, request):
+        attempts = MathGameAttempt.objects.filter(user=request.user)[:20]
+        return Response([game_payload(attempt) for attempt in attempts])