# CC Soccer D11 - Reports Documentation

**Last Updated:** January 28, 2025

---

## Overview

CC Soccer includes several administrative reports for board members to manage operations, generate city payments, track jerseys, and prepare insurance documentation.

All reports are accessible via: **CC Soccer → Reports** in the admin menu.

---

## Report Catalog

### 1. Jersey Report ✅

**Purpose:** Track jersey distribution for each season  
**Access:** CC Soccer → Reports → Jersey Report  
**Path:** `/admin/jersey-report`  
**Type:** View with print CSS  
**Permissions:** Board Member, Administrator

**Features:**
- Multiselect season filter
- Grouped by league (Coed, Men's 35+)
- Shows: Player name, jersey size, league, season
- Size summary counts at top (e.g., "S: 5, M: 12, L: 18...")
- Print-friendly CSS for distribution day

**Implementation:**
- Database View: `jersey_report_view` (MySQL view for performance)
- Drupal View: `jersey_report_view` 
- Custom filter: `SeasonNameFilter` (multiselect dropdown)
- Print CSS: `web/modules/custom/ccsoccer/css/jersey-report.css`

**Usage:**
1. Select season(s) from dropdown
2. Apply filter
3. Review on screen or print to PDF
4. Use on jersey distribution day

---

### 2. City Payment Report ✅

**Purpose:** Calculate 30% revenue share paid to City of San Luis Obispo  
**Access:** CC Soccer → Reports → City Payment Report  
**Path:** `/admin/ccsoccer/reports/city-payment`  
**Type:** Custom PDF Service (TCPDF)  
**Permissions:** Board Member, Administrator

**Features:**
- Multiselect season filter
- Shows paid registrations only (excludes cancelled, comped, credited)
- Calculates 30% of total revenue per season
- Groups by league (Coed, Men's 35+)
- Tight PDF formatting (7pt font, fits 50+ rows per page)

**Implementation:**
- Form: `CityPaymentReportForm.php`
- Service: `CityReportService.php` (uses TCPDF)
- Route: `ccsoccer.reports.city_payment_form`

**Usage:**
1. Navigate to City Payment Report
2. Select season(s) to include
3. Click "Generate PDF Report"
4. PDF downloads with payment calculations
5. Submit to city finance department

**Calculation:**
```
Total Revenue = Σ (paid registrations × price per season)
City Payment = Total Revenue × 0.30
```

---

### 3. Tournament Deposits ✅

**Purpose:** Manage captain deposits (refund or forfeit)  
**Access:** CC Soccer → Reports → Tournament Deposits  
**Path:** `/admin/ccsoccer/reports/tournament-deposits`  
**Type:** View with action buttons  
**Permissions:** Board Member, Administrator

**Features:**
- Lists all tournament captain deposits
- Shows: Captain name, tournament, team name, deposit amount, status
- Actions: Refund deposit, Forfeit deposit
- Tracks deposit status (pending, refunded, forfeited)

**Implementation:**
- View: Queries registrations with `is_captain=TRUE` and `deposit_paid=TRUE`
- Forms: `TournamentDepositRefundForm.php`, `TournamentDepositForfeitForm.php`
- Integrates with Commerce for refund processing

**Usage:**
1. View all captain deposits
2. Click "Refund" to return deposit to captain
3. Click "Forfeit" to mark deposit as forfeited
4. System processes Commerce refund or marks forfeited

---

### 4. Insurance Report ✅

**Purpose:** Generate player roster for annual insurance submission  
**Access:** CC Soccer → Reports → Insurance Report  
**Path:** `/admin/ccsoccer/reports/insurance-report`  
**Type:** Custom PDF Service (TCPDF)  
**Permissions:** Board Member, Administrator

**Features:**
- Multiselect season filter
- Direct PDF generation (no web UI)
- Shows: Player name, date of birth, league, season, team
- One page per season (auto page breaks if needed)
- Sorted alphabetically by last name
- Tight formatting (7pt font, 1px padding)

**Implementation:**
- Form: `InsuranceReportForm.php`
- Service: `InsuranceReportService.php` (uses TCPDF)
- Route: `ccsoccer.reports.insurance_report`

**Usage:**
1. Navigate to Insurance Report
2. Select season(s) to include
3. Click "Generate PDF Report"
4. PDF downloads immediately
5. Submit to insurance company (annual requirement)

**Data included:**
- All paid/active registrations (excludes cancelled, expired, pending)
- Full name, date of birth (formatted: "January 27, 1990")
- League name, season name
- Team assignment (if roster generated)

---

## Report Architecture Patterns

### Pattern 1: View-Based Reports (Jersey Report)

**Use when:**
- Users need to browse/interact with data on screen
- Sorting, filtering, searching required
- Multiple display formats helpful (table, calendar, etc.)

**Components:**
- Drupal View configuration
- Optional: Database View (MySQL) for performance
- Custom filters/plugins as needed
- Print CSS for browser print-to-PDF

**Pros:**
- Quick to build via Views UI
- Easy to modify filters/fields
- No code for basic functionality

**Cons:**
- Limited control over output formatting
- Performance can be slower for complex queries

---

### Pattern 2: Custom Service Reports (City, Insurance)

**Use when:**
- Direct PDF download (no web UI needed)
- Tight formatting control required
- Complex calculations involved
- "Generate and send" workflow

**Components:**
- Form with filter selections
- Service class (uses TCPDF library)
- Route configuration
- Menu link

**Pros:**
- Complete control over PDF layout
- Tight formatting (7pt fonts, 1px padding)
- Can fit 50+ rows per page
- Professional output

**Cons:**
- More code to maintain
- Changes require PHP updates

---

## Creating New Reports

### Permissions Pattern (REQUIRED)

All new reports **must use custom permissions** (not hardcoded roles) for UI-configurable access control.

#### Step 1: Define Permission (Code)

**File:** `web/modules/custom/ccsoccer/ccsoccer.permissions.yml`

```yaml
access [report name] report:
  title: 'Access [Report Name] Report'
  description: 'Brief description of what report does'
```

**Example:**
```yaml
access player stats report:
  title: 'Access Player Stats Report'
  description: 'View player statistics and performance metrics'
```

---

#### Step 2A: Use Permission in Route (Custom Service Reports)

**File:** `web/modules/custom/ccsoccer/ccsoccer.routing.yml`

```yaml
ccsoccer.reports.[report_name]:
  path: '/admin/ccsoccer/reports/[report-name]'
  defaults:
    _form: '\Drupal\ccsoccer\Form\[ReportName]Form'
    _title: '[Report Title]'
  requirements:
    _permission: 'access [report name] report'  # ← Use permission, NOT _role
```

**Example:**
```yaml
ccsoccer.reports.player_stats:
  path: '/admin/ccsoccer/reports/player-stats'
  defaults:
    _form: '\Drupal\ccsoccer\Form\PlayerStatsReportForm'
    _title: 'Player Stats Report'
  requirements:
    _permission: 'access player stats report'
```

**❌ WRONG (don't do this):**
```yaml
  requirements:
    _role: 'board_member+administrator'  # ← Hardcoded, can't change in UI
```

---

#### Step 2B: Use Permission in View (View-Based Reports)

**Navigate to:** Structure → Views → [Your View] → Edit

1. Click **Access: None** (or whatever it currently shows)
2. Change to: **Permission**
3. Select permission: **Access [report name] report**
4. Click **Apply**
5. Save the view

**Or edit config YAML directly:**

**File:** `config/sync/views.view.[your_view].yml`

```yaml
access:
  type: perm
  options:
    perm: 'access [report name] report'
```

---

#### Step 3: Assign Permission (UI)

**Navigate to:** People → Permissions (`/admin/people/permissions`)

1. Scroll to **CC Soccer** section
2. Find your new permission: **Access [Report Name] Report**
3. Check boxes for appropriate roles:
   - ✅ **Board Member** (usually all reports)
   - ✅ **Slofriendly** (if appropriate)
   - **Administrator** gets all automatically
4. Click **Save permissions**

---

### Quick Reference Checklist

**For every new report:**

- [ ] ✅ Define permission in `ccsoccer.permissions.yml`
- [ ] ✅ Use `_permission:` in route (NOT `_role:`)
- [ ] ✅ OR set permission in Views UI (for View-based reports)
- [ ] ✅ Assign to roles via UI at `/admin/people/permissions`
- [ ] ✅ Test access with Board Member account
- [ ] ✅ Document in this file (REPORTS.md)

**Why this pattern?**
- ✅ Permissions configurable in UI (no code changes needed)
- ✅ Granular control per report
- ✅ Can create custom roles (e.g., "Reports Manager")
- ✅ Follows Drupal best practices
- ❌ Hardcoded roles require code deployment for permission changes

---

## Summary

**All required reports implemented:**
- ✅ Jersey Report - View-based with print CSS
- ✅ City Payment Report - Custom TCPDF service
- ✅ Tournament Deposits - View with action buttons
- ✅ Insurance Report - Custom TCPDF service

**Architecture patterns established:**
- View-based for interactive reports
- Custom service for direct PDF generation
- Database views for performance optimization
- Reusable season filter component

**System is production-ready for reporting needs.**