# Advanced Reports Module - Customer Recognition System

## Overview
The Advanced Reports module includes a comprehensive Customer Recognition System that allows businesses to track, rank, and reward their top customers based on sales performance and engagement activities.

## System Architecture

### Customer Recognition System
- **Controller**: `CustomerRecognitionController.php`
- **Views**: `customer-recognition/index.blade.php`
- **Models**: `CustomerAward.php`, `CustomerEngagement.php`, `AwardPeriod.php`
- **Utils**: `CustomerRecognitionUtil.php`

## Key Features

### 1. Customer Ranking & Scoring
- **Period-based Rankings**: Weekly, Monthly, Yearly rankings
- **Scoring Algorithm**: Combines sales total, engagement points, and transaction frequency
- **Ranking Display**: Visual ranking with rank suffixes (1st, 2nd, 3rd, etc.)

### 2. Award System
- **Manual Awards**: Custom gift descriptions with monetary values
- **Catalog Awards**: Product-based awards with automatic stock deduction
- **Quantity Support**: Award multiple units with proper stock management
- **Unaward Functionality**: Reverse awards and restore stock

### 3. Customer Engagement Tracking
- **Engagement Types**: YouTube Follow, Facebook Follow, Instagram Follow, Twitter Follow, Content Share, Reviews, Google Reviews, Customer Referrals
- **Platform Integration**: Platform-specific icons and colors
- **Verification System**: Notes and status tracking for each engagement
- **Points System**: Configurable points for different engagement types

### 4. Enhanced Customer Details Modal
- **Comprehensive Information**: Customer details, period performance, engagement summary
- **Purchase History**: Transaction details and summaries
- **Engagement Timeline**: Visual timeline of customer engagements
- **Print Functionality**: Professional printable customer reports

### 5. Data Tables Integration
- **Customer Rankings Table**: Server-side processing with filters
- **Customer Engagements Table**: Dedicated table for engagement data
- **Advanced Filters**: Period type, location, winner count, status filters
- **Export Functionality**: Data export capabilities

## Database Schema

### customer_awards
- Stores award information for customers
- Links to customers, award periods, and catalog items
- Tracks award status, quantity, and stock deduction

### customer_engagements  
- Records customer engagement activities
- Platform-specific data with verification status
- Points tracking and user attribution

### award_periods
- Manages ranking periods (weekly/monthly/yearly)
- Finalization status and winner counts

## Technical Implementation

### Stock Management
- Integrates with UltimatePOS stock system
- Uses `VariationLocationDetails` for stock tracking  
- Automatic stock deduction/restoration on award/unaward
- Quantity-aware stock operations

### Error Handling
- Comprehensive error logging and user feedback
- Detailed error messages for period finalization
- Graceful handling of stock and validation errors

### Security
- Permission-based access control (`customer_recognition.view`, `customer_recognition.manage`)
- CSRF protection on all form submissions
- Proper input validation and sanitization

## Configuration
- Business-specific settings through `CustomerRecognitionSetting`
- Configurable scoring weights and engagement points
- Period-based configuration options

## Routes
```php
// Customer Recognition System Routes
Route::prefix('customer-recognition')->group(function () {
    Route::get('/', 'CustomerRecognitionController@index');
    Route::get('/data', 'CustomerRecognitionController@getCustomerRecognitionData');
    Route::get('/engagements-data', 'CustomerRecognitionController@getEngagementsData');
    Route::get('/summary', 'CustomerRecognitionController@getSummary');
    Route::get('/details/{customerId}', 'CustomerRecognitionController@getCustomerDetails');
    Route::post('/finalize', 'CustomerRecognitionController@finalizePeriod');
    Route::post('/award', 'CustomerRecognitionController@awardCustomer');
    Route::post('/unaward', 'CustomerRecognitionController@unawardCustomer');
    Route::post('/record-engagement', 'CustomerRecognitionController@recordEngagement');
});
```

## Development Notes

