# CC Soccer D11 - Session Handoff

**Status:** Schedule Builder working with randomization and configuration persistence

**Last Updated:** January 1, 2025

---

## **Current State - WORKING ✅**

### **Environment:**
- DDEV running Drupal 11
- Database: MySQL
- Git repo: Active, pushed to GitHub
- Site URL: http://ccsoccer-d11.ddev.site/
- Mailhog: http://ccsoccer-d11.ddev.site:8026

### **Core Systems Complete:**
- ✅ All 7 custom entities implemented and working
- ✅ Registration entity (custom, not contrib)
- ✅ Waitlist entity with override system
- ✅ Invitation entity for group/team invitations
- ✅ Commerce integration (products auto-created for seasons/tournaments)
- ✅ Notification system (email via Symfony Mailer, SMS via Clickatell)
- ✅ Complete checkout flow with custom panes
- ✅ **Unified group management** - Same interface handles both season groups AND tournament teams
- ✅ Order completion subscriber creating registrations
- ✅ Roles & permissions system with access control
- ✅ Captain access control for tournament teams
- ✅ Roster Builder with drag-and-drop UI and auto-save
- ✅ Team Balancer algorithm for auto-generating balanced rosters
- ✅ Admin Group Invitations page for managing invitation statuses
- ✅ Schedule Builder with drag-and-drop, workbench, randomization, and config persistence
- ✅ Override system (entity + service complete, needs admin UI)
- ✅ Game status banner (display + cron automation complete, needs admin form)

### **Admin Pages Working:**
- `/admin/ccsoccer/season/{season}/roster` - Roster Builder UI
- `/admin/ccsoccer/season/{season}/schedule` - Schedule Builder UI
- `/admin/ccsoccer/group/{group_id}/invitations` - Group Invitations Management
- `/admin/ccsoccer/seasons` - Season management
- `/admin/ccsoccer/teams` - Team list
- `/admin/ccsoccer/registrations` - Registration list
- `/admin/ccsoccer/overrides` - Override listing (needs full UI)
- `/admin/ccsoccer/waitlist/manage` - Waitlist management

### **User-Facing Pages Working:**
- `/register` - Main registration page with state-based cards
- `/my-registrations` - User's active registrations
- `/my-group/{registration}` - **Unified group/team management** (works for both seasons and tournaments)

### **Test Data System:**
```bash
# Seed comprehensive test data (7 seasons + 3 tournaments)
ddev drush ccs-seed --test --force

# Seed with test users (board_test, slofriendly_test, etc)
ddev drush ccs-seed --users

# Test user credentials:
Username: testuser0 (or board_test, slofriendly_test, etc)
Password: password
```

---

## **Known Issues / TODO**

### **Credits System - Entity Complete, Service Stub:**
**Status:** Credits entity fully implemented with all fields, but CreditManagerService is just a stub

**What's Missing:**
- `calculateCancellationCredit()` method
- `issueCredit()` method
- `applyCredits()` method
- `getUserBalance()` method
- `expireCredits()` method
- Integration with cancellation workflow

**Files:**
- `src/Entity/Credits.php` - ✅ Complete
- `src/Service/CreditManagerService.php` - ❌ Just TODO comment

---

### **Override System - Logic Complete, Needs Admin UI:**
**Status:** OverrideManagerService fully implemented, admin UI needed

**What's Complete:**
- ✅ `OverrideManagerService` with all business logic
- ✅ Create, validate, expire, cancel overrides
- ✅ Cron job for expiration checking
- ✅ Reminder notifications 12 hours before expiry

**What's Missing:**
- Admin form to manually create overrides (e.g., for under-35 in Mens 35+)
- View/manage all active overrides
- Extend override expiration

**Note:** Waitlist-triggered overrides work automatically

---

### **Game Status - Display Complete, Needs Admin Form:**
**Status:** Banner display and automation working, needs management form

**What's Complete:**
- ✅ `hook_page_top()` displays banner after 3PM
- ✅ Shows 3 states: on, off, no_games
- ✅ Cron auto-resets to 'on' at midnight
- ✅ Template: `ccsoccer-game-status-banner.html.twig`

**What's Missing:**
- Admin form to manually set status to 'off'
- Cancellation reason textbox
- "Apply Credits" checkbox to auto-credit players
- Track cancellations for revenue reporting
- Display cancellation reason on schedule with overlay

---

### **Season Entity - Missing League Inheritance Fields:**
**Status:** Season needs fields to inherit/override league defaults

**Fields to Add:**
- `team_size` (inherit from league, can override)
- `day_of_week` (inherit from league, can override)
- `time_slots` (inherit from league, can override)
- `num_fields` (inherit from league, can override)
- `location` (inherit from league, can override)
- `game_duration` (inherit from league, can override)

**Visibility Fields to Add:**
- `active` (boolean - whether season appears in admin)
- `roster_visible` (boolean - players can view rosters)
- `registration_visible` (boolean - season appears on registration page)
- Rename `schedules_visible` → `schedule_visible` (consistency)

---

### **Masquerade Functionality:**
**Status:** Not yet implemented

**Purpose:** Allow admins to masquerade as users for testing/support

**Use Cases:**
- Test registration flow as specific user
- Debug group management issues
- Verify permission checks
- Support users experiencing issues

**Implementation:** Use contrib Masquerade module or build custom

---

### **Reports Needed:**

**1. Pay the City Report**
**Purpose:** Calculate revenue share with city (excludes rainouts)
**Fields:**
- Season name
- Total registrations
- Total revenue collected
- Games cancelled (rainouts)
- Revenue to exclude (cancelled games × price per game)
- Net revenue for city calculation

