# CC Soccer Module - Installation & Setup Guide

This guide explains how to install and use the CC Soccer module scaffold.

---

## What You're Getting

### Complete Module Structure

This is a **real, working Drupal module** with:

✅ All directories organized  
✅ All configuration files defined  
✅ All placeholders created with detailed comments  
✅ Complete architecture documented  
✅ Services, entities, forms, plugins outlined  

**BUT - Implementation code is not written yet.** Each file is a placeholder with TODO comments explaining what to build.

Think of this as your **blueprint and scaffolding**. The structure is there, now you fill it in piece by piece.

---

## Installation Steps

### Step 1: Download the Module

You should have received a folder called `cc_soccer/` with this structure:

```
cc_soccer/
├── cc_soccer.info.yml
├── cc_soccer.module
├── cc_soccer.routing.yml
├── cc_soccer.permissions.yml
├── cc_soccer.links.menu.yml
├── cc_soccer.services.yml
├── composer.json
├── README.md
├── config/
│   ├── install/
│   └── schema/
├── src/
│   ├── Entity/
│   ├── Service/
│   ├── Form/
│   ├── Plugin/
│   └── Controller/
├── templates/
└── tests/
```

---

### Step 2: Place Module in Your Site

```bash
# Navigate to your Drupal site
cd ~/Sites/ccsoccer-d11

# Create custom modules directory if it doesn't exist
mkdir -p web/modules/custom

# Copy the cc_soccer folder there
# (Download from chat and copy, or use scp/rsync)
cp -r /path/to/downloaded/cc_soccer web/modules/custom/

# Verify it's there
ls -la web/modules/custom/cc_soccer
```

---

### Step 3: Enable the Module

```bash
# Enable via Drush
ddev drush en cc_soccer -y

# Clear cache
ddev drush cr

# Verify it's enabled
ddev drush pml | grep "CC Soccer"
```

**Expected output:**
```
CC Soccer (cc_soccer)    Enabled    11.x-1.0-dev
```

---

### Step 4: Verify Installation

1. **Check admin menu:**
   - Go to: `/admin`
   - You should see "CC Soccer" in the menu
   - (Links won't work yet - that's expected!)

2. **Check permissions:**
   - Go to: `/admin/people/permissions`
   - Scroll to "CC Soccer" section
   - You should see all permissions listed

3. **Check logs:**
   ```bash
   ddev drush watchdog:show
   ```
   - Should show no errors related to cc_soccer

---

### Step 5: Commit to Git

```bash
cd ~/Sites/ccsoccer-d11

# Add module to Git
git add web/modules/custom/cc_soccer

# Commit
git commit -m "Add cc_soccer module scaffold

- Complete directory structure
- Entity placeholders (League, Season, Team, Game, Credits)
- Service placeholders (7 services)
- Form placeholders (5 admin forms)
- Commerce checkout panes (5 panes)
- Routing, permissions, menus configured
- Ready for incremental implementation"

# Push to GitHub
git push origin main
```

---

## What Happens Next?

### The Module is INSTALLED but EMPTY

**What works:**
- ✅ Module enabled
- ✅ Permissions defined
- ✅ Menu items exist
- ✅ Services registered
- ✅ File structure complete

**What doesn't work yet:**
- ❌ Entities (need to be built)
- ❌ Forms (need to be built)
- ❌ Services (need implementation)
- ❌ Checkout panes (need implementation)
- ❌ Any actual functionality

**This is expected!** You now have the structure to build incrementally.

---

## Building Incrementally

### Recommended Build Order

#### **Phase 1: Core Entities (Week 1-2)**

Start with the data model:

1. **Build League entity**
   - File: `src/Entity/League.php`
   - Read TODO comments
   - Implement `baseFieldDefinitions()`
   - Enable entity via update hook
   - Test: Create a league via Drupal UI

2. **Build Season entity**
   - File: `src/Entity/Season.php`
   - Implement all fields
   - Implement helper methods (isFull, getSpotsRemaining, etc.)
   - Test: Create a season

3. **Extend User entity**
   - Add fields via update hook:
     ```php
     // In cc_soccer.install:
     function cc_soccer_update_9001() {
       $fields = [
         'field_first_name' => 'string',
         'field_jersey_size' => 'list_string',
         // etc...
       ];
       // Create field storage and instances
     }
     ```
   - Run update: `ddev drush updb -y`