### Recent Enhancements
- Fixed reference URL display in engagement table (HTML rendering issue)
- Enhanced customer details modal with engagement information
- Simplified and cleaned modal styling for better UX
- Added quantity support for awards with stock management
- Implemented comprehensive error handling for period finalization

### Code Quality
- Follows Laravel/UltimatePOS patterns and conventions  
- Clean separation of concerns between controllers, models, and views
- Comprehensive error handling and logging
- Responsive design with AdminLTE integration

### Testing & Validation
- Always run linting and type checking after code changes
- Validate stock operations in test environment
- Test award/unaward functionality thoroughly
- Verify engagement data display and filtering

## Customer Lifetime Value (CLV) Report

### Overview
The CLV Report provides comprehensive customer analytics including value segmentation, purchase frequency analysis, retention metrics, and churn prediction to help businesses understand and maximize customer value.

### Key Features

#### 1. Customer Value Segmentation
- **RFM Analysis**: Recency, Frequency, Monetary value-based segmentation
- **11 Customer Segments**: Champions, Loyal Customers, Potential Loyalists, New Customers, Promising, Need Attention, About to Sleep, At Risk, Cannot Lose Them, Hibernating, Lost
- **CLV Calculation**: Customer Lifetime Value scoring based on purchase history and frequency patterns
- **Visual Segmentation**: Interactive pie/bar charts showing customer distribution across segments

#### 2. Purchase Frequency Analysis
- **Frequency Segments**: One-time, Occasional (2-5), Regular (6-10), Frequent (11-20), Super Frequent (20+)
- **Repeat Customer Metrics**: Repeat rate, average purchase frequency, average order value
- **Interactive Visualization**: Doughnut/bar chart toggle for frequency distribution

#### 3. Customer Retention Metrics
- **Lifetime Analysis**: Average customer lifetime in days, purchases per customer
- **Cohort Analysis**: Monthly cohort-based retention tracking
- **Retention Periods**: 3-month, 6-month, and 12-month active customer counts
- **Performance Indicators**: Info-box widgets displaying key retention metrics

#### 4. Churn Prediction Analytics
- **Risk Assessment**: High, Medium, Low, and Active customer classification
- **Churn Scoring**: Behavioral pattern analysis for churn risk identification
- **Visual Indicators**: Doughnut chart and progress bars showing risk distribution
- **Predictive Metrics**: Average days since purchase, churn rate calculation

#### 5. Interactive Dashboard
- **Summary Cards**: Total customers, revenue, average CLV, at-risk customers
- **Top 10 Customers**: Visual cards showing highest CLV customers with rankings
- **Data Tables**: Detailed customer segmentation with server-side processing
- **Export Functionality**: CSV export with comprehensive customer analytics

### Technical Implementation

#### Controller: CustomerLifetimeValueController
- **Analytics Engine**: Comprehensive customer data analysis methods
- **Segmentation Logic**: Advanced RFM scoring with CLV enhancement
- **SQL Optimization**: Complex queries for customer behavior analysis
- **Export System**: CSV generation with detailed customer insights

#### Database Queries
- **Customer Segmentation**: Complex SQL with JOINs and aggregations
- **Retention Analysis**: Cohort-based analysis with time-series data
- **Churn Prediction**: Behavioral pattern analysis using recency and frequency

#### View Components
- **Chart.js Integration**: Interactive visualizations with toggle functionality
- **DataTables**: Server-side processing for large customer datasets
- **Responsive Design**: Mobile-optimized cards and charts
- **AdminLTE Styling**: Consistent UI with existing theme

### Routes
```php
// Customer Lifetime Value (CLV) Report Routes
Route::prefix('customer-lifetime-value')->group(function () {
    Route::get('/', 'CustomerLifetimeValueController@index');
    Route::get('/data', 'CustomerLifetimeValueController@getCustomerLifetimeValueData');
    Route::get('/segmentation', 'CustomerLifetimeValueController@getCustomerSegmentationData');
    Route::post('/export', 'CustomerLifetimeValueController@export');
});
```

### Customer Segmentation Algorithm

