Skip to content

Commit 5de9ad2

Browse files
guillermoscriptclaude
guillermoscript
and
claude
authored
feat(teacher): course analytics page + confusion-hotspots widget (#579)
* feat(teacher): course analytics page + confusion-hotspots widget Teachers had no way to see how an exercise performs across students. The data existed — `lms_get_confusion_hotspots` already fused practice, exercise and exam-question outcomes with Elo `item_ratings` — but it was reachable only from an MCP client, had no widget, and nothing in the web app read it. Adds both surfaces, and closes the gap that actually answers "is this too hard?": `exercises.difficulty_level` (the teacher's own easy/medium/hard label) was never compared against the rating the platform measured from real attempts. Both surfaces now show the label beside the measured rating and flag the divergence. Web - /dashboard/teacher/courses/[id]/analytics — server-rendered, 7/30/90-day window via plain links (no client JS), linked from the course header. - lib/analytics/confusion-hotspots.ts fuses four signals: practice drills, exercise evaluations, lesson checkpoints and exam-question miss rates. `lesson_checkpoint_attempts` was never read by any teacher surface despite shipping a purpose-built `..._teacher_metrics_idx`. - Sweeps use `fetchAllRows`, so a course busy enough to hit PostgREST's 1000-row cap cannot silently under-report. A signal that fails to load becomes a named warning in the UI rather than an empty list that looks like "nobody is struggling". - Ownership-gated to the course author; every read runs under the teacher's own RLS policies, no admin client. MCP - resources/confusion-hotspots/widget.tsx, wired to the existing tool. - hardest_items now carries difficulty_level + mismatch. - Hotspot scope "lesson" renamed to "practice": those rows are drill topics, which may not map to a lesson at all. - Demo fixtures (default / all-clear / empty) for no-DB previews. Typing the Supabase client (rather than `SupabaseClient<any>`) caught two real defects in the hand-written row shapes: `checkpoint_id` is a number, and `submission_date` is nullable and so cannot be compared bare when picking a student's latest retake. Verified: Next build + typecheck + lint clean; mcp-server build (19 widgets) and type check pass; widget rendered headlessly in all three fixture states; page rendered live against seeded local data as creator@codeacademy.com and the seed rows removed afterwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VqQTE7LDYPx7d15BcWLGfC * test(analytics): cover the confusion-hotspots paths QA could not reach The manual pass could only exercise practice and exercise hotspots with a single student, because every source table was empty locally. Exam questions, lesson checkpoints, the fetchAllRows paging loop and the warning path all shipped unverified. 23 tests close that. Each test was mutation-checked — the suite was re-run against a deliberately broken copy of the logic to prove the assertions can fail: - first-attempt-wins instead of latest-attempt → caught - miss threshold moved from 70% to 50% → caught - `easy` given a floor (so it could read easier) → caught - oldest retake wins instead of newest → caught That last mutation initially SURVIVED, which exposed a genuinely misleading test: a NULL `submission_date` never passes the `.gte(cutoff)` window filter (NULL comparisons are never true), so such a row cannot reach the retake logic at all. The test claiming to prove null-handling was passing for the wrong reason. Split into an honest pair: one that exercises retake selection with two dated submissions, and one that pins the real upstream behaviour. fake-supabase gains `range()` (needed by fetchAllRows) and a real `order()`. `count` now reports the FULL match count rather than the post-limit count, matching PostgREST — a per-page count would make a truncated sweep look complete, defeating the assertion fetchAllRows exists to make. All 611 pre-existing tests still pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VqQTE7LDYPx7d15BcWLGfC * fix(analytics): translate the hotspot detail lines on /es The analytics page shipped its per-hotspot "why" line as a prebuilt English sentence built inside lib/analytics/confusion-hotspots.ts, so on /es every heading, badge and footer translated while the line carrying the actual finding stayed in English: 4 of 5 student(s) still failing on their latest attempt · average 52% 3 of 5 student(s) missed it on their latest submission · 60% miss rate Caught by rendering the page under /es for the QA screenshots, not by a test — the strings were correct, just not translatable. Hotspot now carries numbers only (`totalAttempts` replaces `evidence`) and the page formats them through next-intl. Each signal counts something different, so each scope gets its own message rather than one generic sentence that would read wrong for three scopes out of four. The MCP tool keeps its English `evidence` string on purpose: its reader is a model, not a localised UI. Noted in the twin-implementation header. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VqQTE7LDYPx7d15BcWLGfC * docs(screenshots): #579 teacher analytics + hotspots widget QA evidence Page rendered against seeded data in the local Code Academy tenant with all four signals populated (practice, exercise, checkpoint, exam question) and both label-vs-Elo mismatch directions present. 7d/30d/90d differ because the seed spreads attempts across three time bands, so the window switcher is shown doing real work rather than re-rendering the same list. Widget shots cover the three demo fixtures: default, all-clear, empty. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VqQTE7LDYPx7d15BcWLGfC --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 35ef2b8 commit 5de9ad2

18 files changed

Lines changed: 2244 additions & 34 deletions

File tree

‎app/[locale]/dashboard/teacher/courses/[courseId]/analytics/page.tsx‎

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
import { createClient } from '@/lib/supabase/server'
2+
import { redirect } from 'next/navigation'
3+
import Link from 'next/link'
4+
import { getTranslations } from 'next-intl/server'
5+
import { Button } from '@/components/ui/button'
6+
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
7+
import { Badge } from '@/components/ui/badge'
8+
import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'
9+
import {
10+
IconArrowLeft,
11+
IconAlertTriangle,
12+
IconChartBar,
13+
IconFlame,
14+
IconScale,
15+
IconInfoCircle,
16+
} from '@tabler/icons-react'
17+
import { getCurrentTenantId, getCurrentUserId } from '@/lib/supabase/tenant'
18+
import { getConfusionHotspots, type Hotspot } from '@/lib/analytics/confusion-hotspots'
19+
import { HotspotScopeBadge, SeverityBar, DifficultyDelta } from '@/components/teacher/analytics-cells'
20+
21+
interface PageProps {
22+
params: Promise<{ courseId: string; locale: string }>
23+
searchParams: Promise<{ days?: string }>
24+
}
25+
26+
/** Look-back windows offered in the header. Anything else falls back to 30. */
27+
const WINDOWS = [7, 30, 90] as const
28+
const DEFAULT_WINDOW = 30
29+
30+
function parseWindow(raw: string | undefined): number {
31+
const n = Number(raw)
32+
return WINDOWS.includes(n as (typeof WINDOWS)[number]) ? n : DEFAULT_WINDOW
33+
}
34+
35+
/**
36+
* Deep-link a hotspot back to the thing a teacher would edit. Practice topics
37+
* and exam questions have no standalone editor, so they link to the lesson or
38+
* stay inert rather than pointing somewhere that 404s.
39+
*/
40+
function hotspotHref(courseId: string, h: Hotspot): string | null {
41+
if (h.scope === 'exercise' && typeof h.ref === 'number') {
42+
return `/dashboard/teacher/courses/${courseId}/exercises/${h.ref}`
43+
}
44+
if (h.lessonId != null) {
45+
return `/dashboard/teacher/courses/${courseId}/lessons/${h.lessonId}`
46+
}
47+
return null
48+
}
49+
50+
/**
51+
* The one-line "why this is a hotspot" under each item.
52+
*
53+
* Built here rather than in the analytics module so it can be translated: each
54+
* signal counts something different, so each gets its own message instead of a
55+
* generic one that would read wrong for three scopes out of four.
56+
*/
57+
function hotspotEvidence(h: Hotspot, t: Awaited<ReturnType<typeof getTranslations>>): string {
58+
if (h.scope === 'practice') {
59+
return t('hotspots.evidencePractice', {
60+
attempts: h.totalAttempts ?? 0,
61+
students: h.studentsAttempted,
62+
avg: h.avgScore ?? 0,
63+
below: h.studentsAffected,
64+
})
65+
}
66+
if (h.scope === 'exam_question') {
67+
return t('hotspots.evidenceExam', {
68+
missers: h.studentsAffected,
69+
students: h.studentsAttempted,
70+
rate: Math.round((h.studentsAffected / Math.max(h.studentsAttempted, 1)) * 100),
71+
})
72+
}
73+
// Exercises and checkpoints share a shape: latest attempt decides "stuck".
74+
const base = t('hotspots.evidenceStuck', {
75+
stuck: h.studentsAffected,
76+
students: h.studentsAttempted,
77+
attempts: (h.avgAttempts ?? 0).toFixed(1),
78+
})
79+
return h.avgScore == null ? base : `${base} · ${t('hotspots.evidenceAvg', { avg: h.avgScore })}`
80+
}
81+
82+
export default async function CourseAnalyticsPage({ params, searchParams }: PageProps) {
83+
const { courseId } = await params
84+
const { days: daysParam } = await searchParams
85+
const days = parseWindow(daysParam)
86+
87+
const supabase = await createClient()
88+
const t = await getTranslations('dashboard.teacher.analytics')
89+
const tenantId = await getCurrentTenantId()
90+
91+
const userId = await getCurrentUserId()
92+
if (!userId) redirect('/auth/login')
93+
94+
const courseIdNum = parseInt(courseId, 10)
95+
const { data: course } = await supabase
96+
.from('courses')
97+
.select('course_id, title, author_id')
98+
.eq('course_id', courseIdNum)
99+
.eq('tenant_id', tenantId)
100+
.single()
101+
102+
// Same ownership rule the rest of the teacher course area uses: analytics
103+
// expose every student's results, so a non-author teacher must not see them.
104+
if (!course || course.author_id !== userId) {
105+
return (
106+
<div className="p-8">
107+
<Card className="border-destructive">
108+
<CardHeader>
109+
<CardTitle>{t('accessDenied')}</CardTitle>
110+
<CardDescription>{t('accessDeniedDesc')}</CardDescription>
111+
</CardHeader>
112+
<CardContent>
113+
<Link href="/dashboard/teacher/courses">
114+
<Button variant="outline">{t('backToCourses')}</Button>
115+
</Link>
116+
</CardContent>
117+
</Card>
118+
</div>
119+
)
120+
}
121+
122+
const result = await getConfusionHotspots(supabase, {
123+
courseId: courseIdNum,
124+
tenantId,
125+
days,
126+
})
127+
128+
const { hotspots, hardestItems, sources, warnings } = result
129+
const mislabeled = hardestItems.filter((i) => i.mismatch !== null)
130+
const totalSignals =
131+
sources.practiceAttempts +
132+
sources.exerciseEvaluations +
133+
sources.checkpointAttempts +
134+
sources.examSubmissions
135+
136+
return (
137+
<div className="min-h-screen bg-background pb-20">
138+
<header className="sticky top-0 z-10 border-b bg-card">
139+
<div className="container mx-auto px-4 py-5 sm:px-6 lg:px-8">
140+
<div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
141+
<div className="space-y-1">
142+
<div className="flex min-w-0 items-center gap-2">
143+
<Link href={`/dashboard/teacher/courses/${courseId}`} className="shrink-0">
144+
<Button variant="ghost" size="icon" className="h-8 w-8" aria-label={t('backToCourse')}>
145+
<IconArrowLeft className="h-4 w-4" />
146+
</Button>
147+
</Link>
148+
<h1 className="truncate text-2xl font-bold tracking-tight">{t('title')}</h1>
149+
</div>
150+
<p className="ml-10 text-sm text-muted-foreground">
151+
{t('subtitle', { course: course.title })}
152+
</p>
153+
</div>
154+
155+
{/* Look-back window. Plain links keep the page fully server-rendered. */}
156+
<nav aria-label={t('windowLabel')} className="flex items-center gap-1">
157+
{WINDOWS.map((w) => (
158+
<Link
159+
key={w}
160+
href={`/dashboard/teacher/courses/${courseId}/analytics?days=${w}`}
161+
scroll={false}
162+
>
163+
<Button variant={w === days ? 'default' : 'outline'} size="sm">
164+
{t('windowDays', { days: w })}
165+
</Button>
166+
</Link>
167+
))}
168+
</nav>
169+
</div>
170+
</div>
171+
</header>
172+
173+
<div className="container mx-auto space-y-6 px-4 py-6 sm:px-6 lg:px-8">
174+
{warnings.length > 0 && (
175+
<Alert variant="destructive">
176+
<IconAlertTriangle />
177+
<AlertTitle>{t('warningsTitle')}</AlertTitle>
178+
<AlertDescription>
179+
<p>{t('warningsDesc')}</p>
180+
<ul className="mt-1 list-disc pl-4">
181+
{warnings.map((w) => (
182+
<li key={w}>{w}</li>
183+
))}
184+
</ul>
185+
</AlertDescription>
186+
</Alert>
187+
)}
188+
189+
{/* ── Difficulty calibration ─────────────────────────────────────── */}
190+
<Card>
191+
<CardHeader>
192+
<CardTitle className="flex items-center gap-2">
193+
<IconScale className="h-4 w-4 text-muted-foreground" />
194+
{t('calibration.title')}
195+
</CardTitle>
196+
<CardDescription>{t('calibration.desc')}</CardDescription>
197+
</CardHeader>
198+
<CardContent>
199+
{hardestItems.length === 0 ? (
200+
<p className="py-6 text-center text-sm text-muted-foreground">
201+
{t('calibration.empty')}
202+
</p>
203+
) : (
204+
<>
205+
{mislabeled.length > 0 && (
206+
<p className="mb-4 text-sm">
207+
<Badge variant="destructive" className="mr-2">
208+
{mislabeled.length}
209+
</Badge>
210+
{t('calibration.mismatchSummary', { count: mislabeled.length })}
211+
</p>
212+
)}
213+
<ul className="divide-y">
214+
{hardestItems.map((item) => (
215+
<li
216+
key={`${item.itemType}-${item.itemId}`}
217+
className="flex flex-wrap items-center gap-x-4 gap-y-2 py-3"
218+
>
219+
<div className="min-w-48 flex-1">
220+
<div className="flex items-center gap-2">
221+
{item.itemType === 'exercise' ? (
222+
<Link
223+
href={`/dashboard/teacher/courses/${courseId}/exercises/${item.itemId}`}
224+
className="truncate text-sm font-medium hover:underline"
225+
>
226+
{item.title}
227+
</Link>
228+
) : (
229+
<span className="truncate text-sm font-medium">{item.title}</span>
230+
)}
231+
</div>
232+
<p className="mt-0.5 text-xs text-muted-foreground">
233+
{t(`scope.${item.itemType}`)} ·{' '}
234+
{t('calibration.attempts', { count: item.attemptCount })}
235+
</p>
236+
</div>
237+
<DifficultyDelta
238+
declared={item.declaredDifficulty}
239+
rating={item.rating}
240+
mismatch={item.mismatch}
241+
labels={{
242+
declared: item.declaredDifficulty
243+
? t(`difficulty.${item.declaredDifficulty}`)
244+
: t('difficulty.unlabeled'),
245+
measured: t('calibration.measured'),
246+
harder: t('calibration.harderThanLabeled'),
247+
easier: t('calibration.easierThanLabeled'),
248+
}}
249+
/>
250+
</li>
251+
))}
252+
</ul>
253+
<p className="mt-4 flex items-start gap-1.5 text-xs text-muted-foreground">
254+
<IconInfoCircle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
255+
{t('calibration.ratingHint')}
256+
</p>
257+
</>
258+
)}
259+
</CardContent>
260+
</Card>
261+
262+
{/* ── Confusion hotspots ─────────────────────────────────────────── */}
263+
<Card>
264+
<CardHeader>
265+
<CardTitle className="flex items-center gap-2">
266+
<IconFlame className="h-4 w-4 text-muted-foreground" />
267+
{t('hotspots.title')}
268+
</CardTitle>
269+
<CardDescription>{t('hotspots.desc', { days })}</CardDescription>
270+
</CardHeader>
271+
<CardContent>
272+
{hotspots.length === 0 ? (
273+
<div className="py-8 text-center">
274+
<IconChartBar className="mx-auto mb-2 h-8 w-8 text-muted-foreground/50" />
275+
<p className="text-sm text-muted-foreground">
276+
{totalSignals === 0 ? t('hotspots.noData') : t('hotspots.allClear')}
277+
</p>
278+
</div>
279+
) : (
280+
<ul className="space-y-3">
281+
{hotspots.map((h) => {
282+
const href = hotspotHref(courseId, h)
283+
return (
284+
<li
285+
key={`${h.scope}-${String(h.ref)}`}
286+
className="rounded-lg border p-3"
287+
>
288+
<div className="flex flex-wrap items-start justify-between gap-2">
289+
<div className="min-w-48 flex-1">
290+
<div className="flex flex-wrap items-center gap-2">
291+
<HotspotScopeBadge scope={h.scope} label={t(`scope.${h.scope}`)} />
292+
{href ? (
293+
<Link href={href} className="text-sm font-medium hover:underline">
294+
{h.label}
295+
</Link>
296+
) : (
297+
<span className="text-sm font-medium">{h.label}</span>
298+
)}
299+
</div>
300+
<p className="mt-1 text-xs text-muted-foreground">
301+
{hotspotEvidence(h, t)}
302+
</p>
303+
</div>
304+
<SeverityBar value={h.severity} label={t('hotspots.severity')} />
305+
</div>
306+
</li>
307+
)
308+
})}
309+
</ul>
310+
)}
311+
312+
<p className="mt-4 border-t pt-3 text-xs text-muted-foreground">
313+
{t('hotspots.sources', {
314+
practice: sources.practiceAttempts,
315+
exercises: sources.exerciseEvaluations,
316+
checkpoints: sources.checkpointAttempts,
317+
exams: sources.examSubmissions,
318+
days,
319+
})}
320+
</p>
321+
</CardContent>
322+
</Card>
323+
</div>
324+
</div>
325+
)
326+
}

‎app/[locale]/dashboard/teacher/courses/[courseId]/page.tsx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ import {
3131
IconClock,
3232
IconVideo,
3333
IconChevronRight,
34+
IconChartBar,
3435
} from '@tabler/icons-react'
3536
import { CourseStudentsTable } from '@/components/teacher/course-students-table'
3637
import {getCurrentTenantId, getCurrentUserId } from '@/lib/supabase/tenant'
@@ -222,6 +223,12 @@ export default async function CourseManagementPage({ params }: PageProps) {
222223
{t('tabs.preview')}
223224
</Button>
224225
</Link>
226+
<Link href={`/dashboard/teacher/courses/${courseId}/analytics`}>
227+
<Button variant="outline" size="sm" className="gap-2">
228+
<IconChartBar className="h-3.5 w-3.5" />
229+
{t('analytics')}
230+
</Button>
231+
</Link>
225232
<Link href={`/dashboard/teacher/courses/${courseId}/settings`} data-tour="course-settings">
226233
<Button variant="outline" size="sm" className="gap-2">
227234
<IconSettings className="h-3.5 w-3.5" />

0 commit comments

Comments
 (0)