4. **Test data model**
   - Create leagues via UI
   - Create seasons via UI
   - Verify relationships work

#### **Phase 2: Registration Flow (Week 3-4)**

Now connect to Commerce:

1. **Create Commerce products**
   - Season Registration product type
   - Tournament Registration product type
   - Jersey product
   - Deposit product

2. **Build RegistrationService**
   - File: `src/Service/RegistrationService.php`
   - Implement `processRegistration()`
   - Implement `onPaymentComplete()`
   - Implement `canRegister()`

3. **Build checkout panes**
   - Start with PlayerInfoPane
   - Then GroupSelectionPane
   - Test checkout flow

4. **Hook into Commerce**
   - Implement `hook_commerce_checkout_complete()` in `cc_soccer.module`
   - Call RegistrationService
   - Test complete flow: Add to cart → Checkout → Payment → Registration created

#### **Phase 3: Team & Schedule (Week 5-6)**

Build the generation tools:

1. **Build Team entity**
   - File: `src/Entity/TeamGameCredits.php` (separate Team class)
   - Implement fields

2. **Build Game entity**
   - Implement fields
   - Test: Create games manually

3. **Build TeamBalancerService**
   - File: `src/Service/TeamBalancerService.php`
   - Implement `generateTeams()`
   - Start simple (just distribute evenly)
   - Add balancing later

4. **Build RosterBuilderForm**
   - File: `src/Form/AdminForms.php` (separate RosterBuilderForm class)
   - Call TeamBalancerService
   - Display results
   - Add manual adjustments later

5. **Build ScheduleGeneratorService**
   - File: `src/Service/ScheduleGeneratorService.php`
   - Implement round-robin
   - Add time slot balancing

6. **Build ScheduleBuilderForm**
   - Call ScheduleGeneratorService
   - Display preview
   - Add manual edits later

#### **Phase 4: Waitlist & Credits (Week 7-8)**

Add supporting systems:

1. **Build WaitlistManagerService**
   - Implement queue logic
   - Integrate with OverrideManager

2. **Build OverrideManagerService**
   - Implement override lifecycle
   - Add cron support

3. **Build CreditManagerService**
   - Implement credit calculation
   - Implement issuance
   - Add expiration cron

4. **Build NotificationService**
   - Set up Message templates
   - Implement sending logic
   - Add Clickatell integration

#### **Phase 5: Reports & Polish (Week 9-10)**

Finish the system:

1. **Create Views**
   - Jersey report
   - Deposit report
   - Player lists
   - Schedule displays

2. **Add remaining forms**
   - Waitlist management
   - Override management

3. **Testing**
   - Generate test data
   - Test all workflows
   - Fix bugs

4. **Documentation**
   - Update README
   - Add inline comments
   - Create user guides

---

## How to Build Each Piece

### Example: Building League Entity

1. **Open the file:**
   ```bash
   code web/modules/custom/cc_soccer/src/Entity/League.php
   ```

2. **Read the TODO comments:**
   - Shows what fields you need
   - Shows what each field should be

3. **Implement fields:**
   ```php
   public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
     $fields = parent::baseFieldDefinitions($entity_type);

     // Name field (already there)
     
     // Add type field
     $fields['type'] = BaseFieldDefinition::create('list_string')
       ->setLabel(t('League Type'))
       ->setRequired(TRUE)
       ->setSettings([
         'allowed_values' => [
           'coed' => 'Coed',
           'mens' => "Men's",
           'tournament_series' => 'Tournament Series',
         ],
       ])
       ->setDisplayOptions('form', [
         'type' => 'options_select',
         'weight' => 1,
       ]);

     // Add team_size_min field
     $fields['team_size_min'] = BaseFieldDefinition::create('integer')
       ->setLabel(t('Minimum Team Size'))
       ->setRequired(TRUE)
       ->setDefaultValue(6)
       ->setDisplayOptions('form', [
         'type' => 'number',
         'weight' => 2,
       ]);

     // Continue for all fields...

     return $fields;
   }
   ```

4. **Clear cache:**
   ```bash
   ddev drush cr
   ```

5. **Test:**
   - Go to `/admin/cc-soccer/league/add`
   - Form should show your fields
   - Create a test league
   - Verify it saves

6. **Commit:**
   ```bash
   git add web/modules/custom/cc_soccer/src/Entity/League.php
   git commit -m "Implement League entity fields"
   git push
   ```

