SolverForge Hospital Use Case

use serde::{Deserialize, Serialize};

/// Coarse service-line grouping used to make nearby search meaningful.
///
/// The solver does not understand "hospital geography" by itself. We therefore
/// encode a lightweight domain signal that says which locations and employee
/// skill bundles are close to one another.
#[derive(
    Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
#[serde(rename_all = "snake_case")]
pub enum CareHub {
    Ambulatory,
    Neurology,
    CriticalCare,
    PediatricCare,
    Surgery,
    Radiology,
    Outpatient,
    #[default]
    Unknown,
}

impl CareHub {
    /// Maps a published shift location label to the hub used by nearby search.
    pub fn from_location(location: &str) -> Self {
        match location {
            "Ambulatory care" => Self::Ambulatory,
            "Neurology" => Self::Neurology,
            "Critical care" => Self::CriticalCare,
            "Pediatric care" => Self::PediatricCare,
            "Surgery" => Self::Surgery,
            "Radiology" => Self::Radiology,
            "Outpatient" => Self::Outpatient,
            _ => Self::Unknown,
        }
    }

    /// Maps a required skill to the hub that most naturally owns that work.
    pub fn from_skill(skill: &str) -> Option<Self> {
        match skill {
            "Ambulatory doctor" | "Ambulatory nurse" => Some(Self::Ambulatory),
            "Neurology doctor" | "Neurology nurse" | "Cardiology" => Some(Self::Neurology),
            "Critical care doctor" | "Critical care nurse" => Some(Self::CriticalCare),
            "Pediatric doctor" | "Pediatric nurse" => Some(Self::PediatricCare),
            "Surgery doctor" | "Surgery nurse" | "Anaesthetics" => Some(Self::Surgery),
            "Radiology day" | "Radiology nurse" | "Radiology call" => Some(Self::Radiology),
            "Outpatient doctor" | "Outpatient nurse" => Some(Self::Outpatient),
            _ => None,
        }
    }

    /// Guesses an employee's home hub from the service-line skills they carry.
    ///
    /// This is only a fallback for generated or decoded employees that did not
    /// set `home_hub` explicitly.
    pub fn infer_from_skills<'a>(skills: impl IntoIterator<Item = &'a str>) -> Self {
        let mut counts = [0usize; 7];
        for skill in skills {
            match Self::from_skill(skill) {
                Some(Self::Ambulatory) => counts[0] += 1,
                Some(Self::Neurology) => counts[1] += 1,
                Some(Self::CriticalCare) => counts[2] += 1,
                Some(Self::PediatricCare) => counts[3] += 1,
                Some(Self::Surgery) => counts[4] += 1,
                Some(Self::Radiology) => counts[5] += 1,
                Some(Self::Outpatient) => counts[6] += 1,
                Some(Self::Unknown) | None => {}
            }
        }

        let Some((best_index, best_count)) = counts
            .iter()
            .copied()
            .enumerate()
            .max_by_key(|&(index, count)| (count, index))
        else {
            return Self::Unknown;
        };

        if best_count == 0 {
            Self::Unknown
        } else {
            match best_index {
                0 => Self::Ambulatory,
                1 => Self::Neurology,
                2 => Self::CriticalCare,
                3 => Self::PediatricCare,
                4 => Self::Surgery,
                5 => Self::Radiology,
                6 => Self::Outpatient,
                _ => Self::Unknown,
            }
        }
    }
}

use chrono::NaiveDate;
use serde::{Deserialize, Serialize};
use solverforge::prelude::*;
use std::collections::BTreeSet;

use super::CareHub;

