# ═══════════════════════════════════════════════════════════════
# PHASE 12: REPORTS & DASHBOARDS MODULE
# Module directory: /modules/reports/
# ═══════════════════════════════════════════════════════════════
# READ THE MASTER PROMPT FIRST.

## YOUR TABLES
report_definitions, report_parameters, report_templates, report_favorites,
report_generated, report_schedules, report_schedule_runs,
dashboard_widgets, dashboard_user_layouts

## DATABASE VIEWS (use these heavily)
vw_active_members, vw_pending_applications, vw_overdue_invoices,
vw_member_balance_summary, vw_member_family_overview, vw_subscription_renewal_status,
vw_active_freezes, vw_violation_summary, vw_complaint_dashboard,
vw_installment_overview, vw_daily_revenue, vw_expiring_cards,
vw_expiring_documents, vw_sport_class_summary, vw_today_access,
vw_waiting_list_status, vw_kpi_summary

## PAGES TO BUILD

### 1. Report Browser (`GET /reports`)
- Card grid of available reports grouped by category
- Search and filter by category
- Quick access to favorites

### 2. Report Viewer (`GET /reports/{id}`)
- Dynamic parameter form from report_parameters
- Execute report and display results in DataTable
- Chart visualization (if chart_type defined)
- Export buttons: PDF, Excel, CSV, Print
- Save as favorite with current parameters

### 3. Built-in Reports (create report_definitions for each):
  - **Members Report**: Member listing with flexible filters (type, status, join date, city, nationality, age range)
  - **Financial Summary**: Revenue by period, by fee type, by payment method
  - **Outstanding Balances**: Members with outstanding > 0, aging analysis
  - **Subscription Status**: Active/expired/expiring breakdown
  - **Violation Report**: Violations by type, severity, period
  - **Complaint Analysis**: Complaints by category, SLA compliance rate
  - **Attendance Report**: Facility usage, sport class attendance
  - **Guest Pass Report**: Guest passes issued by period
  - **Collection Report**: Payments collected by cashier, by method, by period
  - **Membership Type Distribution**: Members per type with trends
  - **Dependent Report**: Dependents by type, age analysis
  - **Expiring Documents/Cards**: Items expiring in configurable window
  - **Freeze Report**: Freezes by reason, by period
  - **Sport Enrollment**: Class enrollments, fill rates
  - **Board Resolutions**: Resolutions by status, implementation rate

### 4. Report Scheduler (`GET /reports/schedules`)
- CRUD for report_schedules
- Frequency configuration
- Recipient management
- Run history

### 5. Custom Report Builder (`GET /reports/custom`)
- Table/view selector
- Column selector
- Filter builder (AND/OR conditions)
- Grouping selector
- Sorting configuration
- Preview and save as report definition

### 6. Dashboard Configuration (`GET /reports/dashboard-config`)
- Manage personal dashboard layout
- Widget selection and arrangement (drag-drop or grid config)
- Widget catalog from all modules

### 7. KPI Dashboard (`GET /reports/kpis`)
- Use vw_kpi_summary
- Large number cards with sparkline trends
- Comparison to previous period

## BUSINESS LOGIC
- Report queries generated dynamically from report_definitions and parameters
- Results cached temporarily for export after initial query
- Report generation logged in report_generated
- Scheduled reports run at configured times
- Custom reports validated for SQL injection prevention (whitelist approach)

## DASHBOARD WIDGETS
1. **KPI Summary** — Key numbers from vw_kpi_summary
2. **Revenue Chart** — 30-day trend line
3. **Member Growth** — Monthly new members chart

## PERMISSIONS
reports.view, reports.schedule, reports.custom