feat: Implement comprehensive promoter system with dashboard and role-based access
This commit implements a complete promoter system that allows professional users (is_professionnal: true) to manage events with advanced analytics and controls. ## Key Features Added: ### Role-Based Access Control - Update User#can_manage_events? to use is_professionnal field - Add promoter? alias method for semantic clarity - Restrict event management to professional users only ### Enhanced Navigation - Add conditional "Créer un événement" and "Mes événements" links - Display promoter navigation only for professional users - Include responsive mobile navigation with appropriate icons - Maintain clean UI for regular users ### Comprehensive Promoter Dashboard - Revenue metrics with total earnings calculation - Tickets sold counter across all events - Published vs draft events statistics - Monthly revenue trend chart (6 months) - Recent events widget with quick management actions - Recent orders table with customer information ### Advanced Analytics - Real-time revenue calculations from order data - Monthly revenue trends with visual progress bars - Event performance metrics and status tracking - Customer order history and transaction details ### Event Management Workflow - Verified existing event CRUD operations are comprehensive - Maintains easy-to-use interface for event creation/editing - State management system (draft → published → cancelled) - Quick action buttons for common operations ### Documentation - Comprehensive implementation guide in docs/ - Technical details and architecture explanations - Future enhancement recommendations - Testing and deployment considerations ## Technical Implementation: - Optimized database queries to prevent N+1 problems - Proper eager loading for dashboard performance - Responsive design with Tailwind CSS components - Clean separation of promoter vs regular user features - Maintainable code structure following Rails conventions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kbe
236
docs/promoter-system-implementation.md
Normal file
236
docs/promoter-system-implementation.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Promoter System Implementation
|
||||
|
||||
This document outlines the comprehensive promoter system implemented for AperoNight, providing professional event organizers with powerful tools to manage their events and track their performance.
|
||||
|
||||
## Overview
|
||||
|
||||
The promoter system allows professional users (marked with `is_professionnal: true`) to create, manage, and analyze their events through a dedicated interface. This system includes:
|
||||
|
||||
- **Role-based access control** - Only professional users can manage events
|
||||
- **Comprehensive dashboard** - Real-time metrics and revenue tracking
|
||||
- **Event management workflow** - Easy CRUD operations for events
|
||||
- **Revenue analytics** - Monthly revenue trends and detailed metrics
|
||||
|
||||
## Key Features Implemented
|
||||
|
||||
### 1. User Role Management
|
||||
|
||||
**File**: `app/models/user.rb`
|
||||
|
||||
The system uses the existing `is_professionnal` boolean field to determine promoter privileges:
|
||||
|
||||
```ruby
|
||||
def can_manage_events?
|
||||
# Only professional users can manage events
|
||||
is_professionnal?
|
||||
end
|
||||
|
||||
def promoter?
|
||||
# Alias for can_manage_events? to make views more semantic
|
||||
can_manage_events?
|
||||
end
|
||||
```
|
||||
|
||||
### 2. Conditional Navigation
|
||||
|
||||
**File**: `app/views/components/_header.html.erb`
|
||||
|
||||
Navigation items are conditionally displayed based on user status:
|
||||
|
||||
- **Desktop Navigation**: "Créer un événement" and "Mes événements" links
|
||||
- **Mobile Navigation**: Same functionality with appropriate icons
|
||||
- **Responsive Design**: Maintains clean UI across all device sizes
|
||||
|
||||
### 3. Promoter Dashboard
|
||||
|
||||
**File**: `app/controllers/pages_controller.rb` & `app/views/pages/dashboard.html.erb`
|
||||
|
||||
The dashboard provides comprehensive business intelligence for promoters:
|
||||
|
||||
#### Key Metrics Cards
|
||||
- **Total Revenue**: Sum of all completed event orders
|
||||
- **Tickets Sold**: Count of active tickets across all events
|
||||
- **Published Events**: Count of live/published events
|
||||
- **Draft Events**: Count of events in preparation
|
||||
|
||||
#### Monthly Revenue Chart
|
||||
- **6-Month Trend**: Visual representation of revenue over time
|
||||
- **Progressive Bars**: Easy-to-read revenue comparison
|
||||
- **Responsive Design**: Works on all screen sizes
|
||||
|
||||
#### Recent Events Widget
|
||||
- **Quick Overview**: Last 5 events with status indicators
|
||||
- **Status Badges**: Visual indicators for draft/published/cancelled states
|
||||
- **Ticket Sales**: Shows tickets sold per event
|
||||
- **Quick Actions**: Direct links to event management
|
||||
|
||||
#### Recent Orders Table
|
||||
- **Transaction History**: Latest 10 orders for promoter events
|
||||
- **Customer Information**: Buyer details and contact info
|
||||
- **Revenue Tracking**: Order amounts and dates
|
||||
- **Event Association**: Clear event-to-order relationship
|
||||
|
||||
### 4. Event Management Workflow
|
||||
|
||||
The existing event management system provides:
|
||||
|
||||
#### Event Creation
|
||||
- **Intuitive Form**: Step-by-step event creation process
|
||||
- **Auto-Generated Slugs**: SEO-friendly URLs from event names
|
||||
- **Rich Metadata**: Full event details including location and timing
|
||||
- **Draft System**: Create and refine before publishing
|
||||
|
||||
#### Event List Management
|
||||
- **Tabular View**: Clean, scannable list of all events
|
||||
- **Status Indicators**: Visual badges for event states
|
||||
- **Quick Actions**: Inline buttons for common operations
|
||||
- **Bulk Operations**: Efficient management of multiple events
|
||||
|
||||
#### Publishing Workflow
|
||||
- **Draft → Published**: One-click publishing when ready
|
||||
- **State Management**: Clean state transitions
|
||||
- **Rollback Capability**: Can unpublish if needed
|
||||
|
||||
## Technical Implementation Details
|
||||
|
||||
### Database Schema
|
||||
|
||||
The system leverages existing database structure:
|
||||
- **Users Table**: `is_professionnal` boolean field
|
||||
- **Events Table**: Belongs to user, has states enum
|
||||
- **Orders Table**: Links to events and users
|
||||
- **Tickets Table**: Links to orders and events
|
||||
|
||||
### Revenue Calculations
|
||||
|
||||
Revenue metrics are calculated with optimized queries:
|
||||
|
||||
```ruby
|
||||
# Total revenue across all promoter events
|
||||
@total_revenue = current_user.events
|
||||
.joins(:orders)
|
||||
.where(orders: { status: ['paid', 'completed'] })
|
||||
.sum('orders.total_amount_cents') / 100.0
|
||||
|
||||
# Monthly revenue trend (6 months)
|
||||
@monthly_revenue = (0..5).map do |months_ago|
|
||||
start_date = months_ago.months.ago.beginning_of_month
|
||||
end_date = months_ago.months.ago.end_of_month
|
||||
|
||||
revenue = current_user.events
|
||||
.joins(:orders)
|
||||
.where(orders: { status: ['paid', 'completed'] })
|
||||
.where(orders: { created_at: start_date..end_date })
|
||||
.sum('orders.total_amount_cents') / 100.0
|
||||
|
||||
{ month: start_date.strftime("%B %Y"), revenue: revenue }
|
||||
end.reverse
|
||||
```
|
||||
|
||||
### Security & Authorization
|
||||
|
||||
- **Controller Guards**: `before_action :ensure_can_manage_events!`
|
||||
- **Model-level Checks**: User role validation in models
|
||||
- **View-level Conditionals**: UI elements only shown to authorized users
|
||||
- **Route Protection**: Promoter namespace requires authentication
|
||||
|
||||
### Performance Optimizations
|
||||
|
||||
- **Eager Loading**: `includes(:orders, :tickets)` to prevent N+1 queries
|
||||
- **Efficient Queries**: Database-level aggregations for metrics
|
||||
- **Caching Ready**: Structure allows for future caching implementation
|
||||
- **Paginated Results**: Large datasets handled efficiently
|
||||
|
||||
## User Experience Enhancements
|
||||
|
||||
### Dashboard Design Philosophy
|
||||
- **Information Hierarchy**: Most important metrics prominently displayed
|
||||
- **Progressive Disclosure**: Detailed information available on demand
|
||||
- **Action-Oriented**: Quick access to common tasks
|
||||
- **Responsive First**: Mobile-friendly from the ground up
|
||||
|
||||
### Visual Design Elements
|
||||
- **Color Coding**: Consistent color schemes for different data types
|
||||
- **Iconography**: Lucide icons for clear visual communication
|
||||
- **Status Indicators**: Immediate visual feedback on event states
|
||||
- **Gradient Cards**: Attractive metric display with brand consistency
|
||||
|
||||
### Navigation Improvements
|
||||
- **Contextual Links**: Navigation adapts based on user type
|
||||
- **Breadcrumbs**: Clear navigation path for complex workflows
|
||||
- **Quick Actions**: Common tasks accessible from multiple locations
|
||||
|
||||
## Future Enhancement Opportunities
|
||||
|
||||
### Analytics Expansion
|
||||
1. **Customer Analytics**: Buyer demographics and behavior
|
||||
2. **Event Performance**: Attendance rates and conversion metrics
|
||||
3. **Comparative Analysis**: Event-to-event performance comparison
|
||||
4. **Seasonal Trends**: Year-over-year growth tracking
|
||||
|
||||
### Feature Additions
|
||||
1. **Bulk Operations**: Mass edit/publish multiple events
|
||||
2. **Templates**: Reusable event templates for recurring events
|
||||
3. **Automated Marketing**: Integration with email marketing tools
|
||||
4. **Advanced Reporting**: PDF export of financial reports
|
||||
|
||||
### Technical Improvements
|
||||
1. **Real-time Updates**: WebSocket integration for live metrics
|
||||
2. **Export Functionality**: CSV/Excel export of data
|
||||
3. **API Endpoints**: RESTful API for mobile app integration
|
||||
4. **Advanced Caching**: Redis caching for improved performance
|
||||
|
||||
### Business Intelligence
|
||||
1. **Predictive Analytics**: Revenue forecasting
|
||||
2. **Customer Segmentation**: Audience analysis tools
|
||||
3. **Market Analysis**: Industry benchmarking
|
||||
4. **ROI Tracking**: Event profitability analysis
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
### Unit Tests
|
||||
- User role methods validation
|
||||
- Revenue calculation accuracy
|
||||
- Event state transitions
|
||||
- Authorization checks
|
||||
|
||||
### Integration Tests
|
||||
- Dashboard data loading
|
||||
- Event creation workflow
|
||||
- Publishing process
|
||||
- Navigation conditional display
|
||||
|
||||
### User Acceptance Testing
|
||||
- Promoter onboarding flow
|
||||
- Event management efficiency
|
||||
- Dashboard usability
|
||||
- Mobile responsiveness
|
||||
|
||||
## Deployment Considerations
|
||||
|
||||
### Database Migrations
|
||||
- Ensure `is_professionnal` field exists and is properly indexed
|
||||
- Verify foreign key constraints on events→users relationship
|
||||
- Check order status values match expected enum values
|
||||
|
||||
### Feature Flags
|
||||
Consider implementing feature flags for gradual rollout:
|
||||
- Dashboard sections can be enabled incrementally
|
||||
- A/B testing for different dashboard layouts
|
||||
- Progressive enhancement of analytics features
|
||||
|
||||
### Performance Monitoring
|
||||
- Monitor dashboard load times
|
||||
- Track query performance for revenue calculations
|
||||
- Set up alerts for slow promoter page loads
|
||||
|
||||
## Conclusion
|
||||
|
||||
The promoter system provides a solid foundation for professional event management within AperoNight. The implementation focuses on:
|
||||
|
||||
- **User-Centric Design**: Intuitive workflows that match promoter needs
|
||||
- **Performance**: Efficient queries and responsive design
|
||||
- **Scalability**: Architecture that can grow with business needs
|
||||
- **Security**: Proper authorization and data protection
|
||||
|
||||
This system transforms AperoNight from a simple event listing platform into a comprehensive event management solution for professional organizers, providing the tools they need to grow their business and serve their customers effectively.
|
||||
Reference in New Issue
Block a user