Neuste Version

2026-04-29 10:32:05 +02:00
commit 92a68cd079
103 changed files with 14941 additions and 0 deletions
@@ -0,0 +1,104 @@
+# NVJ Turnierplaner - AI Coding Agent Instructions
+
+## Project Overview
+Volleyball tournament organizer (NVJ = Netzroller Volleyball Jugend) for managing teams, rounds, and scoring across two league types: Bundesliga and Champions League. Built with React/TypeScript.
+
+## Architecture
+
+### State Management Pattern
+Single global context provider in [src/context/TournamentContext.tsx](src/context/TournamentContext.tsx):
+- **TournamentProvider** wraps entire app in [App.tsx](src/App.tsx)
+- Access via `useTournament()` hook - throws error if used outside provider
+- State includes: teams, rounds, field count, match results
+- **Critical**: Use `crypto.randomUUID()` for all new IDs (teams, matches, rounds)
+
+### Data Flow
+1. Teams created on Index page → stored in context
+2. `generateMatches()` utility distributes teams across fields/leagues
+3. Rounds track match results and waiting teams
+4. Scores calculated via point differential: `pointsA = -(scoreB - scoreA)`, `pointsB = (scoreB - scoreA)`
+
+### Type System ([src/types/tournament.ts](src/types/tournament.ts))
+- **League**: `'bundesliga' | 'champions'` - string literal types only
+- **Match** includes `result?: MatchResult` - undefined until scores entered
+- **Round** has `completed: boolean` - only one active round allowed at a time
+- **TeamScore** maintains `pointsHistory: number[]` for per-round tracking
+
+## Development Workflow
+
+### Running the App
+```bash
+npm run dev          # Start development server on port 8080
+npm run build        # Production build
+npm run build:dev    # Development mode build
+npm run test         # Run Vitest once
+npm run test:watch   # Watch mode for tests
+```
+
+### Vite Configuration
+- **Path alias**: `@/` maps to `src/` (configured in [vite.config.ts](vite.config.ts))
+- **React deduplication**: Critical for preventing hook errors - never remove from config
+
+## UI Component Conventions
+
+### shadcn/ui Pattern
+- All UI primitives in [src/components/ui/](src/components/ui/) - **do not edit** these directly
+- Import from `@/components/ui/<component>` 
+- Customization via Tailwind classes and variants, not component modification
+
+### Design System ([src/index.css](src/index.css))
+**Custom CSS tokens** (use these instead of arbitrary values):
+- `card-apple` - Standard card styling (rounded-2xl, shadow, border)
+- `card-apple-hover` - Interactive card with hover effects
+- `bg-bundesliga` / `bg-champions` - League-specific colors with matching foregrounds
+- `bg-waiting` / `bg-field` - Status colors for team/field states
+
+**Color semantics**:
+- Bundesliga: Red theme (`--bundesliga: 0 72% 51%`)
+- Champions: Gold/yellow theme (`--champions: 45 93% 47%`)
+- Field: Green (`--field: 142 71% 45%`)
+- All have HSL definitions in CSS custom properties
+
+### Component Structure Pattern
+See [src/components/TournamentView.tsx](src/components/TournamentView.tsx) for reference:
+- Extract sub-components within file for local use (`WaitingTeam`, `LeagueSection`)
+- Use typed icon props: `icon: typeof Trophy` instead of React.ComponentType
+- Filter round data at component level, not in context
+
+## Key Files & Responsibilities
+
+- [src/utils/tournamentUtils.ts](src/utils/tournamentUtils.ts) - Match generation with field distribution logic
+- [src/context/TournamentContext.tsx](src/context/TournamentContext.tsx) - All tournament state mutations
+- [src/pages/Index.tsx](src/pages/Index.tsx) - Team setup interface
+- [src/pages/Tournament.tsx](src/pages/Tournament.tsx) - Active tournament management
+- [src/components/MatchScoreInput.tsx](src/components/MatchScoreInput.tsx) - Score entry with point calculation
+
+## Project-Specific Rules
+
+1. **Never modify completed rounds** - `completed: true` rounds are immutable
+2. **Field allocation**: Bundesliga and Champions always share fields evenly (±1) when both have teams
+3. **Waiting teams**: Odd-numbered teams in a league → last team waits (see `createMatchesForLeague`)
+4. **Score point mapping**: Differential-based, not win/loss binary
+5. **Component naming**: PascalCase files match export name exactly
+6. **Routing**: Custom routes MUST be above `path="*"` catch-all in [App.tsx](App.tsx)
+
+## Dependencies Notes
+
+- **Bun runtime**: Package manager is Bun (uses bun.lockb), but npm scripts work
+- **React Router**: v6 pattern with BrowserRouter
+- **React Query**: QueryClient setup in App.tsx but minimal usage currently
+- **Lucide React**: Icon library of choice (see imports in components)
+- **Sonner + shadcn Toast**: Dual toast systems - prefer Sonner for new toasts
+
+## Testing
+
+- Vitest + Testing Library configured ([vitest.config.ts](vitest.config.ts))
+- Test setup in [src/test/setup.ts](src/test/setup.ts)
+- Run with `npm run test:watch` for development
+
+## Common Pitfalls
+
+- Don't destructure `useTournament()` before checking context existence
+- TypeScript paths require build tool awareness - always use `@/` imports
+- Custom CSS utilities won't work without `@layer utilities` wrapper
+- Dark mode is class-based - test both light/dark themes