/// Hospital staff member published as a SolverForge problem fact.
///
/// A few fields are "authoritative transport state" (`*_dates`), while others
/// are precomputed runtime helpers (`index`, `*_days`). `finalize()` keeps those
/// two views in sync after generation or JSON decoding.
#[problem_fact]
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Employee {
    pub id: String,
    #[serde(skip)]
    pub index: usize,
    pub name: String,
    #[serde(default)]
    pub home_hub: CareHub,
    #[serde(default)]
    pub skills: BTreeSet<String>,
    #[serde(default)]
    pub unavailable_dates: BTreeSet<NaiveDate>,
    #[serde(default)]
    pub undesired_dates: BTreeSet<NaiveDate>,
    #[serde(default)]
    pub desired_dates: BTreeSet<NaiveDate>,
    #[serde(skip)]
    pub unavailable_days: Vec<NaiveDate>,
    #[serde(skip)]
    pub undesired_days: Vec<NaiveDate>,
    #[serde(skip)]
    pub desired_days: Vec<NaiveDate>,
}

impl Employee {
    /// Creates a beginner-friendly builder seed with stable defaults.
    pub fn new(index: usize, name: impl Into<String>) -> Self {
        Self {
            id: format!("employee-{index}"),
            index,
            name: name.into(),
            home_hub: CareHub::Unknown,
            skills: BTreeSet::new(),
            unavailable_dates: BTreeSet::new(),
            undesired_dates: BTreeSet::new(),
            desired_dates: BTreeSet::new(),
            unavailable_days: Vec::new(),
            undesired_days: Vec::new(),
            desired_days: Vec::new(),
        }
    }

    /// Overrides the transport-visible identifier.
    pub fn with_id(mut self, id: impl Into<String>) -> Self {
        self.id = id.into();
        self
    }

    /// Sets the employee's home service line used by nearby search.
    pub fn with_home_hub(mut self, home_hub: CareHub) -> Self {
        self.home_hub = home_hub;
        self
    }

    /// Rebuilds the derived caches the solver reads frequently.
    ///
    /// The serialized `BTreeSet`s are the stable truth for transport. The
    /// `Vec`s are just pre-expanded, iteration-friendly mirrors used by
    /// constraints and heuristics.
    pub fn finalize(&mut self) {
        if self.home_hub == CareHub::Unknown {
            self.home_hub = CareHub::infer_from_skills(self.skills.iter().map(String::as_str));
        }
        self.unavailable_days = self.unavailable_dates.iter().copied().collect();
        self.undesired_days = self.undesired_dates.iter().copied().collect();
        self.desired_days = self.desired_dates.iter().copied().collect();
    }

    /// Adds one service-line skill to the employee.
    pub fn with_skill(mut self, skill: impl Into<String>) -> Self {
        self.skills.insert(skill.into());
        self
    }

    /// Adds several skills in one builder step.
    pub fn with_skills(mut self, skills: impl IntoIterator<Item = impl Into<String>>) -> Self {
        for skill in skills {
            self.skills.insert(skill.into());
        }
        self
    }

    /// Marks a day as completely unavailable.
    pub fn with_unavailable_date(mut self, date: NaiveDate) -> Self {
        self.unavailable_dates.insert(date);
        self
    }

    /// Marks a day the employee would prefer to avoid.
    pub fn with_undesired_date(mut self, date: NaiveDate) -> Self {
        self.undesired_dates.insert(date);
        self
    }

    /// Marks a day the employee would actively like to work.
    pub fn with_desired_date(mut self, date: NaiveDate) -> Self {
        self.desired_dates.insert(date);
        self
    }
}

//! Domain model for the hospital employee scheduling problem.

use chrono::{NaiveDate, NaiveDateTime, Timelike};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use solverforge::prelude::*;

use super::{CareHub, Employee};

/// Work item that the solver must assign to exactly one employee or leave open.
///
/// In this example a shift is the only planning entity, which keeps the
/// beginner mental model simple: SolverForge is choosing `employee_idx` values
/// for each `Shift`.
#[planning_entity]
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Shift {
    #[planning_id]
    pub id: String,
    #[serde(skip)]
    pub index: usize,
    pub start: NaiveDateTime,
    pub end: NaiveDateTime,
    pub location: String,
    #[serde(default)]
    pub care_hub: CareHub,
    pub required_skill: String,
    #[serde(skip)]
    pub touched_dates: Vec<NaiveDate>,
    // Scalar planning slot index into `Plan.employees`, not `Employee.id`.
    #[planning_variable(
        value_range = "employees",
        allows_unassigned = true,
        nearby_value_distance_meter = "shift_to_employee_nearby_distance",
        nearby_entity_distance_meter = "shift_to_shift_nearby_distance"
    )]
    pub employee_idx: Option<usize>,
}

