refactor(stage-4): partition monolithic main.py into modular APIRouters

app/routers/grammar.py

@@ -0,0 +1,97 @@
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from app.auth import require_user
+from app.database import get_db
+from app.grammar import (
+    get_grammar_units_list,
+    get_grammar_unit_detail,
+    process_grammar_answer,
+    record_grammar_completion,
+    update_handwritten_status,
+)
+
+router = APIRouter(tags=["Murphy Grammar"])
+
+
+class GrammarAnswerRequest(BaseModel):
+    unit_id: int
+    exercise_idx: int
+    selected_option: str
+
+
+class GrammarCompleteRequest(BaseModel):
+    unit_id: int
+    score: int = Field(..., ge=0, le=100)
+    handwritten_logged: bool = False
+
+
+class GrammarHandwrittenRequest(BaseModel):
+    unit_id: int
+    handwritten: bool
+
+
+@router.get("/api/grammar/units")
+async def api_grammar_units(user: dict = Depends(require_user)):
+    """
+    Returns the list of all curated Murphy grammar units with user progress.
+    """
+    with get_db() as conn:
+        units = get_grammar_units_list(conn, user["id"])
+        return {"units": units}
+
+
+@router.get("/api/grammar/units/{unit_id}")
+async def api_grammar_unit_detail(unit_id: int, user: dict = Depends(require_user)):
+    """
+    Returns full content of a unit for lesson mode.
+    """
+    with get_db() as conn:
+        unit = get_grammar_unit_detail(conn, user["id"], unit_id)
+        if not unit:
+            raise HTTPException(status_code=404, detail="Unit not found")
+        return unit
+
+
+@router.post("/api/grammar/answer")
+async def api_grammar_answer(
+    req: GrammarAnswerRequest,
+    user: dict = Depends(require_user),
+):
+    """
+    Checks answer for a Cloze Tap grammar exercise.
+    If wrong, performs automated gap ingestion into active SRS vocabulary.
+    """
+    with get_db() as conn:
+        result = process_grammar_answer(
+            conn, user["id"], req.unit_id, req.exercise_idx, req.selected_option
+        )
+        if "error" in result:
+            raise HTTPException(status_code=404, detail=result["error"])
+        return result
+
+
+@router.post("/api/grammar/complete")
+async def api_grammar_complete(
+    req: GrammarCompleteRequest,
+    user: dict = Depends(require_user),
+):
+    """
+    Records completion of a grammar unit and user's score.
+    """
+    with get_db() as conn:
+        return record_grammar_completion(
+            conn, user["id"], req.unit_id, req.score, req.handwritten_logged
+        )
+
+
+@router.post("/api/grammar/handwritten")
+async def api_grammar_handwritten(
+    req: GrammarHandwrittenRequest,
+    user: dict = Depends(require_user),
+):
+    """
+    Toggles handwritten paper notebook checkbox for a unit.
+    """
+    with get_db() as conn:
+        return update_handwritten_status(conn, user["id"], req.unit_id, req.handwritten)