Specification: OMGT Order Priority Index

Status: APPROVED PILOT
Feature: Side-car Priority Engine
Target: OMGT Dashboard & WEP Access

1. Executive Summary

This specification defines the algorithm and architecture for the OMGT Priority Index, a calculated value that ranks orders based on urgency, workflow status, and business value. It serves as a Modernization Pilot (Strategy: "Side-car Logic"), introducing an isolated, asynchronous calculation engine alongside the legacy Monolith.

2. The Algorithm (P-Score)

The Priority Score (P-Score) is a floating-point value where a higher number indicates higher priority. It aggregates data from the "Workflow Bar", Timeline, and Financials.

Formula

P-Score = (Sum(ContextPenalty) * UrgencyMultiplier) + IntermediatePenalty + ValueBoost

2.1. Context Penalty (Workflow Status)

Derived from OrderTravelProductOMGT.GetStatusByContext(db). We only penalize "Active" contexts (e.g., Travel, Placement, Interview).

Status	Penalty Points	Description
ERROR	100	A blocking business rule (e.g., "Missing Ticket", "No Host Family").
IN_PROGRESS	10	Active work in progress.
OK / EMPTY	0	No attention needed.
DISABLED / N_A	0	Not relevant.

Justification: An ERROR (100) is 10x more important than standard work (10).

2.2. Urgency Multiplier (Departure Proximity)

Calculated based on DaysToDeparture. Amplifies existing penalties.

double days = (RealDepartureDate - DateTime.Now).TotalDays;

double urgencyMultiplier = 1.0;
if (days < 7) urgencyMultiplier = 3.0;       // < 1 week: CRITICAL
else if (days < 30) urgencyMultiplier = 2.0; // < 1 month: URGENT
else if (days < 60) urgencyMultiplier = 1.5; // < 2 months: HIGH
else if (days < 90) urgencyMultiplier = 1.2; // < 3 months: MEDIUM

Example: A generic Ticket Error (100pts) becomes a Critical Emergency (300pts) if departure is next week.

2.3. Intermediate Penalty (Deadline Proximity)

Captures tasks with deadlines independent of departure (e.g., Interview Date, Document Upload).

• Overdue ToDo Item: +50 pts per item.
• Imminent Deadline (<48h): +20 pts.

Justification: Ensures that "Early Bird" orders (Departure in 8 months) still get flagged if they miss an early deadline (e.g., Interview).

2.4. Value Boost (Business Value)

Uses OrderHeader.OREndUserPrice.

• Formula: ValueBoost = Price / 1000
• Example: €15,000 Order = +15 points.
• Justification: Acts as a tie-breaker. Between two identical emergencies, the higher value customer comes first.

3. Reference Scenarios

Scenario	Context States	Calculation Factors	Final Score
"The Silent Crisis" Departs: 45 days Value: €15k	Travel: OK Placement: IN_PROGRESS (10) Compliance: ERROR (100) ToDo: 2 Overdue (+100)	Penalty: 110 Mult: x1.5 Interm: +100 Value: +15	(110 * 1.5) + 100 + 15 = 280 Calculation: 165 (Wf) + 100 (Int) + 15 (Val)
"Last Minute Panic" Departs: 5 days Value: €2k	Travel: ERROR (100)	Penalty: 100 Mult: x3.0 Interm: 0 Value: +2	(100 * 3.0) + 2 = 302 Immediate Action
"Smooth Sailing" Departs: 20 days Value: €8k	Compliance: IN_PROGRESS (10)	Penalty: 10 Mult: x2.0 Interm: 0 Value: +8	(10 * 2.0) + 8 = 28 Low Priority

4. Technical Architecture

4.1. The Performance Challenge

The GetStatusByContext(db) method executes Deep Graph Traversals and N+1 queries. It cannot be used for sorting lists in real-time (O(N) * Cost > 10s for 500 items).

4.2. Solution: Async Priority Cache

We decouple Calculation from Read.

1. Database Extention:

   • Table: OrderTravelProductOMGT
   • Column: PriorityScore (float, indexed)
   • Column: PriorityLastUpdated (datetime)

2. Service Component: OrderPriorityService (Side-car)

   • Isolated stateless logic.
   • Dependencies: OrderTravelProductOMGT (Entity), ToDoListService.

3. Calculation Strategy (Hybrid):

   • A. Reactive (User Level):
     • Trigger: OrderService.Save() or ProcessHandler.
     • Mechanism: Fire-and-Forget. Use HostingEnvironment.QueueBackgroundWorkItem to run calculation after the request returns.
     • Latency: ~1-5 seconds.
   • B. Proactive (System Level):
     • Trigger: Nightly Batch Job.
     • Goal: Recalculate ALL active orders to capture "Time Passage" (e.g. crossing the 30-day threshold).

5. Strategic Roadmap

This feature is a Strategic Pilot for our platform modernization. It explicitly targets:

1. Pattern: Side-car Logic

   • We introduce new logic alongside the monolith, not inside the spaghetti.
   • The service is isolated, stateless, and interacts via defined inputs (Contracts).

2. Goal: TDD & Quality First

   • Since OrderPriorityService is a pure calculation engine, it is a perfect candidate for Test Driven Development.
   • We can write hundreds of unit tests (Scenarios) before writing the code, ensuring the algorithm behaves exactly as specified.

3. Goal: Linux/Docker Readiness

   • This service does not depend on System.Web or IIS-specifics (except the Fire-and-Forget hook, which is an adapter).
   • It paves the way for extracting "Calculation Engines" into separate .NET 8 Microservices running in Linux Containers.

4. Goal: Pipeline Automation

   • Being a new, isolated component, we can enforce Strict CI/CD from Day 1 (Linting, Test Coverage, Auto-Deployment).
   • It serves as a "Golden Path" example for future migrations.