feat: analytics dashboards & two-tier feedback system (#78)

* docs: add analytics & user feedback design document Covers team analytics, personal analytics, flow analytics, step-level thumbs up/down feedback, and flow CSAT ratings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add analytics & feedback implementation plan 12-task TDD plan covering session ratings, step feedback, team/personal/flow analytics endpoints, and frontend pages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add session_ratings table and analytics indexes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add SessionRating model and analytics schemas Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add session CSAT rating endpoint with tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add step thumbs feedback and /ratings alias routes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add team, personal, and flow analytics endpoints Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add recharts, analytics types, and API client Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add inline step thumbs up/down feedback during sessions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add CSAT rating modal after session completion Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add Team Analytics page with charts and leaderboards Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add Flow Analytics panel with step dropoff and CSAT data Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add My Analytics page with personal stats and charts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-16 15:23:14 -05:00
parent 293ceaa9e9
commit bd12ced5ee
29 changed files with 4856 additions and 5 deletions
--- a/backend/tests/test_analytics.py
+++ b/backend/tests/test_analytics.py
@@ -0,0 +1,137 @@
+import pytest
+from httpx import AsyncClient
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.fixture
+async def team_admin(client: AsyncClient, test_db):
+    """Create a team admin user (gets own account via registration)."""
+    from uuid import UUID as PyUUID
+    from sqlalchemy import select
+    from app.models.user import User
+
+    data = {
+        "email": "teamadmin@example.com",
+        "password": "TeamAdmin123!",
+        "name": "Team Admin"
+    }
+    response = await client.post("/api/v1/auth/register", json=data)
+    assert response.status_code in (200, 201), f"Failed: {response.text}"
+
+    user_id = PyUUID(response.json()["id"])
+    result = await test_db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one()
+    user.is_team_admin = True
+    await test_db.commit()
+
+    return {"email": data["email"], "password": data["password"], "user_data": response.json()}
+
+
+@pytest.fixture
+async def team_admin_headers(client: AsyncClient, team_admin: dict):
+    """Auth headers for team admin."""
+    response = await client.post(
+        "/api/v1/auth/login/json",
+        json={"email": team_admin["email"], "password": team_admin["password"]},
+    )
+    assert response.status_code == 200
+    return {"Authorization": f"Bearer {response.json()['access_token']}"}
+
+
+async def test_team_analytics_success(client: AsyncClient, admin_auth_headers: dict):
+    """Super admin can access team analytics."""
+    response = await client.get(
+        "/api/v1/analytics/team?period=30d",
+        headers=admin_auth_headers,
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert "summary" in data
+    assert "time_series" in data
+    assert "top_flows" in data
+    assert "top_engineers" in data
+    assert "total_sessions" in data["summary"]
+    assert "completion_rate" in data["summary"]
+    assert "median_duration_minutes" in data["summary"]
+    assert "active_engineers" in data["summary"]
+
+
+async def test_team_analytics_team_admin(client: AsyncClient, team_admin_headers: dict):
+    """Team admin can also access team analytics."""
+    response = await client.get(
+        "/api/v1/analytics/team",
+        headers=team_admin_headers,
+    )
+    assert response.status_code == 200
+
+
+async def test_team_analytics_forbidden_for_engineer(client: AsyncClient, auth_headers: dict):
+    """Regular engineers cannot access team analytics."""
+    response = await client.get(
+        "/api/v1/analytics/team",
+        headers=auth_headers,
+    )
+    assert response.status_code == 403
+
+
+async def test_personal_analytics_success(client: AsyncClient, auth_headers: dict):
+    """Any user can access personal analytics."""
+    response = await client.get(
+        "/api/v1/analytics/me?period=30d",
+        headers=auth_headers,
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert "summary" in data
+    assert "time_series" in data
+    assert "top_flows" in data
+    assert "median_duration_minutes" in data["summary"]
+
+
+async def test_personal_analytics_empty(client: AsyncClient, auth_headers: dict):
+    """Personal analytics with no sessions returns zeroes."""
+    response = await client.get(
+        "/api/v1/analytics/me?period=7d",
+        headers=auth_headers,
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["summary"]["total_sessions"] == 0
+    assert data["summary"]["completion_rate"] == 0.0
+    assert data["summary"]["median_duration_minutes"] == 0.0
+    assert data["summary"]["active_engineers"] == 1  # always 1 for personal
+
+
+async def test_flow_analytics_success(client: AsyncClient, auth_headers: dict, test_tree: dict):
+    """Can access analytics for a visible flow."""
+    response = await client.get(
+        f"/api/v1/analytics/flows/{test_tree['id']}",
+        headers=auth_headers,
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert "summary" in data
+    assert "step_feedback" in data
+    assert "recent_comments" in data
+    assert "avg_csat" in data
+    assert "total_ratings" in data
+
+
+async def test_flow_analytics_404(client: AsyncClient, auth_headers: dict):
+    """Non-existent flow returns 404."""
+    import uuid
+    response = await client.get(
+        f"/api/v1/analytics/flows/{uuid.uuid4()}",
+        headers=auth_headers,
+    )
+    assert response.status_code == 404
+
+
+async def test_invalid_period_rejected(client: AsyncClient, auth_headers: dict):
+    """Invalid period values are rejected."""
+    response = await client.get(
+        "/api/v1/analytics/me?period=1y",
+        headers=auth_headers,
+    )
+    assert response.status_code == 422
--- a/backend/tests/test_ratings.py
+++ b/backend/tests/test_ratings.py
@@ -0,0 +1,215 @@
+import pytest
+from httpx import AsyncClient
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.fixture
+async def test_session(client: AsyncClient, auth_headers: dict, test_tree: dict):
+    """Create a test session from the test tree."""
+    response = await client.post(
+        "/api/v1/sessions",
+        json={"tree_id": test_tree["id"]},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201, f"Failed to create session: {response.text}"
+    return response.json()
+
+
+@pytest.fixture
+async def completed_session(client: AsyncClient, auth_headers: dict, test_session: dict):
+    """Complete a session so it can be rated."""
+    response = await client.post(
+        f"/api/v1/sessions/{test_session['id']}/complete",
+        json={"outcome": "resolved", "outcome_notes": "Test resolved"},
+        headers=auth_headers,
+    )
+    assert response.status_code == 200, f"Failed to complete session: {response.text}"
+    return response.json()
+
+
+async def test_rate_session_success(client: AsyncClient, auth_headers: dict, completed_session: dict):
+    """Rate a completed session with CSAT score."""
+    response = await client.post(
+        f"/api/v1/sessions/{completed_session['id']}/rate",
+        json={"rating": 4, "comment": "Very helpful flow"},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["rating"] == 4
+    assert data["comment"] == "Very helpful flow"
+
+
+async def test_rate_session_no_comment(client: AsyncClient, auth_headers: dict, completed_session: dict):
+    """Rate without a comment."""
+    response = await client.post(
+        f"/api/v1/sessions/{completed_session['id']}/rate",
+        json={"rating": 5},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["rating"] == 5
+    assert data["comment"] is None
+
+
+async def test_rate_session_duplicate(client: AsyncClient, auth_headers: dict, completed_session: dict):
+    """Cannot rate same session twice."""
+    await client.post(
+        f"/api/v1/sessions/{completed_session['id']}/rate",
+        json={"rating": 4},
+        headers=auth_headers,
+    )
+    response = await client.post(
+        f"/api/v1/sessions/{completed_session['id']}/rate",
+        json={"rating": 5},
+        headers=auth_headers,
+    )
+    assert response.status_code == 409
+
+
+async def test_rate_session_invalid_rating(client: AsyncClient, auth_headers: dict, completed_session: dict):
+    """Rating must be 1-5."""
+    response = await client.post(
+        f"/api/v1/sessions/{completed_session['id']}/rate",
+        json={"rating": 6},
+        headers=auth_headers,
+    )
+    assert response.status_code == 422
+
+
+async def test_rate_incomplete_session(client: AsyncClient, auth_headers: dict, test_session: dict):
+    """Cannot rate a session that hasn't been completed."""
+    response = await client.post(
+        f"/api/v1/sessions/{test_session['id']}/rate",
+        json={"rating": 4},
+        headers=auth_headers,
+    )
+    assert response.status_code == 400
+
+
+# --- Step Feedback Tests ---
+
+@pytest.fixture
+async def test_step(client: AsyncClient, auth_headers: dict):
+    """Create a step in the step library."""
+    response = await client.post(
+        "/api/v1/steps",
+        json={
+            "title": "Test Step",
+            "step_type": "action",
+            "content": {
+                "instructions": "Run the diagnostic command",
+                "commands": [{"label": "Echo test", "command": "echo hello"}]
+            },
+        },
+        headers=auth_headers,
+    )
+    assert response.status_code == 201, f"Failed to create step: {response.text}"
+    return response.json()
+
+
+async def test_step_feedback_thumbs_up(client: AsyncClient, auth_headers: dict, test_step: dict, test_session: dict):
+    """Submit thumbs-up feedback for a step."""
+    response = await client.post(
+        f"/api/v1/steps/{test_step['id']}/feedback",
+        json={"session_id": test_session["id"], "was_helpful": True},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["was_helpful"] is True
+    assert data["status"] == "created"
+
+
+async def test_step_feedback_thumbs_down(client: AsyncClient, auth_headers: dict, test_step: dict, test_session: dict):
+    """Submit thumbs-down feedback for a step."""
+    response = await client.post(
+        f"/api/v1/steps/{test_step['id']}/feedback",
+        json={"session_id": test_session["id"], "was_helpful": False},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["was_helpful"] is False
+    assert data["status"] == "created"
+
+
+async def test_step_feedback_toggle(client: AsyncClient, auth_headers: dict, test_step: dict, test_session: dict):
+    """Submitting again for same step+session updates the rating."""
+    await client.post(
+        f"/api/v1/steps/{test_step['id']}/feedback",
+        json={"session_id": test_session["id"], "was_helpful": True},
+        headers=auth_headers,
+    )
+    response = await client.post(
+        f"/api/v1/steps/{test_step['id']}/feedback",
+        json={"session_id": test_session["id"], "was_helpful": False},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["was_helpful"] is False
+    assert data["status"] == "updated"
+
+
+async def test_step_feedback_not_found(client: AsyncClient, auth_headers: dict, test_session: dict):
+    """Feedback on non-existent step returns 404."""
+    import uuid
+    fake_id = str(uuid.uuid4())
+    response = await client.post(
+        f"/api/v1/steps/{fake_id}/feedback",
+        json={"session_id": test_session["id"], "was_helpful": True},
+        headers=auth_headers,
+    )
+    assert response.status_code == 404
+
+
+# --- /ratings Alias Route Tests ---
+
+async def test_ratings_alias_post(client: AsyncClient, auth_headers: dict, test_step: dict):
+    """POST /steps/{id}/ratings works as alias for /rate."""
+    response = await client.post(
+        f"/api/v1/steps/{test_step['id']}/ratings",
+        json={"rating": 4, "was_helpful": True},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["rating"] == 4
+
+
+async def test_ratings_alias_put(client: AsyncClient, auth_headers: dict, test_step: dict):
+    """PUT /steps/{id}/ratings works as alias for /rate."""
+    # First create a rating
+    await client.post(
+        f"/api/v1/steps/{test_step['id']}/rate",
+        json={"rating": 3, "was_helpful": True},
+        headers=auth_headers,
+    )
+    # Update via alias
+    response = await client.put(
+        f"/api/v1/steps/{test_step['id']}/ratings",
+        json={"rating": 5},
+        headers=auth_headers,
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["rating"] == 5
+
+
+async def test_ratings_alias_delete(client: AsyncClient, auth_headers: dict, test_step: dict):
+    """DELETE /steps/{id}/ratings works as alias for /rate."""
+    # First create a rating
+    await client.post(
+        f"/api/v1/steps/{test_step['id']}/rate",
+        json={"rating": 4, "was_helpful": True},
+        headers=auth_headers,
+    )
+    # Delete via alias
+    response = await client.delete(
+        f"/api/v1/steps/{test_step['id']}/ratings",
+        headers=auth_headers,
+    )
+    assert response.status_code == 204