# CC Soccer D11 - Session Handoff

**Status:** Roles & permissions complete, captain access control implemented and tested

**Last Updated:** December 29, 2024

---

## **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
- ✅ Group management for seasons
- ✅ Team management for tournaments
- ✅ Order completion subscriber creating registrations
- ✅ **Roles & permissions system with access control**
- ✅ **Captain access control for tournament teams**

### **User-Facing Pages Working:**
- `/register` - Main registration page with state-based cards
- `/my-registrations` - User's active registrations
- `/my-group/{registration}` - Group/team management
- `/tournament/{tournament}/team/{team}/manage` - Captain team management (UI TODO)

### **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
```

---

## **Major Accomplishment This Session**

### **Implemented Complete Role-Based Access Control**

**Goal:** Implement proper role-based permissions so Board Members can view reports and update game status, Slofriendly can manage tournaments, and team captains can manage their own teams.

**Implementation:**

#### **1. Created Roles**

**Board Member Role** (`board_member`)
- View reports (teams, games, registrations, credits)
- Send notifications
- Update game status
- View but NOT edit data

**Slofriendly Role** (`slofriendly`)
- All Board Member permissions PLUS:
- Manage tournaments (create, edit, view)
- Edit team names
- Tournament director role

**Files Created:**
- `config/install/user.role.board_member.yml`
- `config/install/user.role.slofriendly.yml`

#### **2. Updated Routing Permissions**

**Before:** Most routes required `administer ccsoccer` (admin only)

**After:** Granular permissions mapped to roles:

| Route | Old Permission | New Permission | Access |
|-------|---------------|----------------|---------|
| `/admin/ccsoccer/seasons/*` | `administer ccsoccer` | `manage seasons` | Admin only |
| `/admin/ccsoccer/tournaments/*` | `administer ccsoccer` | `manage tournaments` | Admin, Slofriendly |
| `/admin/ccsoccer/teams` | `administer ccsoccer` | `view reports` | Admin, Board Member, Slofriendly |
| `/admin/ccsoccer/games` | `administer ccsoccer` | `view reports` | Admin, Board Member, Slofriendly |
| `/admin/ccsoccer/registrations` | `administer ccsoccer` | `manage registrations` | Admin, Board Member |
| `/admin/ccsoccer/game-status` | N/A | `update game status` | Admin, Board Member |

**Files Modified:**
- `ccsoccer.routing.yml` - Updated all routes with specific permissions
- `ccsoccer.permissions.yml` - Removed `manage tournament teams` permission

#### **3. Captain Access Control**

**Decision:** Captain is NOT a Drupal role - it's a field relationship on Team entity.

**Implementation:**
- Created `TeamCaptainAccessCheck` custom access checker
- Checks if `current_user.uid == team.captain.target_id`
- Admin always has override access
- Season teams cannot be managed by captains (only tournament teams)

**Logic:**
```php
// Admin override
if ($account->hasPermission('administer ccsoccer')) {
  return AccessResult::allowed();
}

// Must be tournament team
if (!$team->get('tournament')->target_id) {
  return AccessResult::forbidden('Season teams cannot be managed by captains');
}

// Check if user is captain
if ($team->get('captain')->target_id == $account->id()) {
  return AccessResult::allowed();
}

return AccessResult::forbidden('You are not the captain of this team');
```

**Files Created:**
- `src/Access/TeamCaptainAccessCheck.php` - Custom access checker
- `src/Controller/TournamentController.php` - Stub methods for captain routes
- `src/Form/TournamentTeamNotificationForm.php` - Stub form

**Files Modified:**
- `ccsoccer.services.yml` - Registered access checker as service
- `ccsoccer.routing.yml` - Added 4 captain routes with custom access

**Routes Added:**
- `/tournament/{tournament}/team/{team}/manage` - Manage roster
- `/tournament/{tournament}/team/{team}/invite` - Invite players (POST)
- `/tournament/{tournament}/team/{team}/remove/{user}` - Remove player (POST)
- `/tournament/{tournament}/team/{team}/notifications` - Send notifications

**Testing Completed:**
- ✅ Captain (uid 27) can access team 5 management
- ✅ Non-captain denied access
- ✅ Admin can access any team
- ✅ Service registration successful
- ✅ Routes resolve correctly

#### **4. Test User Seeding**

Added test users with different roles for easy testing:

**Test Users Created:**
- `player_test` - Regular authenticated user
- `board_test` - Board Member role
- `slofriendly_test` - Slofriendly role
- `captain_test` - Regular user (becomes captain when they pay deposit)

All passwords: `password`

**Seeding Integration:**
```bash
# Create test users standalone
ddev drush ccsoccer:seed-users

# Seed data AND users in one command
ddev drush ccs-seed --users

# Still works without users (default)
ddev drush ccs-seed
```

**Files Modified:**
- `src/Drush/Commands/CcsoccerCommands.php` - Added `--users` flag and `seedUsers()` method

**Testing Completed:**
- ✅ Board Member can view teams/games/registrations but NOT edit
- ✅ Board Member can update game status
- ✅ Board Member CANNOT access seasons or tournaments
- ✅ Slofriendly can access tournaments
- ✅ Slofriendly has all Board Member permissions
- ✅ Regular player denied access to admin areas

---

## **Architecture Decisions**

### **Custom Registration Entity (Not Contrib)**

**Decision:** Built completely custom Registration entity instead of extending contrib Registration module.

**Rationale:**
- Contrib Registration designed for "host entity" pattern (events that people register for)
- Our use case: Direct entity references (player → season, player → tournament)
- Avoided fighting module assumptions about workflows
- Cleaner queries without extra joins
- Full control over complex field requirements (XOR constraints, status transitions)

**Trade-off:** More initial work, but much cleaner long-term maintenance

### **Captain as Entity Relationship (Not Role)**

**Decision:** Captain is a field on Team entity, not a Drupal role.

**Rationale:**
- Captains are per-team, not global
- Same user can be captain of multiple teams
- Same user can be captain of one team but not another
- Simpler to manage (no role assignment/removal needed)
- Custom access checker handles programmatic access control

**Implementation:** `TeamCaptainAccessCheck` verifies `current_user == team.captain`

### **Role Hierarchy**

```
Anonymous
  └─ Authenticated (Player - default)
       └─ Board Member (4 permissions)
            └─ Slofriendly (6 permissions)
                 └─ Administrator (all permissions)

Captain (NOT a role - Team.captain field relationship)
```

---

## **Next Session Priorities**

### **Build Captain Team Management UI**

Captain routes are wired up with working access control, but controller methods are stubs. Need to build:

**1. Team Roster Management (`manageTeam()` controller)**
- Show current team members (with contact info for captain)
- Invite button → form to send invitation
- Remove player links → confirmation + removal logic
- Send team notification link
- Team details display

**2. Invitation System (`invitePlayer()` controller)**
- Accept email or search for existing user
- Create invitation record
- Send email with magic link
- Handle acceptance workflow

**3. Remove Player (`removePlayer()` controller)**
- Verify player is on team
- Remove registration relationship
- Send notification to removed player
- Handle refund logic if needed

**4. Team Notifications (`TournamentTeamNotificationForm`)**
- Textarea for message
- Options: Email, SMS, Both
- Preview recipient list
- Integration with NotificationService
- Confirmation and sending

**File Locations:**
- Controller: `src/Controller/TournamentController.php` (methods exist as stubs)
- Form: `src/Form/TournamentTeamNotificationForm.php` (stub exists)
- Template: `templates/ccsoccer-tournament-team-manage.html.twig` (create)

### **TESTING: Role-Based Access**

Comprehensive testing needed for all role scenarios:

**Test as board_test:**
1. Log in: Username `board_test`, Password `password`
2. Access `/admin/ccsoccer/registrations` → ✅ Should work
3. Access `/admin/ccsoccer/teams` → ✅ Should work (view only)
4. Try to edit a team → ❌ Should be denied
5. Access `/admin/ccsoccer/game-status` → ✅ Should work
6. Access `/admin/ccsoccer/seasons` → ❌ Should be denied
7. Access `/admin/ccsoccer/tournaments` → ❌ Should be denied

**Test as slofriendly_test:**
1. Log in: Username `slofriendly_test`, Password `password`
2. All board_test permissions → ✅ Should work
3. Access `/admin/ccsoccer/tournaments` → ✅ Should work
4. Create/edit tournaments → ✅ Should work
5. Access `/admin/ccsoccer/seasons` → ❌ Should be denied

**Test as captain_test:**
1. Log in: Username `captain_test`, Password `password`
2. Access `/tournament/16/team/5/manage` → ❌ Should be denied (not captain yet)
3. Make captain_test the captain of team 5:
   ```bash
   ddev drush sqlq "UPDATE team SET captain = 27 WHERE id = 5"
   ddev drush cr
   ```
4. Access `/tournament/16/team/5/manage` → ✅ Should work
5. Try to access another team → ❌ Should be denied

### **Document Current Permission Matrix**

Create comprehensive documentation of:
- Which roles can access which routes
- Permission inheritance
- Special cases (captain access)
- How to test each scenario

---

## **Known Issues / TODO**

### **Captain UI - Not Yet Built**
**Status:** Access control complete, routes exist, controller methods are stubs

**What's Missing:**
- Team roster display with member details
- Invitation form and handler
- Remove player confirmation and logic
- Team notification form functionality

**Files with TODO Comments:**
- `src/Controller/TournamentController.php` - All methods have detailed TODO
- `src/Form/TournamentTeamNotificationForm.php` - Stub form

### **Role Import for Collaborators**

When Andrew pulls from git, roles won't auto-import. He needs to run:
```bash
ddev drush config:import --partial --source=modules/custom/ccsoccer/config/install -y
ddev drush cr
```

Consider adding this to README or creating a setup script.

---

## **Key Files Modified This Session**

**Roles & Config:**
- `config/install/user.role.board_member.yml` - Created
- `config/install/user.role.slofriendly.yml` - Created

**Routing & Permissions:**
- `ccsoccer.routing.yml` - Updated all route permissions, added captain routes
- `ccsoccer.permissions.yml` - Removed `manage tournament teams`

**Access Control:**
- `src/Access/TeamCaptainAccessCheck.php` - Created custom access checker
- `ccsoccer.services.yml` - Registered access checker service

**Controllers & Forms:**
- `src/Controller/TournamentController.php` - Updated with stub captain methods
- `src/Form/TournamentTeamNotificationForm.php` - Created stub form

**Drush Commands:**
- `src/Drush/Commands/CcsoccerCommands.php` - Added `--users` flag and `seedUsers()`

---

## **Database Validation Queries**

**Check roles exist:**
```bash
ddev drush sqlq "SELECT id, label FROM user_role WHERE id IN ('board_member', 'slofriendly')"
```

**Check test users have correct roles:**
```bash
ddev drush sqlq "SELECT u.uid, u.name, r.roles_target_id FROM users_field_data u LEFT JOIN user__roles r ON u.uid = r.entity_id WHERE u.name IN ('board_test', 'slofriendly_test')"
```

**Check captain of team 5:**
```bash
ddev drush sqlq "SELECT id, name, captain, tournament FROM team WHERE id = 5"
```

**Verify tournament teams exist:**
```bash
ddev drush sqlq "SELECT id, name, tournament, captain FROM team WHERE tournament IS NOT NULL"
```

---

## **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

# Check Mailhog for emails
open http://ccsoccer-d11.ddev.site:8026

# Git workflow (ALWAYS pull first - Andrew may have pushed!)
git pull
git status
git add .
git commit -m "message"
git push origin main
```

### **Role & Permission Testing:**
```bash
# Create test users with roles
ddev drush ccsoccer:seed-users

# Log in as specific user (one-time link)
ddev drush uli --name=board_test
ddev drush uli --name=slofriendly_test
ddev drush uli --name=captain_test

# Check user roles
ddev drush user:information board_test

# Import role config (for collaborators)
ddev drush config:import --partial --source=modules/custom/ccsoccer/config/install -y
```

### **Debugging:**
```bash
# Watch Drupal logs
ddev drush watchdog:show --type=ccsoccer --count=20

# Check specific registration
ddev drush sqlq "SELECT * FROM ccsoccer_registration WHERE player = 23"

# Check permissions for user
ddev drush sqlq "SELECT roles_target_id FROM user__roles WHERE entity_id = 25"
```

---

## **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
# Import any new config (roles, etc)
ddev drush config:import --partial --source=modules/custom/ccsoccer/config/install -y

# Clear cache
ddev drush cr

# Optionally create test users
ddev drush ccsoccer:seed-users
```

**Entity Updates:**
- Drupal 10/11: Use update hooks in `.install` file
- No `drush entity:updates` command (doesn't exist anymore)
- Always clear cache after entity changes

---

## **Test User Quick Reference**

| Username | Password | Role | Can Access |
|----------|----------|------|------------|
| `admin` | (existing) | Administrator | Everything |
| `testuser0` | `password` | Player | Register, own data, manage groups |
| `player_test` | `password` | Player | Same as testuser0 |
| `board_test` | `password` | Board Member | View reports, send notifications, update game status |
| `slofriendly_test` | `password` | Slofriendly | Board Member perms + manage tournaments |
| `captain_test` | `password` | Player | Becomes captain when assigned to Team.captain field |

**Login Commands:**
```bash
ddev drush uli --name=board_test
ddev drush uli --name=slofriendly_test
ddev drush uli --name=captain_test
```

---

## **Success Metrics**

**This Session:**
- ✅ Board Member and Slofriendly roles created
- ✅ Permissions mapped to routes
- ✅ All route permissions updated from generic to specific
- ✅ Custom TeamCaptainAccessCheck implemented and tested
- ✅ Captain routes active with working access control
- ✅ Test user seeding integrated into main seed command
- ✅ Access control tested and verified working
- ✅ Clean breaking point - all code wired up, UI is TODO

**Next Session Goal:**
- ✅ Build captain team management UI
- ✅ Complete invitation workflow for captains
- ✅ Test remove player functionality
- ✅ Implement team notification form
- ✅ Document complete permission matrix

---

## **Important Reminders**

- **Captain is NOT a role** - it's a Team.captain field relationship
- **Access checker verifies per-team** - same user can be captain of some teams but not others
- **Board Member can VIEW but not EDIT** - read-only access to admin areas
- **Slofriendly is additive** - has all Board Member permissions PLUS tournament management
- **Test users created with `--users` flag** - optional, safe to run multiple times
- **Roles must be imported** - collaborators need to run config:import after git pull
- **Controller methods exist as stubs** - access control works, UI needs building

---

**End of Handoff - Captain Access Control Complete**

Current State: Role-based permissions fully implemented and tested, captain access working
Next Priority: Build UI for captain team management
Breaking Point: Clean - all access control wired up, stubs marked with TODO