impl Shift {
    /// Creates a new unassigned shift and derives its first-pass care hub.
    pub fn new(
        id: impl Into<String>,
        start: NaiveDateTime,
        end: NaiveDateTime,
        location: impl Into<String>,
        required_skill: impl Into<String>,
    ) -> Self {
        let location = location.into();
        Self {
            id: id.into(),
            index: 0,
            start,
            end,
            care_hub: CareHub::from_location(&location),
            location,
            required_skill: required_skill.into(),
            touched_dates: Vec::new(),
            employee_idx: None,
        }
    }

    /// Returns every calendar day touched by the shift, including overnight end days.
    pub fn touched_dates(&self) -> &[NaiveDate] {
        self.touched_dates.as_slice()
    }

    /// Convenience helper used by tests and data exploration.
    pub fn duration_hours(&self) -> f64 {
        (self.end - self.start).num_minutes() as f64 / 60.0
    }
}

/// Full planning solution published to the solver runtime and the HTTP API.
#[planning_solution(
    constraints = "crate::constraints::create_constraints",
    solver_toml = "../../solver.toml"
)]
#[derive(Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Plan {
    #[problem_fact_collection]
    pub employees: Vec<Employee>,
    #[planning_entity_collection]
    pub shifts: Vec<Shift>,
    #[planning_score]
    pub score: Option<HardSoftDecimalScore>,
}

impl Plan {
    /// Builds a plan and immediately restores all derived runtime helpers.
    pub fn new(employees: Vec<Employee>, shifts: Vec<Shift>) -> Self {
        let mut schedule = Self {
            employees,
            shifts,
            score: None,
        };
        schedule.rebuild_derived_fields();
        schedule
    }

    /// Recomputes indexes, inferred hubs, touched dates, and range-safe assignments.
    ///
    /// This runs after generation and after transport decoding so the domain
    /// model always reaches the solver in a normalized state.
    pub fn rebuild_derived_fields(&mut self) {
        for (index, employee) in self.employees.iter_mut().enumerate() {
            employee.index = index;
            employee.finalize();
        }

        for (index, shift) in self.shifts.iter_mut().enumerate() {
            shift.index = index;
            if shift.care_hub == CareHub::Unknown {
                shift.care_hub = CareHub::from_location(&shift.location);
            }
            shift.touched_dates = dates_touched_by_span(shift.start, shift.end);
            shift.employee_idx = shift
                .employee_idx
                .filter(|employee_idx| *employee_idx < self.employees.len());
        }
    }

    /// Converts the domain model into a flat JSON-object field map for transport DTOs.
    pub fn to_transport_fields(&self) -> Map<String, Value> {
        match serde_json::to_value(self).expect("failed to serialize employee schedule") {
            Value::Object(fields) => fields,
            _ => Map::new(),
        }
    }

    /// Rebuilds a domain plan from the transport field map used by `PlanDto`.
    pub fn from_transport_fields(fields: Map<String, Value>) -> Result<Self, serde_json::Error> {
        let mut schedule: Self = serde_json::from_value(Value::Object(fields))?;
        schedule.rebuild_derived_fields();
        Ok(schedule)
    }

    /// Safe index lookup used by nearby meters and constraint helpers.
    #[inline]
    pub fn get_employee(&self, idx: usize) -> Option<&Employee> {
        self.employees.get(idx)
    }

    /// Convenience accessor used by tests and diagnostics.
    #[inline]
    pub fn employee_count(&self) -> usize {
        self.employees.len()
    }

