# 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 CapaKraken 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 CapaKraken 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 CapaKraken? 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.