plansolve 0.27.0

use serde::{Deserialize, Serialize};

/// Request model for starting a shift optimization.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShiftRequest {
    /// Optional caller-supplied identifier for the plan.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    /// Plan display name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Free-text plan description.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// Contracts defining the working-time rules referenced by employees.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub contracts: Vec<Contract>,
    /// Shifts that need to be staffed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub shifts: Vec<ShiftAssignment>,
    /// Employees available to be assigned to shifts.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub employees: Vec<ShiftEmployee>,
    /// Optional controls governing how the shift solver runs.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub options: Option<Options>,
    /// Per-constraint penalty weights that steer the solver's objective.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub weights: Option<Weights>,
    /// Fairness configuration.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fairness: Option<Fairness>,
    /// Employee requests to have specific days off.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub day_off_requests: Vec<DayOffRequest>,
    /// Employee requests to avoid specific shifts.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub shift_off_requests: Vec<ShiftOffRequest>,
    /// Optional callback URL invoked when solving completes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hook: Option<String>,
    /// Advanced knobs for the shift constraint set.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub constraint_weight_overrides: Option<ConstraintWeightOverrides>,
}

/// A time window for shift scheduling.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Shift {
    /// Caller-supplied unique identifier for the shift.
    pub id: String,
    /// Earliest the shift may start.
    pub min_start_time: String,
    /// Latest the shift may end.
    pub max_end_time: String,
}

/// A shift assignment to be scheduled.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShiftAssignment {
    /// Shift name, used as its identifier.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Shift start, as an ISO-8601 timestamp.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,
    /// Shift end, as an ISO-8601 timestamp.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub to: Option<String>,
    /// Skills an employee must have to be assigned this shift.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub skills: Vec<String>,
    /// Cost of staffing this shift.
    #[serde(default)]
    pub cost: f64,
    /// Business value of staffing this shift.
    #[serde(default)]
    pub value: i64,
    /// Relative priority of staffing this shift.
    #[serde(default)]
    pub priority: i64,
    /// Skills that are preferred but not required.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub desired_skills: Vec<String>,
    /// Arbitrary tags used for grouping and affinity constraints.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// When true, the existing assignment is locked and left unchanged by the solver.
    #[serde(default)]
    pub pinned_by_user: bool,
}

/// An employee in the shift optimization.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShiftEmployee {
    /// Employee name, used as the identifier referenced by requests and assignments.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Name of the [`Contract`] governing this employee's working-time rules.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub contract: Option<String>,
    /// Skills the employee possesses.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub skills: Vec<String>,
    /// Date the employee last had rest.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub last_rest_date: Option<String>,
    /// Dates/periods the employee is available to work.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub availability: Vec<String>,
    /// Shifts/periods the employee prefers to work.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub preference: Vec<String>,
    /// Period-specific working-time rules for this employee.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub period_rules: Vec<PeriodRule>,
    /// Dates the employee cannot work.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub unavailable_dates: Vec<String>,
    /// Arbitrary tags used for grouping and affinity constraints.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// Cap on weekly working minutes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub maximum_minutes_per_week: Option<i64>,
    /// Solution: shifts assigned to this employee.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub shifts: Vec<ShiftAssignment>,
}

/// A shift employee contract.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Contract {
    /// Contract name, referenced by an employee's `contract` field.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Maximum total working time, as an ISO-8601 duration.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max: Option<String>,
    /// Minimum total working time, as an ISO-8601 duration.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min: Option<String>,
    /// Maximum consecutive days that may be worked.
    #[serde(default)]
    pub max_consecutive_work_days: i64,
    /// Maximum shifts allowed on a single day.
    #[serde(default)]
    pub max_shifts_day: i64,
    /// Minimum rest between two shifts on the same day.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_rest_between_shifts_same_day: Option<String>,
    /// Maximum working days in the planning period.
    #[serde(default)]
    pub max_working_days: i64,
    /// Latest permitted shift start time.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub latest_shift_start: Option<String>,
    /// Earliest permitted shift start time.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub earliest_shift_start: Option<String>,
    /// Minimum consecutive days off between working stretches.
    #[serde(default)]
    pub minimum_consecutive_days_off: i64,
    /// Minimum hours off between consecutive shifts.
    #[serde(default)]
    pub minimum_hours_off_between_shifts: i64,
}