    /// Named slice accessor used by joins and generated transport code.
    #[inline]
    pub fn employees_slice(&self) -> &[Employee] {
        self.employees.as_slice()
    }
}

//! Domain-layer exports for the planning model.
//!
//! This file is intentionally tiny: it keeps the public names for the rest of
//! the app in one place, while the real teaching material lives in the
//! dedicated domain modules.

// @solverforge:begin domain-exports
mod care_hub;
mod employee;
mod plan;

pub use care_hub::CareHub;
pub use employee::Employee;
pub use plan::{Plan, PlanConstraintStreams, Shift, ShiftUnassignedFilter};
// @solverforge:end domain-exports

const SCORE_SCALE: i64 = 100_000;

fn shift_to_employee_nearby_distance(solution: &Plan, shift: &Shift, employee_index: usize) -> f64 {
    let Some(employee) = solution.get_employee(employee_index) else {
        return f64::INFINITY;
    };

    let mut distance = 10.0 * care_hub_distance(shift.care_hub, employee.home_hub);

    if !employee.skills.contains(&shift.required_skill) {
        distance += 10_000.0;
    } else if CareHub::from_skill(&shift.required_skill) != Some(employee.home_hub) {
        distance += 12.0;
    }

    if shift
        .touched_dates()
        .iter()
        .any(|date| employee.unavailable_dates.contains(date))
    {
        distance += 2_000.0;
    }

    distance
}

fn shift_to_shift_nearby_distance(_solution: &Plan, left: &Shift, right: &Shift) -> f64 {
    10.0 * care_hub_distance(left.care_hub, right.care_hub)
        + start_band_distance(left.start.time().hour(), right.start.time().hour())
}

//! Constraint assembly for employee scheduling.
//!
//! Each sibling module contributes one named rule. `create_constraints()`
//! simply lists them in the order we want them to appear in analysis output.

use crate::domain::Plan;
use solverforge::prelude::*;

pub use self::assemble::create_constraints;

// @solverforge:begin constraint-modules
mod assigned_shift;
mod balance_assignments;
mod desired_day;
mod minimum_rest;
mod one_shift_per_day;
mod overlapping_shift;
mod required_skill;
mod unavailable_employee;
mod undesired_day;
// @solverforge:end constraint-modules

mod assemble {
    use super::*;

    /// Collects the full scoring model used by `Plan`.
    pub fn create_constraints() -> impl ConstraintSet<Plan, HardSoftDecimalScore> {
        // @solverforge:begin constraint-calls
        (
            assigned_shift::constraint(),
            required_skill::constraint(),
            overlapping_shift::constraint(),
            minimum_rest::constraint(),
            one_shift_per_day::constraint(),
            unavailable_employee::constraint(),
            undesired_day::constraint(),
            desired_day::constraint(),
            balance_assignments::constraint(),
        )
        // @solverforge:end constraint-calls
    }
}

use crate::domain::{Plan, PlanConstraintStreams, ShiftUnassignedFilter};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

const SCORE_SCALE: i64 = 100_000;

/// Penalizes every shift that remains unassigned at the end of solving.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .unassigned()
        .penalize(HardSoftDecimalScore::of_hard_scaled(SCORE_SCALE))
        .named("Assigned shift")
}

use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

const SCORE_SCALE: i64 = 100_000;

/// Penalizes assignments where the employee lacks the required skill label.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join((
            Plan::employees_slice,
            joiner::equal_bi(
                |shift: &Shift| shift.employee_idx,
                |employee: &Employee| Some(employee.index),
            ),
        ))
        .filter(|shift: &Shift, employee: &Employee| {
            !employee.skills.contains(&shift.required_skill)
        })
        .penalize(HardSoftDecimalScore::of_hard_scaled(10 * SCORE_SCALE))
        .named("Required skill")
}

