Multi-plan subscriptions, quotas, and token usage APIs (#16 #17 #36) (#37)

## Summary
Implements [#16](#16), [#17](#17), and [#36](#36) in one backend PR.

- **#36 Multi-plan catalog**: Founders ($10, public), Standard ($15), Pro ($40), Business ($99), Backer ($0). Future tiers seeded but hidden/`is_selectable=false`. Backer email whitelist auto-assigns Founders-level access with no checkout.
- **#36 Feature + prompt gating**: plan feature flags (text vs image); rolling **6h** prompt windows (100 / 200 / 300 / 300 / 300). Enforced in both chat consumers when `ENFORCE_SUBSCRIPTION_GATES=true`.
- **#17 Token-period quotas**: optional `monthly_token_quota` on plans + per-user override; calendar-month aggregation from `PromptMetric`; warn/block when reported token totals exceed cap. Null provider usage never fabricated as 0; tracked via `turns_missing_token_usage`.
- **#16 Token API exposure**: `tokens_in` / `tokens_out` on conversation + prompt serializers (null when unknown). `GET /api/finance/subscription/` returns plan + usage snapshot for the FE.
- Checkout defaults to **Founders**; Stripe paid webhooks assign Founders. Registration/OAuth redeem Backer whitelist and return `needs_checkout`.

Companion FE PR: `chat_web_app` branch `feature/plans-quotas-token-usage`.

## Test plan
- [ ] `manage.py migrate` seeds five plans; admin can add Backer emails
- [ ] Public `GET /api/finance/plans/` returns only Founders
- [ ] Register with Backer email → active Backer, `needs_checkout=false`, checkout rejected
- [ ] Founders checkout + paid webhook → active Founders subscription
- [ ] Chat turn blocked without subscription / when prompt window exceeded / when token period exceeded
- [ ] Standard plan denies image feature; Pro/Founders/Backer allow
- [ ] Conversation/prompt API returns `null` tokens when unreported, sums when present
- [ ] `finance.tests.test_plans_quotas` + existing finance/checkout tests passReviewed-on: #37

llm_be/chat_backend/serializers.py

@@ -1,11 +1,14 @@
 from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
 from rest_framework import serializers
+from django.db.models import Count, Q, Sum
+
 from .models import (
     CustomUser,
     Announcement,
     Company,
     Conversation,
     Prompt,
+    PromptMetric,
     Feedback,
     FEEDBACK_CATEGORIES,
     DocumentWorkspace,
@@ -48,12 +51,33 @@ class CustomUserSerializer(serializers.ModelSerializer):
     password = serializers.CharField(min_length=8, write_only=True)
     company = CompanySerializer()
     has_usable_password = serializers.BooleanField()
+    subscription = serializers.SerializerMethodField()
 
     class Meta:
         model = CustomUser
         fields = "__all__"
         extra_kwargs = {"password": {"write_only": True}}
 
+    def get_subscription(self, obj):
+        from finance.services.plans import needs_checkout, plan_to_dict
+        from finance.models import UserSubscription
+
+        try:
+            sub = obj.subscription
+        except UserSubscription.DoesNotExist:
+            return {
+                "plan": None,
+                "status": UserSubscription.Status.NONE,
+                "source": UserSubscription.Source.NONE,
+                "needs_checkout": True,
+            }
+        return {
+            "plan": plan_to_dict(sub.plan) if sub.plan_id else None,
+            "status": sub.status,
+            "source": sub.source,
+            "needs_checkout": needs_checkout(obj),
+        }
+
 
 class SelfServeRegistrationSerializer(serializers.Serializer):
     """Minimal payload for public self-serve sign-up (gated by settings)."""
@@ -79,6 +103,8 @@ class SelfServeRegistrationSerializer(serializers.Serializer):
         return email
 
     def create(self, validated_data):
+        from finance.services.plans import try_redeem_backer_email
+
         email = validated_data["email"]
         password = validated_data["password"]
         first_name = (validated_data.get("first_name") or "").strip()
@@ -102,16 +128,73 @@ class SelfServeRegistrationSerializer(serializers.Serializer):
             company=company,
             is_company_manager=True,
         )
+        try_redeem_backer_email(user)
         return user
 
 
+def _conversation_token_totals(conversation_id: int):
+    """
+    Sum PromptMetric tokens for a conversation.
+
+    Returns nulls when the provider never reported usage (never fabricate 0).
+    """
+    agg = PromptMetric.objects.filter(conversation_id=conversation_id).aggregate(
+        tin=Sum("tokens_in"),
+        tout=Sum("tokens_out"),
+        with_in=Count("id", filter=Q(tokens_in__isnull=False)),
+        with_out=Count("id", filter=Q(tokens_out__isnull=False)),
+    )
+    return (
+        agg["tin"] if agg["with_in"] else None,
+        agg["tout"] if agg["with_out"] else None,
+    )
+
+
+def _prompt_token_pair(prompt_id: int):
+    metric = (
+        PromptMetric.objects.filter(prompt_id=prompt_id)
+        .order_by("-created")
+        .only("tokens_in", "tokens_out")
+        .first()
+    )
+    if metric is None:
+        return None, None
+    return metric.tokens_in, metric.tokens_out
+
+
 class ConversationSerializer(serializers.ModelSerializer):
+    tokens_in = serializers.SerializerMethodField()
+    tokens_out = serializers.SerializerMethodField()
+
     class Meta:
         model = Conversation
-        fields = ("title", "created", "last_modified", "id")
+        fields = (
+            "title",
+            "created",
+            "last_modified",
+            "id",
+            "tokens_in",
+            "tokens_out",
+        )
+
+    def _token_pair(self, obj):
+        cache = self.context.setdefault("_conversation_token_cache", {})
+        if obj.id not in cache:
+            cache[obj.id] = _conversation_token_totals(obj.id)
+        return cache[obj.id]
+
+    def get_tokens_in(self, obj):
+        tin, _ = self._token_pair(obj)
+        return tin
+
+    def get_tokens_out(self, obj):
+        _, tout = self._token_pair(obj)
+        return tout
 
 
 class PromptSerializer(serializers.ModelSerializer):
+    tokens_in = serializers.SerializerMethodField()
+    tokens_out = serializers.SerializerMethodField()
 
     class Meta:
         model = Prompt
@@ -120,8 +203,24 @@ class PromptSerializer(serializers.ModelSerializer):
             "user_created",
             "created",
             "id",
+            "tokens_in",
+            "tokens_out",
         )
 
+    def _token_pair(self, obj):
+        cache = self.context.setdefault("_prompt_token_cache", {})
+        if obj.id not in cache:
+            cache[obj.id] = _prompt_token_pair(obj.id)
+        return cache[obj.id]
+
+    def get_tokens_in(self, obj):
+        tin, _ = self._token_pair(obj)
+        return tin
+
+    def get_tokens_out(self, obj):
+        _, tout = self._token_pair(obj)
+        return tout
+
     def validate_message(self, value: str) -> str:
         if value is None or not str(value).strip():
             raise serializers.ValidationError("Message text cannot be empty.")