Migration: add monthly ProductCategory, first_payment EmailType, seed prorated product

forgejo_admin commented

2026-04-07 01:11:11 +00:00

Owner

Type

Feature

Lineage

Decomposed from forgejo_admin/basketball-api#366. Ticket A of 3 — prerequisite for B (checkout endpoint) and C (email + blast).

Repo

forgejo_admin/basketball-api

User Story

As a developer implementing the first-payment feature
I want the database schema to support monthly product category and first_payment email tracking
So that the checkout and email endpoints have the enums and product row they need

Context

The first-payment feature requires two new enum values (ProductCategory.monthly, EmailType.first_payment) and a seeded Product row ("Monthly Fee — Prorated April") for the Orders table FK. This migration is the prerequisite for the checkout endpoint (ticket B) and email blast (ticket C). Both depend on these enum values and the product row existing.

File Targets

Files to create:

alembic/versions/031_add_monthly_category_and_first_payment_email.py — migration with enum additions and product seed

Files to modify:

src/basketball_api/models.py:63-70 — add first_payment to EmailType enum (after interest_notification)
src/basketball_api/models.py:123-128 — add monthly to ProductCategory enum (after equipment)

Files NOT to touch:

Any route or service files — those are ticket B and C scope

Acceptance Criteria

ProductCategory.monthly exists in Python enum and Postgres
EmailType.first_payment exists in Python enum and Postgres
Product row "Monthly Fee — Prorated April" seeded with product_type=one_time, category=monthly, price_cents=0, tenant_id=1
alembic upgrade head applies cleanly
alembic downgrade removes the product row (enum values remain — Postgres limitation)

Test Expectations

Unit test: verify ProductCategory.monthly and EmailType.first_payment are valid enum members
Integration test: migration applies and rolls back cleanly on test DB
Run: cd ~/basketball-api && alembic upgrade head && alembic downgrade -1 && alembic upgrade head

Constraints

Latest migration is 030_add_registration_type_to_registrations.py — new revision is 031
Use ALTER TYPE ... ADD VALUE IF NOT EXISTS for Postgres enum safety
Use ON CONFLICT DO NOTHING for product seed idempotency
tenant_id=1 is westside-kings-queens (seeded in 001_initial)

Checklist

PR opened
Tests pass
No unrelated changes

westside-basketball — project
Parent: forgejo_admin/basketball-api#366
Spec: ~/pal-e-platform/docs/superpowers/specs/2026-04-06-first-payment-email-design.md
Plan: ~/pal-e-platform/docs/superpowers/plans/2026-04-06-first-payment-email.md (Task 1)

### Type Feature ### Lineage Decomposed from `forgejo_admin/basketball-api#366`. Ticket A of 3 — prerequisite for B (checkout endpoint) and C (email + blast). ### Repo `forgejo_admin/basketball-api` ### User Story As a developer implementing the first-payment feature I want the database schema to support monthly product category and first_payment email tracking So that the checkout and email endpoints have the enums and product row they need ### Context The first-payment feature requires two new enum values (`ProductCategory.monthly`, `EmailType.first_payment`) and a seeded Product row ("Monthly Fee — Prorated April") for the Orders table FK. This migration is the prerequisite for the checkout endpoint (ticket B) and email blast (ticket C). Both depend on these enum values and the product row existing. ### File Targets Files to create: - `alembic/versions/031_add_monthly_category_and_first_payment_email.py` — migration with enum additions and product seed Files to modify: - `src/basketball_api/models.py:63-70` — add `first_payment` to `EmailType` enum (after `interest_notification`) - `src/basketball_api/models.py:123-128` — add `monthly` to `ProductCategory` enum (after `equipment`) Files NOT to touch: - Any route or service files — those are ticket B and C scope ### Acceptance Criteria - [ ] `ProductCategory.monthly` exists in Python enum and Postgres - [ ] `EmailType.first_payment` exists in Python enum and Postgres - [ ] Product row "Monthly Fee — Prorated April" seeded with `product_type=one_time`, `category=monthly`, `price_cents=0`, `tenant_id=1` - [ ] `alembic upgrade head` applies cleanly - [ ] `alembic downgrade` removes the product row (enum values remain — Postgres limitation) ### Test Expectations - [ ] Unit test: verify `ProductCategory.monthly` and `EmailType.first_payment` are valid enum members - [ ] Integration test: migration applies and rolls back cleanly on test DB - Run: `cd ~/basketball-api && alembic upgrade head && alembic downgrade -1 && alembic upgrade head` ### Constraints - Latest migration is `030_add_registration_type_to_registrations.py` — new revision is `031` - Use `ALTER TYPE ... ADD VALUE IF NOT EXISTS` for Postgres enum safety - Use `ON CONFLICT DO NOTHING` for product seed idempotency - `tenant_id=1` is westside-kings-queens (seeded in 001_initial) ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `westside-basketball` — project - Parent: `forgejo_admin/basketball-api#366` - Spec: `~/pal-e-platform/docs/superpowers/specs/2026-04-06-first-payment-email-design.md` - Plan: `~/pal-e-platform/docs/superpowers/plans/2026-04-06-first-payment-email.md` (Task 1)

forgejo_admin commented

2026-04-07 01:13:54 +00:00

Author

Owner

Scope Review: READY

Review note: review-873-2026-04-06
Scope is solid — all file targets verified against codebase, template complete, traceability triangle intact (story:WS-S7 confirmed on project page). Single-repo, single-agent pass under 5 minutes.

[SCOPE] Missing arch note arch-basketball-api in pal-e-docs (platform-wide gap, does not block this ticket)

## Scope Review: READY Review note: `review-873-2026-04-06` Scope is solid — all file targets verified against codebase, template complete, traceability triangle intact (story:WS-S7 confirmed on project page). Single-repo, single-agent pass under 5 minutes. - `[SCOPE]` Missing arch note `arch-basketball-api` in pal-e-docs (platform-wide gap, does not block this ticket)