use crate::domain::{Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

const SCORE_SCALE: i64 = 100_000;
const STRUCTURAL_MINUTE_HARD_UNITS: i64 = 20;

/// Penalizes overlapping time windows for the same employee.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join(joiner::equal(|shift: &Shift| shift.employee_idx))
        .filter(|a: &Shift, b: &Shift| a.index < b.index && a.start < b.end && b.start < a.end)
        .penalize_hard_with(|a: &Shift, b: &Shift| {
            let overlap_start = a.start.max(b.start);
            let overlap_end = a.end.min(b.end);
            let overlap_minutes = if overlap_start < overlap_end {
                (overlap_end - overlap_start).num_minutes()
            } else {
                0
            };
            HardSoftDecimalScore::of_hard_scaled(
                overlap_minutes * STRUCTURAL_MINUTE_HARD_UNITS * SCORE_SCALE,
            )
        })
        .named("Overlapping shift")
}

use crate::domain::{Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

const SCORE_SCALE: i64 = 100_000;
const STRUCTURAL_MINUTE_HARD_UNITS: i64 = 20;

/// Penalizes back-to-back shifts that leave less than 10 hours of rest.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join(joiner::equal(|shift: &Shift| shift.employee_idx))
        .filter(|a: &Shift, b: &Shift| {
            if a.index >= b.index {
                return false;
            }

            let (earlier, later) = if a.end <= b.start {
                (a, b)
            } else if b.end <= a.start {
                (b, a)
            } else {
                return false;
            };

            let gap_minutes = (later.start - earlier.end).num_minutes();
            (0..600).contains(&gap_minutes)
        })
        .penalize_hard_with(|a: &Shift, b: &Shift| {
            let (earlier, later) = if a.end <= b.start { (a, b) } else { (b, a) };
            let gap_minutes = (later.start - earlier.end).num_minutes();
            HardSoftDecimalScore::of_hard_scaled(
                (600 - gap_minutes) * STRUCTURAL_MINUTE_HARD_UNITS * SCORE_SCALE,
            )
        })
        .named("At least 10 hours between 2 shifts")
}

use crate::domain::{Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

const SCORE_SCALE: i64 = 100_000;

/// Forbids assigning two shifts that touch the same calendar day to one employee.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join(joiner::equal(|shift: &Shift| shift.employee_idx))
        .filter(|a: &Shift, b: &Shift| {
            a.index < b.index
                && a.touched_dates()
                    .iter()
                    .any(|date| b.touched_dates().contains(date))
        })
        .penalize(HardSoftDecimalScore::of_hard_scaled(20 * SCORE_SCALE))
        .named("One shift per day")
}

use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

const SCORE_SCALE: i64 = 100_000;
const STRUCTURAL_MINUTE_HARD_UNITS: i64 = 20;

/// Penalizes assigning someone on dates they declared unavailable.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join((
            Plan::employees_slice,
            joiner::equal_bi(
                |shift: &Shift| shift.employee_idx,
                |employee: &Employee| Some(employee.index),
            ),
        ))
        .filter(|shift: &Shift, employee: &Employee| {
            employee.unavailable_days.iter().any(|date| {
                let day_start = date.and_hms_opt(0, 0, 0).unwrap();
                let day_end = date
                    .succ_opt()
                    .unwrap_or(*date)
                    .and_hms_opt(0, 0, 0)
                    .unwrap();
                let overlap_start = shift.start.max(day_start);
                let overlap_end = shift.end.min(day_end);
                overlap_start < overlap_end
            })
        })
        .penalize_hard_with(|shift: &Shift, employee: &Employee| {
            let overlap_minutes: i64 = employee
                .unavailable_days
                .iter()
                .map(|date| {
                    let day_start = date.and_hms_opt(0, 0, 0).unwrap();
                    let day_end = date
                        .succ_opt()
                        .unwrap_or(*date)
                        .and_hms_opt(0, 0, 0)
                        .unwrap();
                    let overlap_start = shift.start.max(day_start);
                    let overlap_end = shift.end.min(day_end);
                    if overlap_start < overlap_end {
                        (overlap_end - overlap_start).num_minutes()
                    } else {
                        0
                    }
                })
                .sum();
            HardSoftDecimalScore::of_hard_scaled(
                overlap_minutes * STRUCTURAL_MINUTE_HARD_UNITS * SCORE_SCALE,
            )
        })
        .named("Unavailable employee")
}

