Santhosh Janardhanan
b8262bbcaf
Archive three completed changes to archive/: - api-resource-standard (70 tasks, 14 resource classes) - capacity-expert-mode (68 tasks, expert mode planning grid) - enhanced-allocation (62 tasks, planning fidelity + reporting) Sync all delta specs to main specs/: - api-resource-standard: API response standardization - capacity-expert-mode: Expert mode toggle, grid, KPIs, batch API - resource-allocation: Month execution comparison, bulk, untracked - untracked-allocation: Null team member support - allocation-indicators: Variance indicators (red/amber/neutral) - monthly-budget: Explicit project-month planning All changes verified and tested (157 tests passing).
131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# 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) |
|