# Dispo v2 Implementation Plan — Overview

**Date:** 2026-03-13
**Status:** Draft
**Source:** `MandatoryDispoCategories_V3.xlsx` + `20260309_Bi-Weekly_Chargeability_Reporting_Content_Production_V0.943_4Hartmut.xlsx`

## Goal

Extend Nexus to support chargeability reporting with country-specific SAH (Standard Available Hours), FTE-based capacity, organizational hierarchy, utilization categories, client/WBS management, and a native chargeability report replacing the current Excel workflow.

## Plan Documents

| #   | Plan                   | File                                                             | Core Deliverable                                                                       |
| --- | ---------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| 1   | Country, SAH & FTE     | [plan-country-sah-fte.md](plan-country-sah-fte.md)               | Country/MetroCity models, SAH calculator, FTE-scaled daily hours                       |
| 2   | Org Unit Hierarchy     | [plan-org-unit-hierarchy.md](plan-org-unit-hierarchy.md)         | 3-level OrgUnit tree (L5→L6→L7), resource assignment, admin UI                         |
| 3   | Utilization Categories | [plan-utilization-categories.md](plan-utilization-categories.md) | UtilizationCategory model on projects (Chg, BD, MD&I, M&O, PD&R, Absence)              |
| 4   | Client & WBS           | [plan-client-wbs-model.md](plan-client-wbs-model.md)             | Client tree (Master→Entity), project-client linking                                    |
| 5   | Resource Extensions    | [plan-resource-extensions.md](plan-resource-extensions.md)       | EID attributes, ManagementLevel, ResourceType, Chg Responsibility, derivation rules    |
| 6   | Chargeability Report   | [plan-chargeability-report.md](plan-chargeability-report.md)     | Native report replacing Excel, forecast from assignments + SAH, SAP import for actuals |

## Key Design Decisions

### SAH as capacity basis

Standard Available Hours = `(dailyHours * FTE) * (workingDays - publicHolidays - absence)`.
Country drives daily hours (8h most, 9h India, variable Spain). FTE reduces proportionally.

### Resource Type derivation (Option A)

Store only 5 base types in DB: Employee, Freelancer, Apprentice, Intern, Student.
Derive reporting types at query time:

- **Production Studios** = `chgResponsibility = true` AND country = Germany
- **Near&Offshore** = country NOT Germany AND type = Employee/Freelancer
- **Accenture** = `chgResponsibility = false`
- **Long-term absence** = derived from absence system

Derivation rules are configurable in admin (which countries map to which reporting type).

### Utilization on projects, not allocations

Each project carries a utilization category (Chg, BD, MD&I, etc.). Hours assigned to a project inherit its category for reporting. Unassigned hours = SAH minus all categorized hours.

### Forecast chargeability = derived metric

`forecastChg = hours on Chg projects / SAH`. No manual chargeability entry — it comes from what Nexus already knows about assignments.

## Dependency Order

```
1. Country/SAH ─────────────────┐
2. OrgUnit Hierarchy ───────────┤
3. Utilization Categories ──────┼──→ 5. Resource Extensions ──→ 6. Chargeability Report
4. Client/WBS ──────────────────┘
```

Plans 1-4 are independent and can be implemented in parallel.
Plan 5 (Resource Extensions) depends on 1-4 for the FK targets.
Plan 6 (Chargeability Report) depends on all others.

## New Prisma Models Summary

| Model                   | Purpose                                             |
| ----------------------- | --------------------------------------------------- |
| `Country`               | Country with daily working hours and schedule rules |
| `MetroCity`             | City within a country (for public holidays)         |
| `OrgUnit`               | Self-referencing 3-level org hierarchy              |
| `UtilizationCategory`   | Project classification for hour bucketing           |
| `Client`                | Self-referencing client hierarchy (Master → Entity) |
| `ManagementLevelGroup`  | Career level grouping with target chargeability %   |
| `ManagementLevel`       | Specific level within a group                       |
| `ChargeabilitySnapshot` | Imported SAP actuals for historical reporting       |

## Resource Model Changes Summary

New fields on `Resource`:

- `enterpriseId` (String, unique)
- `countryId` → Country
- `metroCityId` → MetroCity
- `orgUnitId` → OrgUnit (L7)
- `managementLevelGroupId` → ManagementLevelGroup
- `managementLevelId` → ManagementLevel
- `resourceType` (enum: EMPLOYEE, FREELANCER, APPRENTICE, INTERN, STUDENT)
- `chgResponsibility` (Boolean, default true)
- `rolledOff` (Boolean)
- `departed` (Boolean)
- `clientUnitId` → Client (primary client for reporting)
- `lcrCents`, `ucrCents` (Int, placeholder for cost rates)

## Project Model Changes Summary

New fields on `Project`:

- `utilizationCategoryId` → UtilizationCategory
- `clientId` → Client (WBS Client Name)

## Open Questions

1. **Resource Type derivation rules**: The country→reporting-type mapping should be admin-configurable. Exact admin UI TBD.
2. **Win Probability**: The Dispo file mentions it "should contain the value from MMS". Is this relevant for Nexus? If so, it's a field on Project.
3. **LCR/UCR**: Cost rate definitions are not yet available. Placeholder fields are included.
4. **SAP import format**: What format do SAP period exports come in? CSV? API? Needs clarification for the import mechanism.
5. **FTE history**: Currently single `fte` field. Monthly FTE tracking may be needed if contract changes happen mid-month.