use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

/// Softly penalizes assignments that land on an employee's undesired dates.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join((
            Plan::employees_slice,
            joiner::equal_bi(
                |shift: &Shift| shift.employee_idx,
                |employee: &Employee| Some(employee.index),
            ),
        ))
        .filter(|shift: &Shift, employee: &Employee| {
            employee
                .undesired_days
                .iter()
                .any(|date| shift.touched_dates().contains(date))
        })
        .penalize_with(|shift: &Shift, employee: &Employee| {
            HardSoftDecimalScore::of_soft(
                employee
                    .undesired_days
                    .iter()
                    .filter(|date| shift.touched_dates().contains(date))
                    .count() as i64,
            )
        })
        .named("Undesired day for employee")
}

use crate::domain::{Employee, Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

/// Rewards assigning an employee to dates they explicitly prefer.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join((
            Plan::employees_slice,
            joiner::equal_bi(
                |shift: &Shift| shift.employee_idx,
                |employee: &Employee| Some(employee.index),
            ),
        ))
        .filter(|shift: &Shift, employee: &Employee| {
            employee
                .desired_days
                .iter()
                .any(|date| shift.touched_dates().contains(date))
        })
        .reward_with(|shift: &Shift, employee: &Employee| {
            HardSoftDecimalScore::of_soft(
                employee
                    .desired_days
                    .iter()
                    .filter(|date| shift.touched_dates().contains(date))
                    .count() as i64,
            )
        })
        .named("Desired day for employee")
}

use crate::domain::{Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

/// Softly discourages concentrating too many shifts on one employee.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .balance(|shift: &Shift| shift.employee_idx)
        .penalize_soft()
        .named("Balance employee assignments")
}

pub fn start_job(&self, plan: Plan) -> Result<String, SolverManagerError>
pub fn get_status(&self, id: &str) -> Result<SolverStatus<HardSoftDecimalScore>, SolverManagerError>
pub fn pause(&self, id: &str) -> Result<(), SolverManagerError>
pub fn resume(&self, id: &str) -> Result<(), SolverManagerError>
pub fn cancel(&self, id: &str) -> Result<(), SolverManagerError>
pub fn delete(&self, id: &str) -> Result<(), SolverManagerError>
pub fn get_snapshot(&self, id: &str, snapshot_revision: Option<u64>) -> Result<SolverSnapshot<Plan>, SolverManagerError>
pub fn analyze_snapshot(&self, id: &str, snapshot_revision: Option<u64>) -> Result<SolverSnapshotAnalysis<HardSoftDecimalScore>, SolverManagerError>

static MANAGER: SolverManager<Plan> = SolverManager::new();

//! Stable public entrypoint for demo data.
//!
//! Other modules should import from `crate::data` instead of reaching directly
//! into `data_seed/`. That keeps the app's public data surface small even though
//! the generator itself is split across many focused files.

mod data_seed;

pub use data_seed::{generate, list_demo_data, DemoData};

//! Public demo-data surface for the hospital example.
//!
//! Keep this file intentionally thin. The rest of the application imports
//! `crate::data::{generate, list_demo_data, DemoData}` as a stable boundary, so
//! the detailed dataset design lives in sibling modules where it can evolve
//! without making the top-level data surface noisy.

mod availability;
mod cohorts;
mod coverage;
mod demand;
mod employees;
mod entrypoints;
mod large;
mod preferences;
mod shifts;
mod skills;
mod time_utils;
mod validation;
mod vocabulary;
mod witness;

#[cfg(test)]
mod solve_tests;
#[cfg(test)]
mod tests;

pub use entrypoints::{generate, list_demo_data, DemoData};

use std::str::FromStr;

