# Reporting API Contract

## Overview

The Reporting API provides aggregated resource planning and execution data for management analysis. It supports three view types (did/is/will) inferred from date ranges.

## Endpoint

```
GET /api/reports/allocations
```

## Authentication

Requires Bearer token authentication.

## Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `start_date` | string (YYYY-MM-DD) | Yes | Start of reporting period |
| `end_date` | string (YYYY-MM-DD) | Yes | End of reporting period |
| `project_ids[]` | array of UUIDs | No | Filter by specific projects |
| `member_ids[]` | array of UUIDs | No | Filter by specific team members |

## View Types

The `view_type` is inferred from the date range:

| View Type | Date Range | Description |
|-----------|------------|-------------|
| `did` | All dates in past months | Historical execution analysis |
| `is` | Includes current month | Active planning vs execution |
| `will` | All dates in future months | Forecast and capacity planning |

## Response Structure

```json
{
  "period": {
    "start": "2026-01-01",
    "end": "2026-03-31"
  },
  "view_type": "will",
  "projects": [
    {
      "id": "uuid",
      "code": "PROJ-001",
      "title": "Project Name",
      "approved_estimate": 3000.0,
      "lifecycle_status": "MATCH",
      "plan_sum": 2600.0,
      "period_planned": 2600.0,
      "period_allocated": 2800.0,
      "period_variance": 200.0,
      "period_status": "OVER",
      "months": [
        {
          "month": "2026-01",
          "planned_hours": 1200.0,
          "is_blank": false,
          "allocated_hours": 1300.0,
          "variance": 100.0,
          "status": "OVER"
        }
      ]
    }
  ],
  "members": [
    {
      "id": "uuid",
      "name": "Team Member",
      "period_allocated": 400.0,
      "projects": [
        {
          "project_id": "uuid",
          "project_code": "PROJ-001",
          "project_title": "Project Name",
          "total_hours": 400.0
        }
      ]
    }
  ],
  "aggregates": {
    "total_planned": 2600.0,
    "total_allocated": 2800.0,
    "total_variance": 200.0,
    "status": "OVER"
  }
}
```

## Status Values

| Status | Meaning | Visual |
|--------|---------|--------|
| `OVER` | Allocated > Planned/Capacity | 🔴 Red |
| `UNDER` | Allocated < Planned/Capacity | 🟡 Amber |
| `MATCH` | Allocated = Planned/Capacity | 🟢 Green/Neutral |

## Blank vs Zero Distinction

- **Blank plan** (`is_blank: true`): No plan entry exists for the month
  - `planned_hours`: `null`
  - Used for variance: treated as `0`
  
- **Explicit zero** (`is_blank: false`, `planned_hours: 0`): Plan was explicitly set to zero
  - `planned_hours`: `0`
  - Distinct from blank for reporting accuracy

## Dependencies

This endpoint combines data from:

- `ProjectMonthPlan` - Monthly planning data
- `Allocation` - Resource allocations
- `Project` - Project metadata (approved_estimate)
- `TeamMember` - Team member capacity

Calculations use:
- `ReconciliationCalculator` - Lifecycle plan vs estimate
- `VarianceCalculator` - Period and monthly variances

## Error Responses

| Status | Condition |
|--------|-----------|
| 422 | Missing or invalid date parameters |
| 422 | `end_date` before `start_date` |
| 401 | Unauthorized (missing/invalid token) |