Files

Santhosh Janardhanan b8262bbcaf docs(openspec): archive completed changes and sync main specs

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).

2026-03-08 19:13:28 -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