CapaKraken/plan.md

Nearshore-Ratio Indikator — Plan

Anforderungsanalyse

Was: Ein Nearshore/Offshore-Ratio Indikator pro Projekt, der zeigt wieviel % der gebuchten Ressourcen Standort Deutschland vs. andere Standorte haben.

Kernkonzept:

• Onshore = Resource hat countryId → Country mit Code "DE" (Deutschland)
• Offshore/Nearshore = Resource hat countryId → Country mit Code != "DE" (oder kein Country gesetzt)
• Shoring-Ratio = (Offshore-Stunden / Gesamt-Stunden) * 100
• Threshold = Default 55%, pro Projekt aenderbar
• Anzeige = Farbiger Indikator (gruen < Threshold, rot >= Threshold)

Datenquelle: Assignments eines Projekts → Resource.countryId → Country.code

---

Betroffene Pakete & Dateien

Paket	Dateien	Art der Aenderung
packages/db	prisma/schema.prisma	edit — shoringThreshold Int? auf Project
packages/engine	src/allocation/shoring-ratio.ts	create — Pure Berechnung
packages/engine	src/__tests__/shoring-ratio.test.ts	create — Unit Tests
packages/api	src/router/project.ts	edit — getShoringRatio Query + Threshold im Update
packages/api	src/router/assistant-tools.ts	edit — get_shoring_ratio AI Tool
apps/web	src/components/projects/ShoringIndicator.tsx	create — Visueller Indikator
apps/web	src/app/(app)/projects/[id]/page.tsx	edit — Indikator auf Detail-Seite
apps/web	src/app/(app)/projects/ProjectsClient.tsx	edit — Indikator-Spalte in Projektliste
apps/web	src/components/projects/ProjectModal.tsx	edit — Threshold-Feld im Edit
apps/web	src/components/dashboard/widgets/ProjectHealthWidget.tsx	edit — Optional: Shoring in Health-Score

---

Task-Liste

Phase 1: Schema + Engine (sequenziell)

• Task 1: Schema erweitern → packages/db/prisma/schema.prisma

  • shoringThreshold Int? @default(55) auf dem Project Model
  • Repraesntiert den kritischen Shoring-Prozentsatz (Default 55%)
  • prisma db push

• Task 2: Pure Shoring-Ratio Berechnung → packages/engine/src/allocation/shoring-ratio.ts

  interface ShoringInput {
    resourceId: string;
    countryCode: string | null; // "DE", "ES", "IN", etc.
    hoursPerDay: number;
    workingDays: number; // oder totalHours direkt
  }
  
  interface ShoringResult {
    totalHours: number;
    onshoreHours: number;     // countryCode === "DE"
    offshoreHours: number;    // countryCode !== "DE"
    offshoreRatio: number;    // 0-100 (%)
    onshoreRatio: number;     // 0-100 (%)
    threshold: number;        // Default 55
    isAboveThreshold: boolean;
    byCountry: Record<string, { hours: number; pct: number; resourceCount: number }>;
  }
  
  export function calculateShoringRatio(
    assignments: ShoringInput[],
    threshold?: number, // Default 55
    onshoreCountryCode?: string, // Default "DE"
  ): ShoringResult
  

• Task 3: Unit Tests → packages/engine/src/__tests__/shoring-ratio.test.ts

  • 100% Deutsche Ressourcen → offshoreRatio = 0, isAboveThreshold = false
  • 100% Offshore → offshoreRatio = 100, isAboveThreshold = true
  • 50/50 Mix → offshoreRatio = 50, isAboveThreshold = false (< 55)
  • 60/40 Mix → offshoreRatio = 60, isAboveThreshold = true (> 55)
  • Custom Threshold (30%) → 40% Offshore = above threshold
  • Leere Assignments → offshoreRatio = 0
  • Resource ohne Country → zaehlt als Offshore

• Task 4: Export → packages/engine/src/allocation/index.ts

Phase 2: API + UI (parallel)

• Task 5: API Query → packages/api/src/router/project.ts

  • getShoringRatio Query (protectedProcedure):
    • Input: { projectId: string }
    • Laedt Assignments mit Resource.country
    • Ruft calculateShoringRatio() auf
    • Returns: ShoringResult
  • update Mutation erweitern: shoringThreshold im Input akzeptieren
  • getById erweitern: shoringThreshold im Response zurueckgeben

