[feat] Extend issue #15 and issue #38: rolling work-order completion forecast and schedule-risk alerts

[Peryslaw81]

Problem / motivation

A work order currently has a customer due date and can be placed on the production calendar, but there is no authoritative distinction between:

1. The completion time requested by the customer or ERP.
2. The completion time calculated when the production plan is approved.
3. The latest completion time forecast from actual production progress and current resource availability.
4. The actual completion timestamp.

The customer due date must not move automatically when production is delayed. The approved baseline must also remain available for variance analysis. Only the operational forecast should move when machines fail, personnel become unavailable, production rate changes, blockers appear, or the schedule is modified.

The standard production time introduced by issue #52 and PR #237 is an important input, but the sum of:

setup time + run time per unit x quantity

across all operations represents standard work content and resource demand. It does not necessarily represent calendar lead time when operations overlap, compete for resources, cross shift boundaries, or are affected by downtime and personnel availability.

A simple comparison of elapsed time with produced quantity is also not sufficient for a reliable forecast. Early production samples can be distorted by setup, calibration, first-article inspection, rework, or a very small sample size. Future operations may use different workstations, dependencies, calendars, and production rates.

Without a shared forecasting service:

• The planner cannot show a reliable, continuously updated completion estimate.
• Supervisors cannot see when an order is likely to miss its approved baseline or customer due date.
• Overdue-risk suggestions from issue [feat] AI Suggestions engine — rule-based production insights (Phase 1) #38 would need to rely on simplified elapsed-time-versus-quantity heuristics.
• Schedule optimization from issue [feat] AI Suggestions — schedule optimization, priority alignment & LLM integration (Phase 2) #39 would not have a deterministic source of forecast and risk data.
• Each UI or analyzer could implement different completion-time logic.

Proposed solution

Add a deterministic rolling completion-forecast service for work orders. It should calculate remaining calendar duration, maintain baseline-versus-forecast history, and expose explainable schedule-risk information for the planner and suggestion engine.

Time model

Maintain the following concepts separately:

Value	Purpose	Behaviour
customer_due_at	Customer/ERP commitment	Stable; changed only by an explicit, audited business decision
baseline_planned_end_at	Completion calculated for the approved schedule	Frozen for plan-versus-forecast comparison; replaced only by an explicit re-baseline action
forecast_end_at	Latest operational completion estimate	Recalculated as execution and resource conditions change
completed_at	Actual completion	Recorded when the work order is completed

Equivalent existing field names may be used, but these concepts must remain semantically distinct.

Forecast calculation

The forecasting service should calculate the remaining calendar duration of a work order rather than treating total standard work content as elapsed duration.

The calculation should consider:

• Remaining setup and run time for each operation
• Planned, good, rejected, and remaining quantities
• Operation dependencies and critical path from issue [feat] Operations with dependencies — sequential and parallel operation scheduling #15
• Sequential and parallel operations
• Assigned workstation or eligible workstation type
• Workstation calendars, reservations, and resource conflicts
• Shift calendars and non-working periods
• Planned and unplanned downtime
• Required operator capacity and available qualified personnel
• Active blockers and unresolved production issues
• Current observed production rate when the sample is sufficiently reliable
• Historical performance as an optional fallback when standard data is unavailable

For an active operation, the estimator should blend standard and observed performance instead of immediately replacing the standard rate with a small or unstable sample. The weight of observed performance should increase as the sample becomes representative.

Future operations should continue to use their standard or historical durations until actual execution data becomes available.

Forecast result

The calculation should return an explainable result rather than only a timestamp:

{
  "forecast_end_at": "2026-08-21T06:30:00+02:00",
  "baseline_variance_minutes": 1230,
  "due_date_variance_minutes": 990,
  "confidence": "medium",
  "status": "late",
  "calculated_at": "2026-08-13T21:00:00+02:00",
  "reasons": [
    "active_operation_rate_below_standard",
    "workstation_downtime",
    "insufficient_personnel_on_next_shift"
  ]
}

Reason codes should be machine-readable so that the API, UI, alert system, and suggestion engine do not parse human-readable messages.

Recalculation

Recalculate forecasts after relevant domain events, including:

