feat: add contract_overrides JSONB column to players table

forgejo_admin commented

2026-04-03 23:50:17 +00:00

Owner

Copy link

Type

Feature

Lineage

Sub-ticket of forgejo_admin/westside-contracts#34 — data-driven contract rendering system. Wave 1 (independent).

Repo

forgejo_admin/basketball-api

User Story

As the contract rendering system, I need per-player override data so that individual players can have custom deals (different tournaments, practice schedules, fees) that differ from their team's defaults.

Context

Kiana Sikander (player_id=184, 17U Elite Queens) agreed to $100/month, 1 practice/week, Arizona + Vegas tournaments only. The team default is $200/month, 3 practices/week, 5 tournaments. A sparse JSONB overrides column lets the frontend merge player-specific terms on top of team defaults.

File Targets

alembic/versions/NNN_add_contract_overrides_to_players.py — new migration
src/basketball_api/models.py — add contract_overrides field to Player model

Files NOT to touch:

src/basketball_api/routes/ — no API changes in this ticket
Any team model fields

Acceptance Criteria

contract_overrides JSONB DEFAULT NULL column exists on players table
SQLAlchemy Player model has contract_overrides: Mapped[dict | None] field
Migration is reversible (downgrade drops column)
Existing player rows have NULL contract_overrides
All existing tests pass

Test Expectations

Migration applies cleanly: alembic upgrade head
Migration reverts cleanly: alembic downgrade -1
Run command: pytest tests/

Constraints

Column must be nullable with DEFAULT NULL for backwards compatibility
Use sqlalchemy.dialects.postgresql.JSONB type
Follow existing migration naming convention

Checklist

PR opened
Tests pass
No unrelated changes

westside-basketball — parent project
forgejo_admin/westside-contracts#34 — parent issue

### Type Feature ### Lineage Sub-ticket of `forgejo_admin/westside-contracts#34` — data-driven contract rendering system. Wave 1 (independent). ### Repo `forgejo_admin/basketball-api` ### User Story As the contract rendering system, I need per-player override data so that individual players can have custom deals (different tournaments, practice schedules, fees) that differ from their team's defaults. ### Context Kiana Sikander (player_id=184, 17U Elite Queens) agreed to $100/month, 1 practice/week, Arizona + Vegas tournaments only. The team default is $200/month, 3 practices/week, 5 tournaments. A sparse JSONB overrides column lets the frontend merge player-specific terms on top of team defaults. ### File Targets - `alembic/versions/NNN_add_contract_overrides_to_players.py` — new migration - `src/basketball_api/models.py` — add `contract_overrides` field to Player model Files NOT to touch: - `src/basketball_api/routes/` — no API changes in this ticket - Any team model fields ### Acceptance Criteria - [ ] `contract_overrides JSONB DEFAULT NULL` column exists on players table - [ ] SQLAlchemy Player model has `contract_overrides: Mapped[dict | None]` field - [ ] Migration is reversible (downgrade drops column) - [ ] Existing player rows have NULL contract_overrides - [ ] All existing tests pass ### Test Expectations - [ ] Migration applies cleanly: `alembic upgrade head` - [ ] Migration reverts cleanly: `alembic downgrade -1` - Run command: `pytest tests/` ### Constraints - Column must be nullable with DEFAULT NULL for backwards compatibility - Use `sqlalchemy.dialects.postgresql.JSONB` type - Follow existing migration naming convention ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `westside-basketball` — parent project - `forgejo_admin/westside-contracts#34` — parent issue

forgejo_admin referenced this issue

2026-04-03 23:51:55 +00:00

feat: sponsor blast endpoint with pitch engine and rate limiting #325

forgejo_admin referenced this issue

2026-04-04 20:13:57 +00:00

feat: seed team contract configs + audit player overrides #322

forgejo_admin commented

2026-04-04 21:39:31 +00:00

Author

Owner

Copy link

Scope Review: NEEDS_REFINEMENT

Review note: review-773-2026-04-03
Template complete, file targets verified, acceptance criteria testable, no decomposition needed. One traceability gap:

[SCOPE] Architecture note arch-contracts does not exist in pal-e-docs. Multiple board items reference arch:contracts — backing note needed.

## Scope Review: NEEDS_REFINEMENT Review note: `review-773-2026-04-03` Template complete, file targets verified, acceptance criteria testable, no decomposition needed. One traceability gap: - `[SCOPE]` Architecture note `arch-contracts` does not exist in pal-e-docs. Multiple board items reference `arch:contracts` — backing note needed.

forgejo_admin commented

2026-04-04 21:44:30 +00:00

Author

Owner

Copy link

Agent picked up this ticket.

forgejo_admin referenced this issue from a commit

2026-04-04 21:49:30 +00:00

feat: add contract_overrides JSONB column to players table

forgejo_admin referenced this issue from a pull request that will close it,

2026-04-04 21:49:44 +00:00

feat: add contract_overrides JSONB to players table (#321) #336