The system uses an enhanced RFM (Recency, Frequency, Monetary) model with CLV scoring:

1. **Recency Score** (1-5): Based on days since last purchase
   - 5: ≤30 days, 4: ≤60 days, 3: ≤90 days, 2: ≤180 days, 1: >180 days

2. **Frequency Score** (1-5): Based on total purchase count
   - 5: ≥10 purchases, 4: ≥7, 3: ≥4, 2: ≥2, 1: 1 purchase

3. **Monetary Score** (1-5): Based on CLV calculation
   - 5: ≥$10,000, 4: ≥$5,000, 3: ≥$2,000, 2: ≥$500, 1: <$500

4. **CLV Calculation**: Improved formula with realistic constraints:
   - Single purchase customers: Total Spent (conservative estimate)
   - Same-day multiple purchases: Total Spent × 2 (modest growth assumption)  
   - Multi-period customers: Average Order Value × Projected Annual Purchases (capped at 12)

### Permissions
- `AdvancedReports.customer_lifetime_value`: Access to CLV analysis and reports

## Product Category Performance Report

### Overview
The Product Category Performance report provides comprehensive analysis of category contribution, cross-selling opportunities, margin analysis, and growth trends to help businesses optimize their product portfolio and maximize profitability.

### Key Features

#### 1. Category Contribution Analysis
- **Sales & Profit Contribution**: Percentage breakdown of each category's contribution to total sales and profit
- **Performance Metrics**: Revenue, profit margin, transaction count, unique products per category
- **Interactive Visualization**: Toggleable pie/bar charts showing category contribution distribution
- **Ranking System**: Top performing categories with medal indicators

#### 2. Cross-Selling Opportunities
- **Market Basket Analysis**: Categories frequently bought together with confidence scores
- **Association Rules**: Co-occurrence patterns and confidence percentages for category pairs
- **Customer Affinity**: Category preference analysis based on customer behavior
- **Recommendation Engine**: Top cross-selling opportunities with average basket values

#### 3. Margin Analysis by Category
- **Profitability Metrics**: Gross profit, margin percentage, ROI calculation for each category
- **Margin Benchmarking**: High-margin vs low-margin category identification
- **Consistency Analysis**: Margin variance and stability metrics
- **Performance Scoring**: Combined profitability and volume performance scores

#### 4. Growth Trends Analysis
- **Monthly Growth Tracking**: Period-over-period growth rates for each category
- **Trend Classification**: Growing, declining, or stable category identification
- **Visual Trend Charts**: Interactive line charts showing growth patterns over time
- **Growth Analysis**: Average monthly growth rates and trend direction indicators

#### 5. Advanced Analytics Features
- **Seasonal Patterns**: Monthly, daily, and hourly sales pattern analysis
- **Inventory Turnover**: Category-wise turnover ratios, stock velocity, and days-to-sell metrics
- **Peak Performance Analysis**: Peak month, day, and hour identification
- **Efficiency Scoring**: Stock efficiency and turnover performance ratings

#### 6. Interactive Dashboard
- **Overview Cards**: Total categories, sales, profit, and average margin summaries
- **Multi-Chart Views**: Category contribution, margin analysis, growth trends, and seasonal patterns
- **Filter System**: Date range, location, category, and brand filtering options
- **Export Functionality**: Comprehensive CSV export with all analytics data

### Technical Implementation

#### Controller: ProductCategoryController
- **Analytics Engine**: 8 comprehensive analysis methods covering all aspects of category performance
- **Cross-Selling Logic**: Advanced market basket analysis with confidence and lift calculations
- **Growth Algorithms**: Period-over-period growth rate calculations with trend classification
- **Export System**: Multi-data source CSV generation with formatted metrics

#### Database Queries
- **Category Contribution**: Complex JOINs with aggregations across transactions, products, and categories
- **Market Basket Analysis**: Self-joining transaction analysis for co-occurrence patterns
- **Seasonal Analysis**: Time-based grouping with monthly, daily, and hourly breakdowns
- **Inventory Turnover**: Stock level analysis combined with sales velocity calculations