/// Constraint weights for the shift optimizer.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Weights {
    /// Penalty for assigning an employee who lacks a shift's required skills.
    pub required_skills: i64,
    /// Penalty for exceeding a shift's staffing capacity.
    pub shift_capacity: i64,
    /// Penalty for staffing a shift below its minimum required headcount.
    pub minimum_staffing: i64,
    /// Penalty for assigning an employee to overlapping shifts.
    pub no_double_booking: i64,
    /// Penalty for violating the required rest between consecutive shifts.
    pub rest_between_shifts: i64,
    /// Penalty for assigning an employee outside their declared availability.
    pub employee_availability: i64,
    /// Reward/penalty weight for honoring employees' shift preferences.
    pub shift_preferences: i64,
    /// Weight for minimizing total staffing cost.
    pub cost_minimization: i64,
    /// Weight for balancing workload evenly across employees.
    pub workload_balance: i64,
    /// Weight for the fairness objective across fairness buckets.
    pub fairness: i64,
    /// Penalty for exceeding the maximum consecutive working days.
    pub max_consecutive_work_days: i64,
    /// Penalty for exceeding the maximum shifts per day.
    pub max_shifts_per_day: i64,
    /// Penalty for exceeding the maximum working days per week.
    pub max_working_days_per_week: i64,
    /// Penalty for violating the contract's minimum rest between shifts.
    pub contract_rest_between_shifts: i64,
    /// Penalty for starting a shift before the contract's earliest allowed start.
    pub earliest_shift_start: i64,
    /// Penalty for starting a shift after the contract's latest allowed start.
    pub latest_shift_start: i64,
    /// Penalty for providing fewer than the minimum consecutive days off.
    pub minimum_consecutive_days_off: i64,
    /// Penalty for violating an employee's period-specific rule.
    pub period_rule_violation: i64,
    /// Weight for preferring employees who hold a shift's desired skills.
    pub desired_skills: i64,
    /// Weight for honoring employees' desired day-off requests.
    pub desired_day_off: i64,
    /// Weight for honoring employees' shift-off requests.
    pub shift_off_request: i64,
    /// Weight for balancing total time worked across employees.
    pub balance_time_worked: i64,
    /// Weight for keeping tagged employees working together.
    pub employee_affinity: i64,
    /// Weight for avoiding shifts scheduled immediately adjacent to a day off.
    pub avoid_shift_close_to_day_off: i64,
}

/// Solver options for the shift optimizer.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Options {
    /// When true, keeps existing assignments and only fills the gaps.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub partial_planning: Option<bool>,
    /// Maximum number of solver iterations before stopping.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_iterations: Option<i64>,
    /// Maximum solve time in seconds.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub time_limit: Option<i64>,
}

/// Fairness configuration for the shift optimizer.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Fairness {
    /// Buckets defining the groups the fairness objective balances over.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub fairness_buckets: Vec<FairnessBucket>,
}

/// A fairness bucket grouping employees and shifts.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FairnessBucket {
    /// Name identifier for the fairness bucket.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// List of employee names in this bucket.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub employees: Vec<String>,
    /// List of shift names in this bucket.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub shifts: Vec<String>,
    /// Time period for this bucket (e.g. `2024-01-01/2024-01-08`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub period: Option<String>,
}

/// An employee's request for a day off.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DayOffRequest {
    /// Optional caller-supplied identifier for the request.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    /// Name of the employee making the request.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub employee_name: Option<String>,
    /// The requested day off, as an ISO-8601 date.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub date: Option<String>,
    /// Strength of the preference; higher values make honoring it more important.
    #[serde(default)]
    pub weight: i64,
}

