apskel-pos-backend/PROFIT_LOSS_ANALYTICS_API.md

# Profit/Loss Analytics API

This document describes the Profit/Loss Analytics API that provides comprehensive financial analysis for the POS system, including revenue, costs, and profitability metrics.

## Overview

The Profit/Loss Analytics API allows you to:
- Analyze profit and loss performance over time periods
- Track gross profit and net profit margins
- View product-wise profitability
- Monitor cost vs revenue trends
- Calculate profitability ratios

## Authentication

All analytics endpoints require authentication and admin/manager permissions.

## Endpoints

### Get Profit/Loss Analytics

**Endpoint:** `GET /api/v1/analytics/profit-loss`

**Description:** Retrieves comprehensive profit and loss analytics data including summary metrics, time-series data, and product profitability analysis.

**Query Parameters:**
- `outlet_id` (UUID, optional) - Filter by specific outlet
- `date_from` (string, required) - Start date in DD-MM-YYYY format
- `date_to` (string, required) - End date in DD-MM-YYYY format  
- `group_by` (string, optional) - Time grouping: `hour`, `day`, `week`, `month` (default: `day`)

**Example Request:**
```bash
curl -X GET "http://localhost:8080/api/v1/analytics/profit-loss?date_from=01-12-2023&date_to=31-12-2023&group_by=day" \
  -H "Authorization: Bearer <token>" \
  -H "Organization-ID: <org-id>"
```

**Example Response:**
```json
{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": "123e4567-e89b-12d3-a456-426614174001",
    "date_from": "2023-12-01T00:00:00Z",
    "date_to": "2023-12-31T23:59:59Z",
    "group_by": "day",
    "summary": {
      "total_revenue": 125000.00,
      "total_cost": 75000.00,
      "gross_profit": 50000.00,
      "gross_profit_margin": 40.00,
      "total_tax": 12500.00,
      "total_discount": 2500.00,
      "net_profit": 35000.00,
      "net_profit_margin": 28.00,
      "total_orders": 1250,
      "average_profit": 28.00,
      "profitability_ratio": 66.67
    },
    "data": [
      {
        "date": "2023-12-01T00:00:00Z",
        "revenue": 4032.26,
        "cost": 2419.35,
        "gross_profit": 1612.91,
        "gross_profit_margin": 40.00,
        "tax": 403.23,
        "discount": 80.65,
        "net_profit": 1129.03,
        "net_profit_margin": 28.00,
        "orders": 40
      },
      {
        "date": "2023-12-02T00:00:00Z",
        "revenue": 3750.00,
        "cost": 2250.00,
        "gross_profit": 1500.00,
        "gross_profit_margin": 40.00,
        "tax": 375.00,
        "discount": 75.00,
        "net_profit": 1050.00,
        "net_profit_margin": 28.00,
        "orders": 35
      }
    ],
    "product_data": [
      {
        "product_id": "123e4567-e89b-12d3-a456-426614174002",
        "product_name": "Premium Burger",
        "category_id": "123e4567-e89b-12d3-a456-426614174003",
        "category_name": "Main Course",
        "quantity_sold": 150,
        "revenue": 2250.00,
        "cost": 900.00,
        "gross_profit": 1350.00,
        "gross_profit_margin": 60.00,
        "average_price": 15.00,
        "average_cost": 6.00,
        "profit_per_unit": 9.00
      },
      {
        "product_id": "123e4567-e89b-12d3-a456-426614174004",
        "product_name": "Caesar Salad",
        "category_id": "123e4567-e89b-12d3-a456-426614174005",
        "category_name": "Salads",
        "quantity_sold": 80,
        "revenue": 960.00,
        "cost": 384.00,
        "gross_profit": 576.00,
        "gross_profit_margin": 60.00,
        "average_price": 12.00,
        "average_cost": 4.80,
        "profit_per_unit": 7.20
      }
    ]
  }
}
```

## Response Structure

### Summary Object
- `total_revenue` - Total revenue for the period
- `total_cost` - Total cost of goods sold
- `gross_profit` - Revenue minus cost (total_revenue - total_cost)
- `gross_profit_margin` - Gross profit as percentage of revenue
- `total_tax` - Total tax collected
- `total_discount` - Total discounts given
- `net_profit` - Profit after taxes and discounts
- `net_profit_margin` - Net profit as percentage of revenue
- `total_orders` - Number of completed orders
- `average_profit` - Average profit per order
- `profitability_ratio` - Gross profit as percentage of total cost

### Time Series Data
The `data` array contains profit/loss metrics grouped by the specified time period:
- `date` - Date/time for the data point
- `revenue` - Revenue for the period
- `cost` - Cost for the period  
- `gross_profit` - Gross profit for the period
- `gross_profit_margin` - Gross profit margin percentage
- `tax` - Tax amount for the period
- `discount` - Discount amount for the period
- `net_profit` - Net profit for the period
- `net_profit_margin` - Net profit margin percentage
- `orders` - Number of orders in the period

### Product Profitability Data
The `product_data` array shows the top 20 most profitable products:
- `product_id` - Unique product identifier
- `product_name` - Product name
- `category_id` - Product category identifier
- `category_name` - Category name
- `quantity_sold` - Total units sold
- `revenue` - Total revenue from the product
- `cost` - Total cost for the product
- `gross_profit` - Total gross profit
- `gross_profit_margin` - Profit margin percentage
- `average_price` - Average selling price per unit
- `average_cost` - Average cost per unit
- `profit_per_unit` - Average profit per unit

## Key Metrics Explained

### Gross Profit Margin
Calculated as: `(Revenue - Cost) / Revenue × 100`
Shows the percentage of revenue retained after direct costs.

### Net Profit Margin  
Calculated as: `(Revenue - Cost - Discount) / Revenue × 100`
Shows the percentage of revenue retained after all direct costs and discounts.

### Profitability Ratio
Calculated as: `Gross Profit / Total Cost × 100`
Shows the return on investment for costs incurred.

## Use Cases

1. **Financial Performance Analysis** - Track overall profitability trends
2. **Product Performance** - Identify most and least profitable products
3. **Cost Management** - Monitor cost ratios and margins
4. **Pricing Strategy** - Analyze impact of pricing on profitability
5. **Inventory Decisions** - Focus on high-margin products
6. **Business Intelligence** - Make data-driven financial decisions

## Error Responses

The API returns standard error responses with appropriate HTTP status codes:

**400 Bad Request:**
```json
{
  "success": false,
  "errors": [
    {
      "code": "invalid_request",
      "entity": "AnalyticsHandler::GetProfitLossAnalytics", 
      "message": "date_from is required"
    }
  ]
}
```

**401 Unauthorized:**
```json
{
  "success": false,
  "errors": [
    {
      "code": "unauthorized",
      "entity": "AuthMiddleware",
      "message": "Invalid or missing authentication token"
    }
  ]
}
```

**403 Forbidden:**
```json
{
  "success": false,
  "errors": [
    {
      "code": "forbidden", 
      "entity": "AuthMiddleware",
      "message": "Admin or manager role required"
    }
  ]
}
```

## Notes

- Only completed and paid orders are included in profit/loss calculations
- Voided and refunded orders are excluded from the analysis
- Product profitability is sorted by gross profit in descending order
- Time series data is automatically filled for periods with no data (showing zero values)
- All monetary values are in the organization's base currency
- Margins and ratios are calculated as percentages with 2 decimal precision