#### View Components
- **Chart.js Integration**: Interactive visualizations with toggleable chart types
- **Responsive Cards**: Category performance cards with ranking and medal systems
- **Advanced Filtering**: Multi-select dropdowns with Select2 integration
- **Real-time Analytics**: AJAX-powered data updates without page refresh

### Routes
```php
// Product Category Performance Report Routes
Route::prefix('product-category')->group(function () {
    Route::get('/', 'ProductCategoryController@index');
    Route::get('/analytics', 'ProductCategoryController@getAnalytics');
    Route::get('/export', 'ProductCategoryController@export');
});
```

### Analytics Methods

1. **getCategoryContribution**: Sales and profit contribution analysis with percentage calculations
2. **getCrossSellingOpportunities**: Market basket analysis and category affinity scoring
3. **getMarginAnalysByCategory**: Profitability analysis with benchmarking and performance scoring
4. **getCategoryGrowthTrends**: Monthly growth tracking with trend classification
5. **getSeasonalPatterns**: Temporal analysis across monthly, daily, and hourly patterns
6. **getInventoryTurnoverByCategory**: Stock efficiency and turnover ratio analysis
7. **getTopPerformingCategories**: Revenue-based category ranking and performance metrics
8. **getCategoryComparison**: Comprehensive category comparison with multiple KPIs

### Permissions
- `AdvancedReports.product_category_performance`: Access to category performance analysis and reports
- `AdvancedReports.export`: CSV export functionality for comprehensive analytics data

### Key Metrics Tracked
- **Revenue & Profitability**: Sales, profit, margin percentage, contribution ratios
- **Customer Engagement**: Unique customers, transactions, average transaction value
- **Inventory Management**: Turnover ratios, stock velocity, days-to-sell metrics
- **Growth Performance**: Monthly growth rates, trend directions, seasonal patterns
- **Cross-Selling Potential**: Co-occurrence rates, confidence scores, basket values

## Supplier Performance Report

### Overview
The Supplier Performance Report provides comprehensive analysis of supplier delivery performance, quality assessment, payment term compliance, and risk analysis to optimize supplier relationships and supply chain management.

### Key Features

#### 1. Delivery Performance Metrics
- **On-Time Delivery Tracking**: Percentage of orders delivered on schedule
- **Average Delivery Days**: Mean delivery time for each supplier
- **Delivery Reliability**: Consistency scoring based on delivery performance
- **Late Delivery Analysis**: Identification of chronic late delivery patterns

#### 2. Quality Assessment Analytics
- **Quality Rating System**: Comprehensive quality scoring for suppliers
- **Defect Rate Tracking**: Monitoring of product quality issues and returns
- **Quality Trend Analysis**: Historical quality performance patterns
- **Quality Consistency Metrics**: Variance in quality delivery

#### 3. Payment Term Compliance
- **Payment Terms Adherence**: Compliance with agreed payment schedules
- **Payment Performance Scoring**: Scoring based on payment history
- **Payment Risk Assessment**: Early warning system for payment issues
- **Compliance Trend Analysis**: Historical payment compliance patterns

#### 4. Supplier Risk Analysis
- **Risk Score Calculation**: Multi-dimensional risk assessment
- **Performance Risk Indicators**: Early warning systems for performance issues
- **Financial Risk Assessment**: Supplier financial stability analysis
- **Risk Mitigation Recommendations**: Actionable insights for risk management

#### 5. Interactive Dashboard
- **Overview Cards**: Total suppliers, spend, compliance rates, and delivery metrics
- **Performance Visualizations**: Charts showing delivery, quality, and payment performance
- **Supplier Rankings**: Comprehensive ranking system with performance scores
- **Risk Distribution**: Visual risk assessment across supplier portfolio

### Technical Implementation

