🚀 Feature: Extend Rule Engine for Advanced Overtime & Holiday Logic (Non‑Breaking + API CRUD + Tests)

[renemadsen]

🎯 Goal

Implement advanced rule resolution logic using the updated database model without breaking any existing behavior.

This issue covers engine logic + API controllers/services + integration tests.
Database schema changes are handled separately.

Key principles (must-follow)

• ✅ Backward compatible: existing calculations and existing APIs must keep working as-is unless explicitly enabled via new configuration.
• ✅ Extend, don’t replace: build on existing rule engine code paths; gate new logic behind new rule fields / feature switches where needed.
• ✅ Incremental implementation: implement in small steps with green builds/tests after each step.
• ✅ No “big bang” refactors: avoid broad rewrites; prefer additive changes and well-scoped refactors.
• ✅ Safety checks before commit: run build + all tests before committing any changes.

---

🤖 GitHub Copilot Implementation Workflow (required)

0) Analyze first

Before writing code, Copilot must:

1. Locate current rule-engine calculation flow (entry points, services, calculators).
2. Identify existing overtime logic + holiday logic + day classification logic.
3. Identify where pay lines are generated (PlanRegistrationPayLines, existing pay code rules).
4. Identify existing API layer patterns (controllers/services/repositories), and existing integration test patterns.

1) Write a plan

Copilot must produce a short plan in the PR/commit message or as a comment in the issue describing:

• Which files/classes will be touched
• The order of implementation steps
• How backward compatibility is ensured (feature gating / defaults)
• Which tests will be added per step

2) Implement in steps (each step must be green)

For each step:

• Implement a small change
• Add/adjust tests for that change
• Run dotnet build and all tests
• Only then commit

---

🧮 Engine Implementation Tasks

1️⃣ Overtime Calculation (non-breaking)

Add support for:

• Weekly overtime
• Bi-weekly (14 days) overtime
• Monthly overtime
• Rolling averaging periods

Use new fields from WorkingTimeRuleSets:

• OvertimePeriodLengthDays
• OvertimeAveragingWindowDays
• MonthlyNormMode
• OvertimeAllocationStrategy

Backward compatibility rules

• If new fields are NULL/default → use existing overtime behavior exactly.
• Only activate new period-based logic when OvertimeBasis indicates it AND required parameters are present (or safe defaults are explicitly defined).

---

2️⃣ Overtime Allocation Strategies

Implement allocation strategies:

• LatestFirst
• EarliestFirst
• Proportional

Backward compatibility rules

• Default strategy must match current behavior (confirm by tests).
• Allocation must be deterministic.

---

3️⃣ Day-Type Resolution + Time-Bands (non-breaking)

Resolve day type:

• Weekday
• Saturday
• Sunday
• PublicHoliday
• CompanyHoliday

Apply new rule tables:

• PayDayTypeRules
• PayTimeBandRules

Backward compatibility rules

• If no PayDayTypeRules exist for a ruleset → fall back to current PayDayRules/PayTierRules behavior.
• Do not change existing paycode mapping unless new rules are configured.

---

4️⃣ Holiday Paid-Off Logic (non-breaking)

If employee does not work on public holiday:

• Use PlannedHours
• OR FixedSeconds
• OR None

Generate correct pay lines using configured pay codes.

Backward compatibility rules

• If HolidayPaidOffMode is default/None → preserve current holiday handling.
• If new mode enabled → ensure it does not affect non-holiday days.

---

5️⃣ 11-Hour Rest Rule

Use:

• MinimumDailyRestSeconds
• FirstWorkStartUtc
• LastWorkEndUtc

Add deterministic violation detection logic.
(If existing logic exists, extend it; do not break current outputs.)

---

🌐 API: Controllers + Services (CRUD)

We need API endpoints and service layer for index + CRUD of the new rule entities so Angular frontend can be implemented later.

Entities requiring CRUD

• PayRuleSets (existing)
• PayDayTypeRules (new)
• PayTimeBandRules (new)
• WorkingTimeRuleSets (existing, now extended)
• AssignedSiteRuleSetAssignments (new) — if repository includes employee rule assignment logic

Requirements

• Follow existing architectural patterns (controller → service → repository/data access).
• Include:
  • GET /... list/index (paging optional)
  • GET /.../{id}
  • POST /...
  • PUT /.../{id}
  • DELETE /.../{id} (soft delete if your workflow state model requires it)
• Validate inputs (time band boundaries, overlaps, day type duplicates, etc.).
• Ensure new endpoints do not break existing routes.

---

🧪 Testing Requirements (must-have)

Integration tests (required for ALL controllers/services)

All controllers and services introduced/changed must have full integration test coverage, including:

• Create
• Read
• Update
• Delete
• Index/list
• Validation failures (bad requests)

Tooling constraints

• All test methods should use NSubstitute for mocking dependencies.
• Avoid brittle tests; assert on meaningful outcomes (HTTP status, payload, persisted state).

Engine tests

Add coverage for:

• Weekly overtime
• 14-day overtime
• Monthly overtime
• Rolling window overtime
• Allocation strategies
• Sunday split time bands
• Holiday worked vs not worked
• Rule changes mid-period (effective dating)

Backward compatibility tests

• Add “golden” tests that assert existing behavior remains unchanged when new configs are not present.

---

✅ Acceptance Criteria

• ✅ Deterministic rule output
• ✅ All existing tests pass unchanged (or updated only when strictly necessary)
• ✅ Full integration tests for every new/changed controller/service
• ✅ NSubstitute used for mocking in all tests
• ✅ No performance regression in calculations
• ✅ New features are disabled by default unless configured

---

📦 Deliverables

• Updated rule engine logic (additive, gated)
• New/updated controllers + services for CRUD/index of rule entities
• Integration tests for all controllers/services
• Engine unit/integration tests for new logic
• Documentation/comments describing how to enable new rules safely