/// An employee's request to be off a specific shift.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShiftOffRequest {
    /// Optional caller-supplied identifier.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    /// Name of the employee making the request.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub employee_name: Option<String>,
    /// Name of the shift the employee wants to avoid.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub shift_name: Option<String>,
    /// Strength of the preference; higher values make honoring it more important.
    #[serde(default)]
    pub weight: i64,
}

/// A period-based working constraint.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PeriodRule {
    /// The planning period this rule applies to.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub period: Option<PlanningPeriod>,
    /// Maximum working days allowed within the period.
    #[serde(default)]
    pub max_working_days: i64,
    /// Minimum working days required within the period.
    #[serde(default)]
    pub min_working_days: i64,
    /// Minimum total working time within the period.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_working_duration: Option<String>,
    /// Maximum total working time within the period.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_working_duration: Option<String>,
    /// Minimum rest between shifts on the same day.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_rest_duration_between_shifts_same_day: Option<String>,
    /// Minimum rest between consecutive shifts.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_rest_duration: Option<String>,
}

/// A time period for planning rules.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PlanningPeriod {
    /// Start of the period.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,
    /// End of the period.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub to: Option<String>,
}

/// Overrides for constraint weights.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConstraintWeightOverrides {
    /// Names of constraints the solver is expected to recognize and apply.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub known_constraint_names: Vec<String>,
}

/// Response from starting a shift optimization.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShiftStartResponse {
    /// Public PlanSolve job identifier - use it to poll status and fetch the solution.
    pub job_id: String,
    /// The underlying solver engine's job identifier, when exposed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub solver_job_id: Option<String>,
    /// Inline solver result as raw JSON, when available synchronously.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result: Option<String>,
    /// Error message when the solve request could not be accepted or run.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