### Repeat for Each Component

This pattern works for everything:
1. Open file
2. Read TODO
3. Implement
4. Test
5. Commit

---

## Development Resources

### Drupal Documentation

- **Entity API:** https://www.drupal.org/docs/drupal-apis/entity-api
- **Form API:** https://www.drupal.org/docs/drupal-apis/form-api
- **Services:** https://www.drupal.org/docs/drupal-apis/services-and-dependency-injection
- **Commerce:** https://docs.drupalcommerce.org/

### Your Documentation

- **Architecture:** `/mnt/user-data/outputs/REQUIREMENTS_TO_ARCHITECTURE.md`
  - Complete scenarios and business logic
  - Entity relationships
  - Service responsibilities
  
- **Requirements:** Your original requirements document
  - User stories
  - Feature list

- **Module README:** `web/modules/custom/cc_soccer/README.md`
  - Module overview
  - Feature list

### Debugging Tools

```bash
# Watch logs in real-time
ddev drush watchdog:tail

# Clear cache (do this often!)
ddev drush cr

# Rebuild registry
ddev drush cc drush

# Check module status
ddev drush pml | grep soccer

# Run updates
ddev drush updb -y

# Export config
ddev drush cex -y

# SSH into container
ddev ssh
```

---

## Working with Andrew

### Collaboration Strategy

Since you've created this scaffold in Git:

1. **Andrew clones repo:**
   ```bash
   git clone [your-repo-url]
   cd ccsoccer-d11
   ddev start
   ```

2. **You work on different files:**
   - You: Work on League entity
   - Andrew: Work on Season entity
   - Minimal conflicts!

3. **Regular commits:**
   - Commit often
   - Push to branches
   - Merge via pull requests

4. **Communication:**
   - "I'm working on RegistrationService"
   - "Season entity is done, ready to test"
   - Update each other on progress

---

## Testing as You Build

### Manual Testing

For each feature:

1. **Create test data:**
   - Create leagues
   - Create seasons
   - Create test users

2. **Test workflows:**
   - Try to register
   - Try to cancel
   - Try to generate roster

3. **Check database:**
   ```bash
   ddev drush sql-cli
   SELECT * FROM season;
   ```

4. **Check logs:**
   ```bash
   ddev drush watchdog:show
   ```

### Automated Testing (Later)

Once core features work, add PHPUnit tests:

```php
// tests/src/Unit/RegistrationServiceTest.php
class RegistrationServiceTest extends UnitTestCase {
  public function testCanRegister() {
    // Test registration validation logic
  }
}
```

Run tests:
```bash
ddev exec phpunit web/modules/custom/cc_soccer/tests/
```

---

## Common Issues & Solutions

### "Class not found"

**Cause:** Cache needs clearing  
**Solution:**
```bash
ddev drush cr
```

### "Entity type not found"

**Cause:** Entity not fully defined or registered  
**Solution:**
1. Check entity annotation
2. Clear cache
3. Rebuild entity definitions: `ddev drush entup`

### "Permission denied"

**Cause:** Permission not granted to role  
**Solution:**
1. Go to `/admin/people/permissions`
2. Grant permission to appropriate role

### Routes not working

**Cause:** Routing file not recognized  
**Solution:**
1. Clear cache
2. Rebuild router: `ddev drush router:rebuild`

---

## Summary

### You Now Have:

✅ Complete module structure  
✅ All files organized  
✅ Detailed TODO comments  
✅ Architecture documentation  
✅ Clear build order  
✅ Ready to start coding  

### Next Steps:

1. ✅ Module is installed
2. ✅ Committed to Git
3. 📝 Start with Phase 1: Build League entity
4. 📝 Test it works
5. 📝 Move to Season entity
6. 📝 Continue incrementally

### Remember:

- **Don't rush** - Build one piece at a time
- **Test often** - After each entity/service
- **Commit frequently** - Small, focused commits
- **Read the docs** - Architecture doc has all the answers
- **Ask questions** - Better to clarify than guess

---

## Getting Help

### If you get stuck:

1. **Check the architecture doc** - Has scenarios and logic
2. **Check Drupal.org** - Entity/Form API docs
3. **Check module README** - Overview and features
4. **Ask Claude** - I can help with specific implementation questions

---

**You're all set! Start with the League entity and build from there. Good luck!** 🚀