Random

📘 Random Pool Selection Engine

This document defines the technical and functional logic of the Random Pool Selection engine, designed to ensure total transparency and mathematical determinism in audit processes, validated by the RandomPoolServiceImpTest suite.

1. Audit Transparency Structure

The engine generates an execution summary segmented into 6 key columns, each with a D|A (Drug | Alcohol) breakdown:

Column	Functional Definition
ELIGIBLE (D\|A)	Active employees (DOT) in their primary organization, filtered by organization type (Solo Drug, Solo Alcohol, or ALL).
INACTIVE (D\|A)	"Rescued" inactive employees when the `INCLUDE_INACTIVE_EMPLOYEE` parameter is active.
2nd ORG (D\|A)	Employees included in the pool due to having this organization as a secondary association in their profile.
IGNORED (D\|A)	Inactive employees existing in the database who were NOT rescued (used for accounting integrity).
C/O (D\|A)	Carry-Over: Selection carried forward from the most recent previous cycle, regardless of its completion status (RUNNING or FINISHED).
TARGET (D\|A)	Formula: (Eligible + Inactive + 2nd Org) * % + Carry-Over. Rounding: `Math.ceil`.

2. Exclusion Logic & Eligibility

The system applies exclusion filters to prevent duplicate testing based on organization settings:

Secondary Org Priority: An employee is excluded from their primary organization only if they have an active pool record (NEW or RUNNING) in their secondary organization. If no active conflict exists, they remain in their primary pool.
Group Respect: D|A quotas are assigned strictly according to the TypeFormGroupRandom of each organization. If an organization is "SOLO DRUG", its Alcohol columns will always report 0|0.
Deterministic Selection: The Preview and the Real Execution process share the same engine, ensuring that visualized results are identical to those processed.

3. Data Integrity & Constraints

Uniqueness (Double-Dip Protection): When an employee is selected for both Drug and Alcohol (ALL mode), the system generates a single physical selection record (RandomPoolPerson) to prevent database violations, while maintaining traceability for both categories in summary counters (BOTH Category).

4. Security Validations

The process will abort with a controlled RuntimeException if:

The total eligible population (Active + Rescued Inactive + 2nd Org) is zero.
No Stakeholders (Service Providers) are assigned to perform "Random Pool" tests for the organizations.
The selection percentages exceed allowed limits (0-100%).