Add multi-league foundation

2026-05-22 20:47:28 +02:00
parent e032994628
commit 15e1dc227b
23 changed files with 775 additions and 205 deletions
@@ -0,0 +1,53 @@
+# LeagueLedger Roadmap
+
+This roadmap is based on a senior-developer inspection of the current FastAPI, Jinja, and SQLAlchemy codebase.
+
+## Current Findings
+
+- LeagueLedger currently treats teams, QR sets, events, redemptions, and leaderboards as global records. That blocks multiple pubs or organizers from sharing one installation cleanly.
+- Database migrations are split between `app/db.py` and `app/db_migrations.py`. This increases drift risk because schema changes can land in one path and not the other.
+- Tests are thin and some existing tests mock SQLAlchemy chains in ways that do not match the current query implementation.
+- Several workflows still include compatibility branches for removed model names, which makes behavior harder to reason about.
+- QR redemption did not consistently record the redeeming user on the QR code record, weakening auditability.
+
+## Milestones
+
+### 1. Multi-League Foundation
+
+Status: implemented in this branch.
+
+Acceptance criteria:
+- Add a `League` model with a default league for existing data.
+- Attach teams, QR sets, QR codes, and events to a league.
+- Filter team lists, QR dashboards, leaderboards, and redemption team choices by league.
+- Keep existing URLs and seeded data working.
+- Backfill existing records into the default league during startup migrations.
+
+### 2. League Administration
+
+Acceptance criteria:
+- Add a dedicated admin workflow for creating, editing, activating, and archiving leagues.
+- Allow league managers to administer only their own league.
+- Replace generic admin CRUD for league-sensitive records with validated forms where needed.
+- Add tests for league creation, activation, and manager permissions.
+
+### 3. Data Isolation and Permissions
+
+Acceptance criteria:
+- Introduce league-level roles for owners, quiz masters, and staff.
+- Enforce league boundaries in every query that reads or mutates teams, events, QR sets, QR codes, achievements, and leaderboards.
+- Add authorization tests covering cross-league access attempts.
+
+### 4. Migration Cleanup
+
+Acceptance criteria:
+- Consolidate schema migrations into one approach.
+- Add repeatable migration tests against a fresh database and a simulated legacy database.
+- Remove stale compatibility code after migration coverage is in place.
+
+### 5. Release Hardening
+
+Acceptance criteria:
+- Add CI checks for syntax, tests, and a lightweight app smoke test.
+- Document local development with 1Password-injected environment secrets.
+- Add a release checklist with migration, rollback, and verification steps.
@@ -0,0 +1,26 @@
+# Senior Developer Inspection Prompt
+
+Use this prompt to inspect LeagueLedger before planning or implementing roadmap work.
+
+```text
+You are a senior product-minded software engineer reviewing LeagueLedger, a FastAPI, Jinja, and SQLAlchemy web application for pub quiz leagues, teams, QR-code redemptions, leaderboards, and rewards.
+
+Adopt a code-review stance first. Prioritize correctness, data isolation, migration safety, security, tests, and operational risk over cosmetic cleanup. Inspect the repository before proposing changes.
+
+Goals:
+- Identify the current domain model and the boundaries between leagues, teams, QR sets, QR codes, events, users, and admin workflows.
+- Find bugs, missing constraints, hardcoded assumptions, migration risks, stale compatibility code, security issues, and test gaps.
+- Propose a milestone roadmap that can move the project forward safely in small, releasable increments.
+- For each milestone, define user-visible behavior, code areas touched, database changes, verification steps, and rollback considerations.
+
+Special focus:
+- Multi-publisher and multi-league support. A league should isolate teams, QR assets, events, redemptions, and leaderboards so multiple pubs or organizers can operate in the same app.
+- Backward compatibility with existing single-league data.
+- Avoid exposing secrets. Prefer 1Password-injected secrets for any developer environment or deployment credentials.
+
+Output:
+1. Findings ordered by severity, with file-level references.
+2. Recommended architecture and domain boundaries.
+3. A milestone roadmap with acceptance criteria.
+4. The smallest safe first milestone to implement immediately.
+```