**2. Insurance Report**
**Purpose:** Player roster for insurance coverage
**Fields:**
- Player name
- DOB
- Contact info
- Emergency contact
- Active seasons/teams
- Registration dates

**3. Tournament Team/Captain Report**
**Purpose:** Track tournament team formation and deposits
**Fields:**
- Tournament name
- Team name
- Captain name/contact
- Deposit paid (Y/N, amount, date)
- Team size (current)
- Max team size
- Pending invitations count
- Roster (player names)
- Registration status (open/closed)

---

### **Schedule Builder Edge Cases:**

May need testing/refinement:
- What happens with odd number of teams?
- What if bye weeks eliminate too many game dates?
- Validation when dragging between different weeks

---

## **Current Sprint - Immediate Priorities**

### **Today/Tomorrow:**
1. User ID banner on all pages (dev environment only)
2. Basic content pages (home, roster, schedule)
3. Menu structure
4. Game status admin form (with credits logic + cancellation tracking)
5. Season entity field additions (visibility + league inheritance)
6. Override admin UI (manual override creation for special cases)
7. Masquerade functionality (for admin/support)

### **Next Sprint:**
8. Reports (City payment, Insurance, Tournament teams)
9. Credit system service implementation
10. Schedule cancellation overlay display

### **Integration Points with Andrew:**
- Team name taxonomy - document structure for roster builder
- User entity fields - verify populated during checkout (skill_level, gender, prefers_goalie)
- Schedule generator - merge algorithm improvements

---

## **Commands to Remember**

### **Daily Development:**
```bash
# Start DDEV
ddev start

# Clear cache (do often!)
ddev drush cr

# Fresh test data with users
ddev drush ccs-seed --test --users --force

# Enhance test users with gender/age/skill
ddev drush ccsoccer:enhance-test-data
```

### **Schedule Builder:**
```bash
# Open schedule builder UI
open http://ccsoccer-d11.ddev.site/admin/ccsoccer/season/8/schedule

# Check game assignments
ddev drush sqlq "SELECT id, game_date, time_slot, home_team, away_team FROM game WHERE season = 8 ORDER BY game_date, time_slot LIMIT 20"

# Count games per week
ddev drush sqlq "SELECT game_date, COUNT(*) as games FROM game WHERE season = 8 GROUP BY game_date"
```

### **Roster Builder:**
```bash
# Open roster builder UI
open http://ccsoccer-d11.ddev.site/admin/ccsoccer/season/8/roster

# Generate rosters via Drush
ddev drush ccsoccer:suggest-rosters 8 --apply

# View current state
ddev drush ccsoccer:roster-state 8
```

---

## **Collaboration Notes**

**Team:**
- Caleb - Lead developer
- Andrew (abmeade@hotmail.com) - Roster building and schedule generation

**Git Workflow:**
- **ALWAYS** `git pull` before `git push` (Andrew may have pushed changes)
- Commit working states frequently
- Clear commit messages

**After Pulling Changes:**
```bash
# Clear cache
ddev drush cr

# If entity fields changed, may need database update
ddev drush updb

# Import any new config
ddev drush config:import --partial --source=modules/custom/ccsoccer/config/install -y
```

**Coordination with Andrew:**
- Andrew working on roster builder algorithm (uses User entity fields: skill_level, gender, prefers_goalie)
- Team name taxonomy integration - Andrew needs to know about taxonomy structure
- Schedule generator - merging Andrew's algorithm improvements with UI

---

## **Test Data Quick Reference**

### **Season 8 (TEST: Coed League):**
- 121 players registered
- 26 teams available
- Team size target: 8 players
- Type: Coed (requires women on each team)

### **Test User Credentials:**

| Username | Password | Role | Notes |
|----------|----------|------|-------|
| `admin` | (existing) | Administrator | Full access |
| `testuser26` | `password` | Player | Has a group with TestUser27 |
| `board_test` | `password` | Board Member | View reports only |
| `slofriendly_test` | `password` | Slofriendly | Tournaments only |

---

## **Success Metrics**

**This Session:**
- ✅ Schedule randomization - each generation produces different valid schedule
- ✅ Configuration persistence - time slots, dates, bye weeks saved during session
- ✅ "Reset to League Defaults" button for clearing saved config
- ✅ Bye weeks persistence added to config storage
- ✅ Documentation cleanup - removed stale captain UI references
- ✅ Added masquerade and reports to todo list

**Previous Sessions:**
- ✅ Server-side workbench with AJAX sync
- ✅ Drag-and-drop schedule editing
- ✅ Week navigation in schedule grid
- ✅ Validation preventing double-booking
- ✅ Unified group management for seasons and tournaments

**Next Session Goals:**
1. Season entity updates (visibility + league inheritance fields)
2. Game status admin form with credits integration
3. Override admin UI
4. Basic content pages
5. Menu structure
6. User ID dev banner
7. Masquerade setup

---

## **Important Reminders**

- **Unified group management** - captains and group managers use same interface at `/my-group/{registration}`
- **Randomization is multi-point** - teams, matchups, home/away, and slots all randomized
- **Config persists per-season** - tempstore key includes season ID
- **Workbench is server-side** - survives page refresh, synced via AJAX
- **TBD slots allowed** - teams can be in workbench, leaving slots empty
- **Reset button only shows** - when there's saved config to clear
- **Bye weeks now persist** - along with all other config settings
- **Override reminders work** - 12 hours before expiry via cron
- **Game status auto-resets** - midnight cron sets to 'on' if was 'off'

---

**End of Handoff - Documentation Updated with Masquerade & Reports**

Current State: Schedule Builder fully functional, documentation accurate
Next Priority: Season fields, game status form, override UI, basic content, masquerade, reports
Breaking Point: Clean - ready for Andrew coordination and content development