• Task 6: Visueller Indikator → ShoringIndicator.tsx

  • Kompakte Anzeige:

    [====DE 45%====|==ES 30%==|IN 25%] ⚠ 55% offshore (Limit: 55%)
    

  • Stacked horizontal bar: Laender-Segmente farbig
  • Gruen/Gelb/Rot Badge je nach Threshold
  • Gruen: < Threshold - 10pp
  • Gelb: Threshold - 10pp bis Threshold
  • Rot: >= Threshold
  • Tooltip: Aufschluesselung nach Land
  • Props: projectId: string (laedt Daten selbst via tRPC)

• Task 7: Threshold im ProjectModal → ProjectModal.tsx

  • Neues Feld: "Max Offshore %" (Number Input, 0-100, Default 55)
  • Unter "Budget" oder als eigene Section "Shoring"
  • Label: "Maximum Offshore/Nearshore Ratio (%)"
  • Hinweis: "Alert when offshore staffing exceeds this percentage"

• Task 8: Indikator auf Projekt-Detail-Seite → projects/[id]/page.tsx

  • <ShoringIndicator projectId={id} /> neben dem Budget-Status
  • Oder als eigene Karte unter den Budget-Karten

• Task 9: Indikator-Spalte in Projektliste → ProjectsClient.tsx

  • Neue Spalte "Shoring" mit Mini-Indikator (nur Badge gruen/gelb/rot + %)
  • InfoTooltip: "Offshore staffing ratio vs project threshold"

Phase 3: AI + Dashboard (parallel)

• Task 10: AI Assistant Tool → assistant-tools.ts

  • get_shoring_ratio Tool:
    • Input: { projectId: string }
    • Returns: menschenlesbare Aufschluesselung
    • "Project X: 45% onshore (DE), 55% offshore (ES 30%, IN 25%). ⚠ Above 55% threshold."

• Task 11: Optional: Dashboard Widget oder ProjectHealth Integration

  • Shoring-Warnung in ProjectHealthWidget einbauen
  • Oder neues Mini-Widget "Shoring Alerts" (Projekte ueber Threshold)

---

Abhaengigkeiten

Task 1 (Schema) → Task 2 (Engine) → Task 3 (Tests) → Task 4 (Export)
Task 4 → Task 5 (API)
Task 5 → Task 6 + Task 7 + Task 8 + Task 9 (alle parallel)
Task 5 → Task 10 (AI Tool)
Task 5 → Task 11 (Dashboard)

• Tasks 6-9 vollstaendig parallel (verschiedene Dateien)
• Tasks 10-11 parallel zu Tasks 6-9

---

Akzeptanzkriterien

• pnpm test:unit laeuft gruen (inkl. neue shoring-ratio Tests)
• pnpm --filter @planarchy/web exec tsc --noEmit — keine neuen Errors
• Projekt-Detail: Shoring-Indikator sichtbar mit Laender-Aufschluesselung
• Projektliste: Shoring-Badge-Spalte (gruen/gelb/rot)
• Projekt-Edit: Threshold aenderbar (Default 55%)
• AI Assistant: "Wie ist der Shoring-Mix bei Projekt X?" liefert Antwort
• Farben: Gruen < 45%, Gelb 45-55%, Rot >= 55% (bei Default-Threshold)
• Resource ohne Country: Zaehlt als Offshore
• Projekt ohne Assignments: Zeigt "No data" statt Fehler

---

Risiken & offene Fragen

Risiken

• Country-Daten unvollstaendig: Viele Resources haben moeglicherweise kein countryId gesetzt → Mitigation: Zaehlt als Offshore + Warning "X resources have no country assigned"
• Stunden vs Headcount: Soll nach Stunden oder Koepfen gemessen werden? → Vorschlag: Stunden (gewichtet), da ein 50%-FTE weniger zaehlt als ein 100%-FTE

Offene Fragen

1. Nur "DE" als Onshore? Oder soll der Onshore-Laendercode konfigurierbar sein? → Vorschlag: Default "DE", aber konfigurierbar pro Projekt
2. Welche Assignment-Status zaehlen? Nur CONFIRMED? Auch PROPOSED? → Vorschlag: CONFIRMED + PROPOSED (beide relevant fuer Planung)
3. Soll der Indikator auch in der Timeline sichtbar sein? → Vorschlag: Erst mal nur Projektliste + Detail-Seite