#### Controller: SupplierPerformanceController
- **Analytics Engine**: 4 comprehensive analysis methods covering all aspects of supplier performance
- **Performance Scoring**: Advanced algorithms for delivery, quality, payment, and risk assessment
- **Trend Analysis**: Historical performance tracking with pattern recognition
- **Export System**: Comprehensive CSV export with detailed supplier analytics

#### Database Queries
- **Performance Analysis**: Complex JOINs across purchases, suppliers, and quality metrics
- **Compliance Tracking**: Payment term adherence analysis with time-series data
- **Risk Assessment**: Multi-factor analysis for supplier risk evaluation
- **Delivery Metrics**: Delivery performance calculation with reliability scoring

#### View Components
- **Chart.js Integration**: Interactive visualizations with performance metrics
- **Responsive Cards**: Supplier performance cards with comprehensive metrics
- **Advanced Filtering**: Date range, supplier, and performance threshold filtering
- **Real-time Analytics**: AJAX-powered data updates without page refresh

### Routes
```php
// Supplier Performance Report Routes
Route::prefix('supplier-performance')->group(function () {
    Route::get('/', 'SupplierPerformanceController@index')->name('advancedreports.supplier-performance.index');
    Route::get('/data', 'SupplierPerformanceController@getSupplierPerformanceData')->name('advancedreports.supplier-performance.data');
    Route::get('/export', 'SupplierPerformanceController@export')->name('advancedreports.supplier-performance.export');
});
```

### Analytics Methods

1. **getDeliveryPerformance**: On-time delivery and delivery time analysis
2. **getQualityAssessment**: Quality rating and defect rate analysis  
3. **getPaymentCompliance**: Payment term adherence and compliance scoring
4. **getSupplierRiskAnalysis**: Comprehensive risk assessment and scoring

### Permissions
- `AdvancedReports.supplier_performance`: Access to supplier performance analysis and reports

### Key Metrics Tracked
- **Delivery Performance**: On-time delivery %, average delivery days, reliability scores
- **Quality Assessment**: Quality ratings, defect rates, consistency metrics
- **Payment Compliance**: Payment term adherence, compliance scores, risk indicators
- **Risk Analysis**: Multi-dimensional risk scoring, performance indicators

### Performance Insights
- **Automated Recommendations**: AI-powered supplier improvement suggestions
- **Risk Alerts**: Early warning system for supplier performance issues
- **Trend Analysis**: Historical performance patterns and predictions
- **Benchmarking**: Supplier performance comparison and ranking

### Future Enhancements
- Service Staff Recognition System (planned)
- Machine Learning-enhanced churn prediction
- Customer journey mapping
- Automated retention campaigns
- Advanced cohort analysis with custom periods
- Mobile app integration
- Advanced notification systems
- AI-powered category optimization recommendations
- Predictive inventory management
- Dynamic pricing optimization based on category performance
- Real-time supplier performance monitoring
- Automated supplier risk alerts
- Supplier performance benchmarking against industry standards

## Warranty & Service Report

### Overview
The Warranty & Service Report provides comprehensive tracking and analysis of product warranties, service requests, customer support metrics, and post-sale service performance to optimize customer satisfaction and service operations.

### Key Features

#### 1. Product Warranty Tracking
- **Warranty Status Monitoring**: Real-time tracking of active, expired, expiring, and claimed warranties
- **Coverage Analytics**: Warranty coverage percentage across all products sold
- **Expiring Warranty Alerts**: Proactive identification of warranties expiring within 30 days
- **Warranty Type Analysis**: Different warranty types and their performance metrics

#### 2. Service Request Analysis  
- **Request Type Classification**: Warranty, repair, maintenance, replacement, and refund requests
- **Priority Distribution**: High, medium, and low priority request analysis
- **Status Tracking**: Open, in progress, resolved, and closed request monitoring
- **Resolution Time Analysis**: Average resolution time and efficiency metrics

#### 3. Customer Support Metrics
- **Response Time Tracking**: First response time and resolution time analytics
- **SLA Performance**: Service level agreement compliance monitoring
- **Customer Satisfaction**: Rating analysis and feedback tracking
- **Staff Performance**: Individual support staff performance metrics

