Files

Santhosh Janardhanan b7bbfb45c0 docs(openspec): add reporting API contract documentation

Add comprehensive API documentation for the reporting endpoint:
- Request/response structure
- View type inference (did/is/will)
- Blank vs explicit zero semantics
- Status values and error responses

Related to enhanced-allocation change.

2026-03-08 18:22:27 -04:00

3.3 KiB

Raw Blame History

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

{
  "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)

3.3 KiB Raw Blame History