Events and Experiments

Event model

Table: public.content_usage_events

Required fields:

• template_id (uuid)
• account_id (uuid)
• actor_id (uuid)
• actor_role ('teacher' | 'student')
• event_type ('viewed' | 'assigned' | 'submission_completed' | 'graded')
• occurred_at (timestamp)

Optional fields (new):

• variant_id (text) – explanation variant shown
• item_id (text) – item identifier within content_data.items
• experiment_id (uuid) – experiment session/group
• metadata (jsonb) – attempts, time_ms, hint_count, device info, etc.

Client logging

• When opening preview: log event_type="viewed" (template-level). Optionally include variant_id if a non-default explanation is shown.
• For item interactions (digital): log per-item events with item_id, variant_id (if explanation displayed), metadata including attempts and time.

A/B policy (initial)

• Start with uniform randomization among available explanation variants.
• Minimum sample size per variant: 50 events before deciding.
• Uplift metric: combination of higher correctness, fewer hints, lower time.
• Nightly job promotes top variant by updating content_data.explanations.default.
• Guardrails: teacher can force “best only”; cap exposure for poor performers.

Feedback endpoints (planned)

• POST /api/feedback { templateId, itemId?, variantId?, rating: 1|-1, comment? }
• Stored in public.resource_feedback with RLS: class members can write, all class members can read aggregated.

Privacy and RLS

• Insert: only authenticated users with role on the class account (public.has_role_on_account(account_id)).
• Select: class members only.