# Centrex HR Reports API Documentation

This document outlines the endpoints, accepted parameters, and response structures for the newly implemented HR Reports APIs. All requests require a valid Authentication Token in the headers.

---

## 1. Permanent & Daily Wages Salary Report

**Endpoint:** `GET /report_salary_type.php`

**Description:** Returns the total generated salary amount grouped by employment job type (Permanent vs Daily). Includes table data and formatted chart data for the frontend.

**Parameters:**
*   `month` (String) - Optional. e.g., "08". Defaults to current month.
*   `year` (String) - Optional. e.g., "2026". Defaults to current year.
*   `shop_id` (String) - Optional. Limits the report to a specific shop/entity.

**Example Response:**
```json
{
  "status": "success",
  "message": "Report generated successfully",
  "data": {
    "filters": {
      "month": "08",
      "year": "2026",
      "shop_id": ""
    },
    "table_data": [
      {
        "job_type": "PERMANENT",
        "total_salary": 450000
      },
      {
        "job_type": "DAILY WAGES",
        "total_salary": 85000
      }
    ],
    "chart_data": {
      "labels": ["PERMANENT", "DAILY WAGES"],
      "datasets": [
        {
          "data": [450000, 85000]
        }
      ]
    }
  }
}
```

---

## 2. Department-wise Salary Cost Report

**Endpoint:** `GET /report_dept_cost.php`

**Description:** Provides the total salary cost broken down by individual operational departments.

**Parameters:**
*   `month` (String) - Optional. e.g., "08". Defaults to current month.
*   `year` (String) - Optional. e.g., "2026". Defaults to current year.
*   `shop_id` (String) - Optional. Limits the report to a specific shop/entity.

**Example Response:**
```json
{
  "status": "success",
  "message": "Report generated successfully",
  "data": {
    "filters": {
      "month": "08",
      "year": "2026",
      "shop_id": ""
    },
    "table_data": [
      {
        "department": "PRODUCTION",
        "total_salary": 1200000
      },
      {
        "department": "SALES",
        "total_salary": 340000
      }
    ],
    "chart_data": {
      "labels": ["PRODUCTION", "SALES"],
      "datasets": [
        {
          "data": [1200000, 340000]
        }
      ]
    }
  }
}
```

---

## 3. Department-wise Headcount Report

**Endpoint:** `GET /report_dept_headcount.php`

**Description:** Returns the total physical workforce headcount breakdown across each department.

**Parameters:**
*   `shop_id` (String) - Optional. Filter by specific branch or division.
*   `status` (String) - Optional. "A" for Active, "R" for Resigned. Defaults to "A".

**Example Response:**
```json
{
  "status": "success",
  "message": "Report generated successfully",
  "data": {
    "filters": {
      "status": "A",
      "shop_id": "POS-0003"
    },
    "table_data": [
      {
        "department": "PRODUCTION",
        "headcount": 140
      },
      {
        "department": "SALES",
        "headcount": 25
      }
    ],
    "chart_data": {
      "labels": ["PRODUCTION", "SALES"],
      "datasets": [
        {
          "data": [140, 25]
        }
      ]
    }
  }
}
```

---

## 4. Monthly HR Summary / Management Report

**Endpoint:** `GET /report_hr_summary.php`

**Description:** Generates top-level KPI metrics summing up broader business vitals for the specified month. Excludes graphical mappings as it targets basic numerical info cards (KPIs).

**Parameters:**
*   `month` (String) - Optional. e.g., "08". Defaults to current month.
*   `year` (String) - Optional. e.g., "2026". Defaults to current year.
*   `shop_id` (String) - Optional. Limits the report to a specific shop/entity.

**Example Response:**
```json
{
  "status": "success",
  "message": "HR Summary Generated",
  "data": {
    "filters": {
      "month": "08",
      "year": "2026",
      "shop_id": ""
    },
    "kpi_cards": {
      "total_headcount": 284,
      "total_salary_paid": 5200000,
      "new_joiners": 12,
      "total_leavers": 3
    }
  }
}
```