/// Response from getting shift optimization results.
///
/// The server returns a full echo of the request (all planning inputs) plus the
/// result fields `feasible`, `scoreString`, `score`, `unassignedShifts`, and
/// `assignedShifts`. The wire body carries **no** `jobId`; `job_id` here is a
/// client-side convenience stamped by
/// [`ShiftClient::get_result`](crate::shift::ShiftClient::get_result) and is never
/// read from or written to the wire.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShiftResultResponse {
    /// Public PlanSolve job identifier, stamped client-side from the request.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub job_id: Option<String>,
    // Echoed request fields.
    /// Echoed plan identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    /// Echoed plan display name.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Echoed plan description.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// Echoed contracts defining the working-time rules referenced by employees.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub contracts: Vec<Contract>,
    /// Echoed shifts that needed to be staffed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub shifts: Vec<ShiftAssignment>,
    /// Employees with their assigned shifts populated by the solver.
    #[serde(default)]
    pub employees: Vec<ShiftEmployee>,
    /// Echoed employee day-off requests.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub day_off_requests: Vec<DayOffRequest>,
    /// Echoed employee shift-off requests.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub shift_off_requests: Vec<ShiftOffRequest>,
    /// Echoed solver options.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub options: Option<Options>,
    /// Echoed per-constraint penalty weights.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub weights: Option<Weights>,
    /// Echoed fairness configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub fairness: Option<Fairness>,
    /// Echoed callback URL invoked when solving completes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hook: Option<String>,
    /// Echoed advanced knobs for the shift constraint set.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub constraint_weight_overrides: Option<ConstraintWeightOverrides>,
    // Result fields.
    /// Whether the returned solution satisfies all hard constraints.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub feasible: Option<bool>,
    /// Final score as a solver score string.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub score_string: Option<String>,
    /// Score broken down into its component levels.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub score: Option<serde_json::Value>,
    /// Shifts the solver could not staff.
    #[serde(default)]
    pub unassigned_shifts: Vec<ShiftAssignment>,
    /// Shifts the solver successfully staffed.
    #[serde(default)]
    pub assigned_shifts: Vec<ShiftAssignment>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn serializes_and_omits_empty_collections() {
        let json = serde_json::to_string(&ShiftRequest::default()).unwrap();
        // Empty optional vectors are omitted, keeping payloads lean.
        assert!(!json.contains("\"shifts\""));
        assert!(!json.contains("\"employees\""));
    }

    #[test]
    fn serializes_populated_assignment() {
        let request = ShiftRequest {
            shifts: vec![ShiftAssignment {
                name: Some("Night".into()),
                cost: 12.5,
                priority: 3,
                pinned_by_user: true,
                ..Default::default()
            }],
            ..Default::default()
        };
        let json = serde_json::to_string(&request).unwrap();
        assert!(json.contains("\"shifts\""));
        assert!(json.contains("\"pinnedByUser\":true"));
        assert!(json.contains("\"cost\":12.5"));
    }

    #[test]
    fn request_omits_result_only_fields() {
        // score / assignedShifts / unassignedShifts belong to the response, never the
        // request — a fully-defaulted request must not emit them.
        let json = serde_json::to_string(&ShiftRequest::default()).unwrap();
        assert!(!json.contains("\"score\""));
        assert!(!json.contains("\"assignedShifts\""));
        assert!(!json.contains("\"unassignedShifts\""));
    }

    #[test]
    fn deserializes_result_response() {
        // The response is a full echo of the request plus the result fields.
        let json = r#"{
            "id": "roster-1",
            "name": "January roster",
            "description": "night ward",
            "contracts": [{"name": "full-time", "max": "PT40H"}],
            "shifts": [
                {"name": "Ward A", "from": "2024-01-15T22:00:00", "to": "2024-01-16T06:00:00"}
            ],
            "dayOffRequests": [{"employeeName": "Alice", "date": "2024-01-20", "weight": 5}],
            "shiftOffRequests": [{"employeeName": "Alice", "shiftName": "Ward B", "weight": 3}],
            "options": {"partialPlanning": true},
            "hook": "https://example.test/hook",
            "feasible": true,
            "scoreString": "0hard/0medium/-45soft",
            "score": {"hard": 0, "medium": 0, "soft": -45},
            "assignedShifts": [
                {"name": "Ward A", "from": "2024-01-15T22:00:00", "to": "2024-01-16T06:00:00",
                 "skills": ["nurse"], "cost": 12.5, "value": 2, "priority": 3}
            ],
            "unassignedShifts": [
                {"name": "Ward B", "from": "2024-01-16T22:00:00", "to": "2024-01-17T06:00:00",
                 "skills": ["nurse", "first_aid"]}
            ],
            "employees": [
                {"name": "Alice", "skills": ["nurse"], "shifts": [
                    {"name": "Ward A", "from": "2024-01-15T22:00:00", "to": "2024-01-16T06:00:00"}
                ]}
            ]
        }"#;

        let result: ShiftResultResponse = serde_json::from_str(json).unwrap();
        // Echoed request fields.
        assert_eq!(result.id.as_deref(), Some("roster-1"));
        assert_eq!(result.name.as_deref(), Some("January roster"));
        assert_eq!(result.contracts.len(), 1);
        assert_eq!(result.shifts.len(), 1);
        assert_eq!(result.day_off_requests.len(), 1);
        assert_eq!(result.shift_off_requests.len(), 1);
        assert_eq!(
            result.options.as_ref().unwrap().partial_planning,
            Some(true)
        );
        assert_eq!(result.hook.as_deref(), Some("https://example.test/hook"));
        // Result fields.
        assert_eq!(result.feasible, Some(true));
        assert_eq!(
            result.score_string.as_deref(),
            Some("0hard/0medium/-45soft")
        );
        assert_eq!(result.assigned_shifts.len(), 1);
        assert_eq!(result.assigned_shifts[0].name.as_deref(), Some("Ward A"));
        assert_eq!(
            result.assigned_shifts[0].from.as_deref(),
            Some("2024-01-15T22:00:00")
        );
        assert_eq!(result.assigned_shifts[0].cost, 12.5);
        assert_eq!(result.unassigned_shifts.len(), 1);
        assert_eq!(result.employees.len(), 1);
        assert_eq!(result.employees[0].shifts.len(), 1);
    }
}