Phase 5: Core API Endpoints + Integration Tests

phase-mcd-tracker-5-core-api Phase

phase

Project

Goal: Full CRUD API with rolling window logic, integration tests, deployed to prod. The app is functional.

Owner: Dev agent

Repo: forgejo_admin/mcd-tracker-api

Depends on: Phase 4 (COMPLETED — auth ready)

Scope

Implement all API routes from arch-dataflow-mcd-tracker. Rolling window logic is the core business rule: 5 codes per location per user per rolling 30-day window.

Routes

POST /locations — save a McDonald's location (auth: user)
GET /locations — list user's saved locations (auth: user)
POST /locations/{id}/codes — log a coupon code at a location (auth: user, enforces 5-slot limit)
GET /locations/{id}/codes — list codes at a location (auth: user)
PATCH /codes/{id}/redeem — mark code as redeemed (auth: user)
GET /locations/{id}/slots — slot availability: remaining (0-5), next reopen date (auth: user)
GET /dashboard — all locations with slot status for current user (auth: user)
GET /admin/stats — aggregate stats across all users (auth: admin)

Rolling Window Logic

Count active codes: WHERE expires_at > NOW()
Available slots = 5 - active_count
Next reopen = MIN(expires_at) from active codes
On POST /codes: check count first, reject with 409 if full
expires_at = used_at + timedelta(days=30) — set on insert

Architecture Touch

arch-dataflow-mcd-tracker — all 4 runtime flows implemented: log code, check availability, redeem, slot limit rejection. arch-domain-mcd-tracker#rolling-window-logic — the SQL queries from the diagram become SQLAlchemy queries.

Verification

All routes respond correctly with auth
Log 5 codes → slots = 0. Log 6th → 409 with next reopen date
Redeem a code → redeemed_at set
Dashboard shows all locations with slot counts
Admin stats endpoint restricted to admin role
Integration tests cover all routes + edge cases

pending