• Quantity or machine-counter update
• Batch-step start, pause, resume, or completion
• Workstation assignment or reassignment
• Downtime start or end
• Production issue creation, blocking, resolution, or closure
• Personnel or shift assignment change
• Schedule move or approved re-baseline
• Work-order quantity, process snapshot, or due-date change

Add a periodic reconciliation job for active work orders to recover from missed events and time-dependent calendar changes. Event-driven recalculation should remain the primary mechanism.

Schedule-risk evaluation

Publish deterministic risk state that issue #38 and issue #39 can consume.

Suggested conditions:

• Forecast exceeds the approved baseline by a configurable threshold
• Forecast exceeds the customer due date
• Required remaining production rate exceeds the observed or available rate
• A required future operation has no feasible workstation window
• Required personnel capacity is unavailable
• A blocker affects the critical path
• A previously late order returns to an on-time forecast

Support configurable warning and critical thresholds, deduplication, hysteresis, acknowledgement, and recovery. The system should not create a new alert after every calculation when the risk state has not materially changed.

Suggested actions must remain advisory. Moving work orders, changing priorities, assigning personnel, or extending shifts should require an authorized user action and an audit record.

User interface

Add optional columns to the work-order list:

• Customer due date
• Baseline planned completion
• Current forecast completion
• Variance from baseline
• Variance from customer due date
• Forecast confidence
• Schedule-risk status

On the work-order detail page, display:

• Standard work content
• Baseline calendar duration and completion
• Current forecast duration and completion
• Actual progress and observed rate
• Main reasons affecting the forecast
• Forecast history

In the production planner:

• Display the baseline and current forecast on the work-order block or detail popover.
• Visually identify orders forecast to miss their baseline or customer due date.
• Link active suggestions from issue [feat] AI Suggestions engine — rule-based production insights (Phase 1) #38 and issue [feat] AI Suggestions — schedule optimization, priority alignment & LLM integration (Phase 2) #39.
• Do not silently move or resize the approved baseline when the forecast changes.

Forecast history and auditability

Store a forecast snapshot when the forecast changes materially or its risk status changes. Include:

• Previous and new forecast completion
• Baseline and due-date variance
• Confidence
• Machine-readable reason codes
• Triggering event
• Calculation timestamp
• Calculation version or sufficient diagnostic metadata

Routine recalculations that do not materially change the result should not create unbounded history.

Service boundaries

The authoritative forecast must be deterministic and must not depend on an LLM.

Suggested service separation:

WorkOrderCompletionForecastService
|- RemainingOperationEstimator
|- ResourceCalendarScheduler
|- ObservedRateEstimator
|- ForecastConfidenceEvaluator
|- ScheduleRiskEvaluator
`- ForecastHistoryRecorder

The AI Suggestions engine from issue #38 may consume the result and create human-facing recommendations. Optional LLM functionality from issue #39 may explain a forecast, but it must not be the authoritative calculation source.

API

Proposed read endpoint:

GET /api/v1/work-orders/{id}/completion-forecast

The work-order show response may include the latest forecast summary. Detailed history can be exposed through a separate paginated endpoint. Exact routes should follow the existing API conventions.

Acceptance criteria

• Customer due date, approved baseline completion, current forecast completion, and actual completion are stored or exposed as distinct concepts.
• Creating or approving a schedule produces a baseline completion using operation dependencies and resource calendars.
• Active work orders receive a rolling completion forecast.
• Forecast calculations account for shift calendars, workstation availability, dependencies, and remaining operation work.
• Observed production rate is weighted by sample reliability and does not immediately replace the standard rate after a very small sample.
• Parallel operations use dependency and critical-path logic rather than a simple sum of all operation durations.
• Forecast output includes variance, confidence, status, calculation time, and machine-readable reason codes.
• Relevant production and resource events trigger recalculation.
• A periodic reconciliation job recalculates active work orders.
• Material forecast or risk-state changes are recorded in an auditable history without storing unchanged periodic results indefinitely.
• Warning, critical, and recovery states are deduplicated and use configurable thresholds.
• Work-order list, detail, and planner views display the baseline-versus-forecast distinction.
• Analyzers from issue [feat] AI Suggestions engine — rule-based production insights (Phase 1) #38 and issue [feat] AI Suggestions — schedule optimization, priority alignment & LLM integration (Phase 2) #39 can consume the forecast without duplicating calculation logic.
• No recommendation changes the approved schedule, personnel allocation, priority, or customer due date without authorized confirmation.
• Unit and feature tests cover sequential and parallel operations, shift boundaries, downtime, resource conflicts, small observed samples, recovery, and overdue scenarios.

Affected roles

• Operator
• Supervisor
• Admin

Operators provide execution data through the existing workflow, but this proposal does not require a new operator decision or planning interface. If operator-facing forecast information is later required, it should be introduced deliberately rather than added implicitly to the execution screen.

Alternatives considered

Use the customer due date as the planned completion

Rejected because a customer commitment is a business requirement, not the result of resource-constrained production scheduling. Automatically moving it would hide lateness.

Continuously overwrite the planned completion

Rejected because it removes the approved baseline and makes plan-versus-actual or plan-versus-forecast analysis impossible.

Use total standard production minutes as calendar duration

Rejected because summing all operation durations overstates lead time for parallel operations and ignores shifts, resource conflicts, and non-working periods.

Extrapolate only from produced quantity and elapsed time

Rejected as the authoritative method because small samples and setup activity can produce unstable forecasts, while future operations may have different rates and constraints.

Implement forecasting directly inside issue #38

Rejected because issue #38 should consume forecast and risk data rather than own scheduling, calendar, confidence, and forecast-history logic. Keeping the calculation in a separate domain service prevents duplication across suggestions, APIs, planner views, and reports.

Use an LLM to predict completion

Rejected for the authoritative calculation because results must be deterministic, testable, auditable, and reproducible. An LLM may explain deterministic results as an optional presentation layer.

Automatically reassign resources or move orders

Rejected for the initial scope. Recommendations should remain advisory and require authorized confirmation with an audit trail.

Additional context

Related work

• Issue [feat] Operations with dependencies — sequential and parallel operation scheduling #15: operation dependencies and sequential/parallel operation scheduling
• Issue [feat] Extend #15: workstation_type on steps + ISA-95 standard/actual times + pool dispatch #52: standard times, workstation type requirements, and workstation dispatch
• PR feat(steps): workstation type + ISA-95 standard/actual times + pool dispatch (#52) #237: implementation of issue [feat] Extend #15: workstation_type on steps + ISA-95 standard/actual times + pool dispatch #52 on the develop branch
• Issue [feat] AI Suggestions engine — rule-based production insights (Phase 1) #38: rule-based production insights, including overdue-risk detection
• Issue [feat] AI Suggestions — schedule optimization, priority alignment & LLM integration (Phase 2) #39: schedule optimization and planner-integrated suggestions

Issue #52 explicitly deferred predecessor_step_id, parallel-operation scheduling, and the Gantt timeline until the standard-time foundation was available. PR #237 has now delivered that foundation. This proposal builds on the calendar-aware scheduling result expected from issue #15 and supplies reliable forecast data to issue #38 and issue #39.

ISA-95 alignment

This feature belongs to ISA-95 Level 3 Manufacturing Operations Management:

• ERP/Level 4 remains the authority for customer demand, requested due date, BOM, and standard planning targets.
• MES/Level 3 calculates the operational schedule and rolling forecast from current execution and resource conditions.
• Forecast and schedule-risk information can be reported back to ERP without changing the customer commitment automatically.

Out of scope

• MRP and procurement planning
• Sales-order changes or automatic renegotiation of customer commitments
• Financial costing
• Fully autonomous personnel reassignment
• Fully autonomous schedule changes
• LLM-based authoritative forecasting

Open questions

1. Should the initial implementation require issue [feat] Operations with dependencies — sequential and parallel operation scheduling #15 to be completed, or should it support the current sequential step_number model first and add dependency-graph support later?
2. Should personnel availability constrain the first forecasting version, or be introduced as a second increment?
3. What change threshold should create a forecast-history snapshot?
4. Should approved schedule changes create a new baseline version or replace the current baseline while retaining an audit record?
5. Which existing schedule and alert services should own the integration points?