use crate::domain::Plan;

use super::large::generate_large;

/// Public demo-data identifiers exposed through the HTTP API.
///
/// The hospital app currently ships one serious benchmark instance rather than a
/// menu of toy presets, so the surface stays explicit instead of pretending that
/// multiple sizes exist when they do not.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DemoData {
    Large,
}

impl FromStr for DemoData {
    type Err = ();

    /// Parses the case-insensitive demo id exposed over HTTP.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_uppercase().as_str() {
            "LARGE" => Ok(DemoData::Large),
            _ => Err(()),
        }
    }
}

impl DemoData {
    /// Returns the canonical uppercase id used by the HTTP API.
    pub fn as_str(&self) -> &'static str {
        match self {
            DemoData::Large => "LARGE",
        }
    }
}

/// Lists the demo identifiers accepted by `/demo-data/{id}`.
pub fn list_demo_data() -> Vec<&'static str> {
    vec![DemoData::Large.as_str()]
}

/// Generates the requested demo dataset.
///
/// Dispatch stays here so callers see the supported public variants in one
/// place, while the dataset assembly itself remains hidden in the per-instance
/// modules.
pub fn generate(demo: DemoData) -> Plan {
    match demo {
        DemoData::Large => generate_large(),
    }
}

/// Lists the demo ids accepted by `/demo-data/{id}`.
async fn list_demo_data() -> Json<Vec<&'static str>> {
    Json(data::list_demo_data())
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PlanDto {
    #[serde(flatten)]
    pub fields: Map<String, Value>,
    #[serde(default)]
    pub score: Option<String>,
}

impl PlanDto {
    pub fn from_plan(plan: &Plan) -> Self { ... }
    pub fn to_domain(&self) -> Result<Plan, serde_json::Error> {
        Plan::from_transport_fields(self.fields.clone())
    }
}

use crate::domain::{Plan, PlanConstraintStreams, Shift};
use solverforge::prelude::*;
use solverforge::IncrementalConstraint;

const SCORE_SCALE: i64 = 100_000;

/// Forbids assigning two shifts that touch the same calendar day to one employee.
pub fn constraint() -> impl IncrementalConstraint<Plan, HardSoftDecimalScore> {
    ConstraintFactory::<Plan, HardSoftDecimalScore>::new()
        .shifts()
        .filter(|shift: &Shift| shift.employee_idx.is_some())
        .join(joiner::equal(|shift: &Shift| shift.employee_idx))
        .filter(|a: &Shift, b: &Shift| {
            a.index < b.index
                && a.touched_dates()
                    .iter()
                    .any(|date| b.touched_dates().contains(date))
        })
        .penalize(HardSoftDecimalScore::of_hard_scaled(20 * SCORE_SCALE))
        .named("One shift per day")
}

mod one_shift_per_day;

(
    assigned_shift::constraint(),
    required_skill::constraint(),
    overlapping_shift::constraint(),
    minimum_rest::constraint(),
    one_shift_per_day::constraint(),
    unavailable_employee::constraint(),
    undesired_day::constraint(),
    desired_day::constraint(),
    balance_assignments::constraint(),
)

#[test]
fn required_skill_penalizes_missing_skill() {
    let plan = Plan::new(
        vec![Employee::new(0, "Alex")], // no skills
        vec![Shift::new(
            "shift-1",
            NaiveDate::from_ymd_opt(2024, 1, 1).unwrap().and_hms_opt(8, 0, 0).unwrap(),
            NaiveDate::from_ymd_opt(2024, 1, 1).unwrap().and_hms_opt(16, 0, 0).unwrap(),
            "ER",
            "Nurse",
        )],
    );

    let analysis = crate::constraints::create_constraints().evaluate_detailed(&plan);
    let required_skill = analysis
        .iter()
        .find(|a| a.constraint_ref.name == "Required skill")
        .expect("constraint should exist");

    assert!(required_skill.score.hard() < 0, "should penalize missing skill");
}