#### 4. Post-Sale Service Performance
- **Service by Product Age**: Analysis of service requests based on product lifecycle
- **Monthly Service Trends**: Historical service request patterns and trends
- **Cost Analysis**: Service cost ratio compared to original sales value
- **Resolution Efficiency**: Service resolution rates and effectiveness

#### 5. Warranty Claims Analysis
- **Claims by Product**: Product-specific warranty claim patterns
- **Claims by Reason**: Analysis of claim reasons and frequencies
- **Claim Value Tracking**: Financial impact of warranty claims
- **Average Days to Claim**: Time between purchase and warranty claim

#### 6. Interactive Dashboard
- **Overview Cards**: Total products sold, warranty coverage, service requests, resolution rate
- **Visual Analytics**: Charts for warranty status distribution, service trends, and claims analysis
- **Performance Insights**: Automated recommendations and key performance indicators
- **Real-time Monitoring**: Live updates of warranty and service metrics

### Technical Implementation

#### Controller: WarrantyServiceController
- **Analytics Engine**: 8 comprehensive analysis methods covering all warranty and service aspects
- **Warranty Tracking**: Real-time warranty status monitoring with expiration alerts
- **Service Analysis**: Request type, priority, and status-based analytics
- **Support Metrics**: Response time, resolution time, and satisfaction tracking

#### Database Queries
- **Warranty Analysis**: Complex JOINs across transactions, sell lines, and warranty tables
- **Service Requests**: Multi-table analysis with status and priority grouping
- **Support Metrics**: Time-based calculations for response and resolution analytics
- **Claims Analysis**: Warranty claim patterns and financial impact assessment

#### View Components
- **Chart.js Integration**: Interactive visualizations for warranty and service data
- **Responsive Cards**: Warranty status cards with color-coded alerts
- **Advanced Filtering**: Date range, customer, warranty status, and service status filters
- **Real-time Dashboard**: AJAX-powered updates without page refresh

### Routes
```php
// Warranty & Service Report Routes  
Route::prefix('warranty-service')->group(function () {
    Route::get('/', 'WarrantyServiceController@index')->name('advancedreports.warranty-service.index');
    Route::get('/data', 'WarrantyServiceController@getWarrantyServiceData')->name('advancedreports.warranty-service.data');
    Route::get('/export', 'WarrantyServiceController@export')->name('advancedreports.warranty-service.export');
});
```

### Analytics Methods

1. **getWarrantyServiceOverview**: Comprehensive overview metrics and KPIs
2. **getProductWarrantyTracking**: Real-time warranty status and expiration monitoring
3. **getServiceRequestAnalysis**: Service request classification and trend analysis
4. **getCustomerSupportMetrics**: Response times, resolution rates, and satisfaction
5. **getPostSaleServicePerformance**: Post-sale service efficiency and cost analysis
6. **getWarrantyClaims**: Warranty claim patterns and financial impact
7. **getServiceTrends**: Historical service request trends and patterns
8. **getWarrantyServiceInsights**: Automated insights and recommendations

### Permissions
- `AdvancedReports.warranty_service`: Access to warranty and service analysis reports

### Key Metrics Tracked
- **Warranty Coverage**: Percentage of products with warranty protection
- **Service Efficiency**: Response time, resolution time, and resolution rate
- **Customer Satisfaction**: Rating scores and feedback analysis
- **Cost Management**: Service cost ratio and warranty claim impact
- **Proactive Monitoring**: Expiring warranty alerts and service recommendations

### Business Value
- **Customer Retention**: Improved service quality and warranty management
- **Cost Control**: Optimized service costs and warranty claim management
- **Operational Efficiency**: Streamlined service processes and staff performance
- **Proactive Service**: Early warranty renewal and service planning

### Service Insights
- **Automated Recommendations**: AI-powered service improvement suggestions
- **Performance Alerts**: Early warning system for service issues
- **Trend Analysis**: Historical service patterns and predictive insights
- **Quality Monitoring**: Product quality assessment through warranty claims