apskel-pos-backend/ANALYTICS_API.md

# Analytics API Documentation

This document describes the analytics APIs implemented for the POS system, providing insights into sales, payment methods, products, and overall business performance.

## Overview

The analytics APIs provide comprehensive business intelligence for POS operations, including:

- **Payment Method Analytics**: Track totals for each payment method by date
- **Sales Analytics**: Monitor sales performance over time
- **Product Analytics**: Analyze product performance and revenue
- **Dashboard Analytics**: Overview of key business metrics

## Authentication

All analytics endpoints require authentication and admin/manager privileges. Include the JWT token in the Authorization header:

```
Authorization: Bearer <your-jwt-token>
```

## Base URL

```
GET /api/v1/analytics/{endpoint}
```

## Endpoints

### 1. Payment Method Analytics

**Endpoint:** `GET /api/v1/analytics/payment-methods`

**Description:** Get payment method totals for a given date range. This is the primary endpoint for tracking payment method performance.

**Query Parameters:**
- `organization_id` (required): UUID of the organization
- `outlet_id` (optional): UUID of specific outlet to filter by
- `date_from` (required): Start date (ISO 8601 format: YYYY-MM-DD)
- `date_to` (required): End date (ISO 8601 format: YYYY-MM-DD)
- `group_by` (optional): Grouping interval - "day", "hour", "week", "month" (default: "day")

**Example Request:**
```bash
curl -X GET "http://localhost:8080/api/v1/analytics/payment-methods?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31" \
  -H "Authorization: Bearer <your-jwt-token>"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "group_by": "day",
    "summary": {
      "total_amount": 15000.00,
      "total_orders": 150,
      "total_payments": 180,
      "average_order_value": 100.00
    },
    "data": [
      {
        "payment_method_id": "456e7890-e89b-12d3-a456-426614174001",
        "payment_method_name": "Cash",
        "payment_method_type": "cash",
        "total_amount": 8000.00,
        "order_count": 80,
        "payment_count": 80,
        "percentage": 53.33
      },
      {
        "payment_method_id": "789e0123-e89b-12d3-a456-426614174002",
        "payment_method_name": "Credit Card",
        "payment_method_type": "card",
        "total_amount": 7000.00,
        "order_count": 70,
        "payment_count": 100,
        "percentage": 46.67
      }
    ]
  }
}
```

### 2. Sales Analytics

**Endpoint:** `GET /api/v1/analytics/sales`

**Description:** Get sales performance data over time.

**Query Parameters:**
- `organization_id` (required): UUID of the organization
- `outlet_id` (optional): UUID of specific outlet to filter by
- `date_from` (required): Start date (ISO 8601 format: YYYY-MM-DD)
- `date_to` (required): End date (ISO 8601 format: YYYY-MM-DD)
- `group_by` (optional): Grouping interval - "day", "hour", "week", "month" (default: "day")

**Example Request:**
```bash
curl -X GET "http://localhost:8080/api/v1/analytics/sales?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31&group_by=day" \
  -H "Authorization: Bearer <your-jwt-token>"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "group_by": "day",
    "summary": {
      "total_sales": 15000.00,
      "total_orders": 150,
      "total_items": 450,
      "average_order_value": 100.00,
      "total_tax": 1500.00,
      "total_discount": 500.00,
      "net_sales": 13000.00
    },
    "data": [
      {
        "date": "2024-01-01T00:00:00Z",
        "sales": 500.00,
        "orders": 5,
        "items": 15,
        "tax": 50.00,
        "discount": 20.00,
        "net_sales": 430.00
      }
    ]
  }
}
```

### 3. Product Analytics

**Endpoint:** `GET /api/v1/analytics/products`

**Description:** Get top-performing products by revenue.

**Query Parameters:**
- `organization_id` (required): UUID of the organization
- `outlet_id` (optional): UUID of specific outlet to filter by
- `date_from` (required): Start date (ISO 8601 format: YYYY-MM-DD)
- `date_to` (required): End date (ISO 8601 format: YYYY-MM-DD)
- `limit` (optional): Number of products to return (1-100, default: 10)

**Example Request:**
```bash
curl -X GET "http://localhost:8080/api/v1/analytics/products?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31&limit=5" \
  -H "Authorization: Bearer <your-jwt-token>"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "data": [
      {
        "product_id": "abc123-e89b-12d3-a456-426614174000",
        "product_name": "Coffee Latte",
        "category_id": "cat123-e89b-12d3-a456-426614174000",
        "category_name": "Beverages",
        "quantity_sold": 100,
        "revenue": 2500.00,
        "average_price": 25.00,
        "order_count": 80
      }
    ]
  }
}
```

### 4. Dashboard Analytics

**Endpoint:** `GET /api/v1/analytics/dashboard`

**Description:** Get comprehensive dashboard overview with key metrics.

**Query Parameters:**
- `organization_id` (required): UUID of the organization
- `outlet_id` (optional): UUID of specific outlet to filter by
- `date_from` (required): Start date (ISO 8601 format: YYYY-MM-DD)
- `date_to` (required): End date (ISO 8601 format: YYYY-MM-DD)

**Example Request:**
```bash
curl -X GET "http://localhost:8080/api/v1/analytics/dashboard?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31" \
  -H "Authorization: Bearer <your-jwt-token>"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "overview": {
      "total_sales": 15000.00,
      "total_orders": 150,
      "average_order_value": 100.00,
      "total_customers": 120,
      "voided_orders": 5,
      "refunded_orders": 3
    },
    "top_products": [...],
    "payment_methods": [...],
    "recent_sales": [...]
  }
}
```

## Error Responses

All endpoints return consistent error responses:

```json
{
  "success": false,
  "error": "error_type",
  "message": "Error description"
}
```

Common error types:
- `invalid_request`: Invalid query parameters
- `validation_failed`: Request validation failed
- `internal_error`: Server-side error
- `unauthorized`: Authentication required

## Date Format

All date parameters should be in ISO 8601 format: `YYYY-MM-DD`

Examples:
- `2024-01-01` (January 1, 2024)
- `2024-12-31` (December 31, 2024)

## Filtering

- **Organization-level**: All analytics are scoped to a specific organization
- **Outlet-level**: Optional filtering by specific outlet
- **Date range**: Required date range for all analytics queries
- **Time grouping**: Flexible grouping by hour, day, week, or month

## Performance Considerations

- Analytics queries are optimized for read performance
- Large date ranges may take longer to process
- Consider using appropriate date ranges for optimal performance
- Results are cached where possible for better response times

## Use Cases

### Payment Method Analysis
- Track which payment methods are most popular
- Monitor payment method trends over time
- Identify payment method preferences by outlet
- Calculate payment method percentages for reporting

### Sales Performance
- Monitor daily/weekly/monthly sales trends
- Track order volumes and average order values
- Analyze tax and discount patterns
- Compare sales performance across outlets

### Product Performance
- Identify top-selling products
- Analyze product revenue and profitability
- Track product category performance
- Monitor product order frequency

### Business Intelligence
- Dashboard overview for management
- Key performance indicators (KPIs)
- Trend analysis and forecasting
- Operational insights for decision making