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
2026-07-31 04:24:20 -07:00
parent 67f16565e9
commit 841c0962d9
23 changed files with 1577 additions and 36 deletions
@@ -0,0 +1,86 @@
+# Generated by Django 6.0 on 2026-07-31 11:14
+
+import django.db.models.deletion
+import django.utils.timezone
+from django.conf import settings
+from django.db import migrations, models
+
+
+def seed_plans(apps, schema_editor):
+    from finance.services.plans import seed_subscription_plans
+
+    seed_subscription_plans(update_existing=True)
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('finance', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='SubscriptionPlan',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(default=django.utils.timezone.now)),
+                ('last_modified', models.DateTimeField(default=django.utils.timezone.now)),
+                ('slug', models.SlugField(max_length=64, unique=True)),
+                ('name', models.CharField(max_length=128)),
+                ('description', models.TextField(blank=True, default='')),
+                ('price_cents', models.PositiveIntegerField(default=0, help_text='List price in cents (0 for complimentary tiers).')),
+                ('currency', models.CharField(default='usd', max_length=8)),
+                ('interval', models.CharField(default='month', max_length=16)),
+                ('stripe_price_id', models.CharField(blank=True, default='', help_text='Optional Stripe Price id; empty uses price_data at Checkout.', max_length=255)),
+                ('is_public', models.BooleanField(default=False, help_text='Shown in public pricing / plan list APIs.')),
+                ('is_selectable', models.BooleanField(default=False, help_text='Selectable at Checkout. Backer is never selectable.')),
+                ('allows_text_generation', models.BooleanField(default=True)),
+                ('allows_image_generation', models.BooleanField(default=False)),
+                ('allows_all_future_features', models.BooleanField(default=False, help_text='Founders/Backer: unlock new capabilities as they ship.')),
+                ('prompt_quota_per_window', models.PositiveIntegerField(help_text='Max prompts allowed in each rolling window.')),
+                ('prompt_window_hours', models.PositiveIntegerField(default=6, help_text='Length of the rolling prompt quota window in hours.')),
+                ('monthly_token_quota', models.PositiveIntegerField(blank=True, help_text='Optional billing-period token cap (tokens_in + tokens_out). Null = no token-period limit (prompt window still applies).', null=True)),
+                ('sort_order', models.PositiveIntegerField(default=0)),
+            ],
+            options={
+                'ordering': ['sort_order', 'price_cents', 'name'],
+            },
+        ),
+        migrations.CreateModel(
+            name='BackerEmail',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(default=django.utils.timezone.now)),
+                ('last_modified', models.DateTimeField(default=django.utils.timezone.now)),
+                ('email', models.EmailField(db_index=True, max_length=254, unique=True)),
+                ('note', models.CharField(blank=True, default='', max_length=512)),
+                ('redeemed_at', models.DateTimeField(blank=True, null=True)),
+                ('redeemed_user', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='backer_email_entries', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Backer email',
+                'verbose_name_plural': 'Backer emails',
+                'ordering': ['email'],
+            },
+        ),
+        migrations.CreateModel(
+            name='UserSubscription',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', models.DateTimeField(default=django.utils.timezone.now)),
+                ('last_modified', models.DateTimeField(default=django.utils.timezone.now)),
+                ('status', models.CharField(choices=[('none', 'None'), ('active', 'Active'), ('past_due', 'Past due'), ('canceled', 'Canceled')], db_index=True, default='none', max_length=32)),
+                ('source', models.CharField(choices=[('none', 'None'), ('stripe', 'Stripe'), ('backer', 'Backer'), ('admin', 'Admin')], default='none', max_length=32)),
+                ('stripe_subscription_id', models.CharField(blank=True, db_index=True, default='', max_length=255)),
+                ('monthly_token_quota_override', models.PositiveIntegerField(blank=True, help_text='Optional per-user override of plan monthly_token_quota.', null=True)),
+                ('plan', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='subscriptions', to='finance.subscriptionplan')),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='subscription', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'User subscription',
+                'verbose_name_plural': 'User subscriptions',
+            },
+        ),
+        migrations.RunPython(seed_plans, migrations.RunPython.noop),
+    ]