Merge pull request #8 from tpaulshippy/flashcards

Author: tpaulshippy

OPENAPI_CONTRACT_TESTING.md

@@ -0,0 +1,85 @@
+# OpenAPI Contract Testing
+
+This document describes the OpenAPI-based contract testing setup to catch frontend/backend API mismatches early.
+
+## Overview
+
+The system uses OpenAPI schema generated from Django REST Framework to:
+1. **Backend**: Validate API responses match expected contract
+2. **Frontend**: Provide realistic mock responses for testing
+
+## Files Created
+
+### Backend
+- `back/requirements.txt` - Added `drf-spectacular`
+- `back/server/settings.py` - Configured OpenAPI schema generation
+- `back/server/urls.py` - Added `/api/schema` endpoint
+- `back/bots/tests/test_flashcard_api.py` - API contract tests (12 tests)
+
+### Frontend
+- `front/api/schema.yaml` - OpenAPI schema file
+- `front/__mocks__/handlers.ts` - MSW handlers for API mocking
+- `front/__tests__/api/flashcards.test.ts` - Frontend API tests (11 tests)
+
+### Scripts
+- `scripts/generate_openapi_schema.sh` - Regenerate schema after API changes
+- `.git/hooks/pre-commit` - Pre-commit hook to run tests
+
+## Running Tests
+
+### Backend Tests
+```bash
+cd back
+venv/bin/python -m pytest bots/tests/test_flashcard_api.py -v
+```
+
+### Frontend Tests
+```bash
+cd front
+npm test -- --testPathPattern="__tests__/api/" --ci
+```
+
+## Schema Regeneration
+
+After making changes to serializers, viewsets, or models that affect the API:
+
+```bash
+./scripts/generate_openapi_schema.sh
+```
+
+Then:
+1. Review `front/api/schema.yaml` for changes
+2. Update `front/__mocks__/handlers.ts` if needed
+3. Run tests to verify nothing broke
+
+## Pre-commit Hook
+
+To enable the pre-commit hook that runs API tests:
+
+```bash
+cp .git/hooks/pre-commit .git/hooks/pre-commit.sample
+chmod +x .git/hooks/pre-commit
+```
+
+## What These Tests Catch
+
+The test suite specifically checks for the issues that occurred in commit 94d2cf5:
+
+1. **Pagination Format**: Backend returns `{ results: [], count }` - frontend must handle this
+2. **Field Names**: `card_count` vs other field names
+3. **Required Fields**: `profile`, `chat` on deck creation
+4. **UUID Lookup**: Support for lookup by `deck_id` and `flashcard_id` (UUID)
+
+## API Schema Endpoint
+
+The OpenAPI schema is available at:
+- `/api/schema` - JSON schema
+- `/api/docs` - Swagger UI
+
+## Adding New API Endpoints
+
+When adding new endpoints:
+1. Add serializer and viewset as usual
+2. Run `scripts/generate_openapi_schema.sh`
+3. Add mock handlers in `front/__mocks__/handlers.ts`
+4. Add tests in appropriate test file

back/bots/admin.py

@@ -1,5 +1,5 @@
 from django.contrib import admin
-from .models import Chat, Message, Profile, Bot, UserAccount, UsageLimitHit, AiModel, Device, RevenueCatWebhookEvent
+from .models import Chat, Message, Profile, Bot, UserAccount, UsageLimitHit, AiModel, Device, RevenueCatWebhookEvent, Deck, Flashcard
 from django.contrib.auth.models import User
 from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
 
@@ -61,6 +61,20 @@ def get_readonly_fields(self, request, obj=None):
     def get_list_display(self, request):
         return ['created_at', 'raw_event'] + list(super().get_list_display(request))
 
+class DeckAdmin(admin.ModelAdmin):
+    def get_readonly_fields(self, request, obj=None):
+        return ['deck_id', 'created_at', 'updated_at']
+    
+    def get_list_display(self, request):
+        return ['deck_id', 'name', 'profile', 'chat', 'card_count', 'created_at', 'updated_at'] + list(super().get_list_display(request))
+
+class FlashcardAdmin(admin.ModelAdmin):
+    def get_readonly_fields(self, request, obj=None):
+        return ['flashcard_id', 'created_at', 'updated_at']
+    
+    def get_list_display(self, request):
+        return ['flashcard_id', 'deck', 'front', 'order', 'created_at', 'updated_at'] + list(super().get_list_display(request))
+
 class UserAccountAdmin(admin.ModelAdmin):
     def get_list_display(self, request):
         return ['user_id', 'pin', 'subscription_level', 'timezone'] + list(super().get_list_display(request))
@@ -78,5 +92,7 @@ class UserAdmin(BaseUserAdmin):
 admin.site.register(AiModel, AiModelAdmin)
 admin.site.register(UsageLimitHit, UsageLimitHitAdmin)
 admin.site.register(RevenueCatWebhookEvent, RevenueCatWebhookEventAdmin)
+admin.site.register(Deck, DeckAdmin)
+admin.site.register(Flashcard, FlashcardAdmin)
 admin.site.unregister(User)
 admin.site.register(User, UserAdmin)

back/bots/migrations/0035_deck_flashcard.py

@@ -0,0 +1,45 @@
+# Generated by Django 6.0.3 on 2026-04-16 05:30
+
+import django.db.models.deletion
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('bots', '0034_profile_oauth_email'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Deck',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('deck_id', models.UUIDField(default=uuid.uuid4, unique=True)),
+                ('name', models.CharField(max_length=255)),
+                ('description', models.TextField(blank=True, default='')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('chat', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='decks', to='bots.chat')),
+                ('profile', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='decks', to='bots.profile')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Flashcard',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('flashcard_id', models.UUIDField(default=uuid.uuid4, unique=True)),
+                ('front', models.TextField()),
+                ('back', models.TextField()),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('deck', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='flashcards', to='bots.deck')),
+            ],
+            options={
+                'indexes': [models.Index(fields=['deck', 'order'], name='bots_flashc_deck_id_a95ed4_idx')],
+                'constraints': [models.UniqueConstraint(fields=('deck', 'order'), name='unique_flashcard_order_per_deck')],
+            },
+        ),
+    ]

back/bots/models/__init__.py

@@ -6,6 +6,8 @@
 from .usage_limit_hit import UsageLimitHit
 from .ai_model import AiModel
 from .device import Device
+from .deck import Deck
+from .flashcard import Flashcard
 
 __all__ = [
     'Chat',
@@ -16,5 +18,7 @@
     'UsageLimitHit',
     'AiModel',
     'Device',
-    'RevenueCatWebhookEvent'
+    'RevenueCatWebhookEvent',
+    'Deck',
+    'Flashcard',
 ]