← All posts 中文版

PMClite Scheduling Engine Technical Deep Dive: Explainable, Traceable Finite-Capacity Scheduling

This is a complete walkthrough of the PMClite scheduling engine. It is a desktop-grade finite-capacity scheduling tool for PMC roles, and its core goal can be stated in one sentence: turn "when should this order be made, and on which line" from a matter of experience into a process that is computable, explainable, and traceable.

This article does not list features. It follows the code path layer by layer: how data precision is tiered, how production modes are unified into one conversion engine, how constraints filter the queue, how scheduling is committed to the calendar, how changes are simulated before they are applied, and what exactly the AI is responsible for. Every step can be inspected and intervened in independently. When you do not intervene, the default rules apply. This is the key to understanding the entire scheduling capability.

Precision model L0 / L2 / L2.5 Production modes 6 Constraint policy soft / hard / off AI role scores only, never dates

1. Positioning and Design Trade-offs

The scheduling module makes an explicit architectural trade-off: it does not attempt APS-level global optimization. Instead, it performs "explainable priority-driven scheduling with finite-capacity calendar consumption."

This trade-off comes from the target scenario: PMC in small and medium-sized manufacturers usually has only one full-time or part-time planner, and master data (labor hours, capacity, yield) is of limited precision. Any black-box optimization result cannot be trusted or corrected.

The scheduling chain in the code is therefore:

master data completeness check → constraint policy filtering → pre-schedule health check → priority-weighted sorting
→ per-line search for earliest feasible interval → calendar commitment → Gantt visualization → human review / fine-tuning

There is no step-skipping in this chain. Every scheduling result can be traced back along this chain to exactly which step and which parameter produced it.

2. Data Foundation: The L0 / L2 / L2.5 Three-Level Precision Model

The upper bound of scheduling precision is determined by master data. PMClite uses getDataLevel() to classify every product into one of three precision levels:

LevelCriteriaScheduling granularityTypical scenario
L0 No process row with type='process' and standardMinutes>0 under the product The whole order occupies a line as one continuous interval Product just created, routing not configured yet
L2 Process rows exist with per-unit time, but all postWaitMinutes=0 Process level, processes run back-to-back Pure machining processes with no inter-process wait
L2.5 Process rows exist, and at least one has postWaitMinutes>0 Process level + inter-process wait buffers Cooling after reflow soldering, curing after coating, resting before inspection

This tiering is not a labeling exercise. It directly determines which code path the engine takes:

The companion UI is renderSchedulePrecisionBadge(), which shows a live badge on the Gantt toolbar:

🎯 Precision · L2.5   L2.5 wait 12 · L2 process 5 · L0 whole-order 3

The statistics logic scans current "pending + in-progress" work orders and determines the level per order: if all are L2/L2.5, it is labeled "precision"; if ≥60%, "mixed"; otherwise "coarse."

The value of this badge is this: when the schedule looks too optimistic, the PMC's first reaction should be to look at this badge, not to doubt the algorithm.
Coarse scheduling means most work orders have no process data, and whole-order hours are estimated from product-level parameters. The source of error is in the data, not in the calculation.

3. Six Production Modes and the Unified Conversion Engine

The way "how much line time one unit of product occupies" is calculated differs completely across industries. PMClite abstracts this into six modes (PRODUCTION_MODES):

ModeFormula (effective time per unit)Applicable industries
fixed_takttaktSeconds / 3600 hours/unitSMT placement, food filling, pharmaceutical tableting
flexible_taktprocessMinutes / 60 / parallel stationsManual assembly, garment sewing, electronics assembly
single_stationcycleMinutes / 60 / parallel machinesInjection molding, stamping, CNC, printing
batchceil(qty/batch size) × batch cycleHeat treatment, electroplating, painting
continuousqty / hourly flow rateChemicals, paper, textiles
projectqty × days per set × daily hoursMolds, non-standard equipment, engineering installation

All mode differences are collapsed into a single function, calcResourceHours(). The entire system has only this one "duration calculation entry." This is deliberate: changing the mode does not change the algorithm, only the parameters.

6
production modes, one conversion entry
3
precision levels L0 / L2 / L2.5
60 days
per-order scheduling search limit

The conversion uniformly handles three things:

  1. Yield compensation: effectiveQty = planned qty / yieldRate. Actual input is always greater than planned output;
  2. Setup time: product-level setupMinutes is added once per start;
  3. Changeover time: line-level changeoverMinutes, from resourceParams.

An easy pitfall: capacity units

There is an explicit comment in the code (getLineCapacityPerDay) that deserves separate mention:

// Daily capacity = dailyHours × utilizationFactor
// Never multiply by parallelStations again
return baseDaily;

The reason: when calcProcessHours calculates process hours, it has already folded "per-unit time ÷ parallel stations" into the result. If daily capacity multiplies by stations again, capacity is inflated by N², and the schedule becomes unusably wrong.

This pitfall has appeared in many self-built scheduling tools. PMClite documents it in code comments and in the settings page hint ("daily available hours = daily hours × utilization, do not multiply by stations again").

Return values of process-level conversion

calcProcessHours() returns five quantities, clearly distinguished:

{
  runH,    // run hours
  setupH,  // setup hours
  waitH,   // post-wait hours
  busyH,   // = runH + setupH, the part that actually occupies work center capacity
  totalH,  // = runH + setupH + waitH, used only to display "from start to full completion"
}

The key point is that the calendar only deducts busyH. Post-wait (e.g. 30 minutes of cooling) does not occupy line capacity; it only pushes the start of the next process later.

This distinction makes L2.5 scheduling results significantly closer to shop-floor reality:
After reflow soldering, the oven is cooling. The SMT line can continue with the next batch, but the next process cannot start early. Capacity and lead time become two independent quantities.

4. Flow Types: Capacity Differences Between flow and batch

For the same multi-process product, the capacity model can be completely different. productionParams.flowType controls this branch:

flow — flow line

Multiple processes advance in parallel, and capacity is determined by the bottleneck process:

total hours = Σ(per-unit time) + (N-1) × bottleneck per-unit time + Σ setup time + changeover time

This is the model where "the first piece goes through the whole flow, and the rest flow out at the bottleneck rhythm." It matches SMT and assembly lines.

batch — batch / single machine

The whole batch completes process 1 before moving to process 2:

total hours = Σ(all time of each process)

This matches scenarios like heat treatment, electroplating, and painting, where "the whole furnace goes in and the whole furnace comes out."

This branch affects two places at once: getOrderTotalHours() determines whole-order hours, and scheduleByProcess() determines whether the calendar is consumed process by process. In flow mode, process segments overlap (you can see waterfall-style parallelism on the Gantt chart); in batch mode, process segments are serial.

5. Scheduling Engine: From Constraints to Calendar Commitment

5.1 Constraint policy: soft / hard / off

Before scheduling, there is a configurable filter (getConstraintPolicy()). Each of the four constraint categories can be set to one of three levels:

ConstraintSoft (default)HardOff
📦 Material kit completeness Schedule anyway, warn in health check Shortage orders do not enter the queue No check at all
📅 Delivery date Schedule anyway; output may exceed commitment Orders already past promised delivery are not scheduled No check at all
🔄 Changeover Warn on consecutive changeovers on the same line Warn only, no block (does not auto-block) No warning
📦 Batch merging Suggest merging Warn that merging must happen first No warning

Defaulting everything to soft is deliberate. In small and medium factories, material arrival, delivery commitments, and changeover times are not fully reliable. Hard constraints across the board tend to "deadlock" the schedule — every work order gets blocked, leaving the planner with no way forward. Soft constraints + health-check warnings + human judgment is the more practical default.

Actual hard-constraint blocking happens in _filterWOsByHardConstraints(), which returns { eligible, blocked }. Blocked work orders carry a reason ("3 material shortages (hard kit)") and are clearly reported via toast. Nothing disappears silently.

5.2 Pre-schedule health check

runSchedulePrecheck() is a pure diagnostic function that outputs a three-tier issue list: error / warn / info:

The health check itself does not block scheduling. It only triggers a confirmation before "one-click auto-schedule": Continue (ignore health check) or Cancel and view details.

This interaction detail matters — it shifts responsibility for "inaccurate schedule" from the algorithm to fixable data issues.

5.3 The one-click auto-schedule algorithm

The main loop of _autoSchedule() can be broken into five steps.

Step 1: Lock in-progress work orders

const lockedWOs = activeRows('workOrders').filter(w =>
    w.status === 'in-progress' && w.assignedLine && w.scheduledStart && w.scheduledEnd
);

In-progress work orders are not rescheduled, but their hours are spread evenly across days and written into lineCalendars, occupying the line calendar. This prevents one-click scheduling from inserting new orders into gaps on a line that is already producing.

Step 2: Priority-weighted sorting

wo._weight = (priorityScore[wo.priority] || 2) * 10 + urgency;

// urgency calculation
const diffDays = ceil((delivery - today) / 86400000);
urgency = diffDays < 0 ? 100 : (diffDays > 30 ? 0 : 30 - diffDays);

Weight = priority base score (high 30 / medium 20 / low 10) + delivery urgency (overdue 100, linearly increasing within 30 days). Processing is in descending weight order.

Step 3: Per-line search for earliest feasible interval

For each work order and each candidate line, the engine probes day by day starting from today, consuming daily capacity with the same logic as consumeCalendar, until the hours are exhausted. The search limit is 60 days, and the start date moves forward one working day after each failure.

Step 4: Serial / mixed-line control

This is the key switch that determines whether the schedule matches shop-floor intuition (db.pmcSettings.allowMixedLine):

Serial mode sacrifices line utilization in exchange for an executable schedule — the actual state of most small and medium factories is one order finished before the next begins.

Step 5: Choose the best line

Among all candidate lines, choose the one with the shortest occupied span (span < best.span). If all fail, the engine outputs detailed diagnostics: daily capacity of each line, average per-unit hours of the product, number of lines, working-day rules, and four troubleshooting suggestions.

5.4 Behavior on failure

Scheduling failure is not silent. When assignedCount === 0, a structured message is assembled:

❌ Could not assign a schedule to any work order

【Current configuration】
   • Daily capacity per line: SMT Line A = 6.8h, SMT Line B = 6.8h
   • Average per-unit hours of the product: 2.35 h/unit
   • Base daily capacity: 8h (daily capacity 8h × factor 85%)
   • Number of lines: 2
   • Working days: Monday to Friday only

【Troubleshooting suggestions】
   1. "Settings → Industry configuration": increase the line's "parallel stations"
   2. "Settings → PMC rules": increase "daily capacity" or "capacity factor"
   3. Check whether the product's per-unit hours are set too high
   4. Reduce the number of work orders in a single scheduling run
The design intent of this message is to let a planner who does not understand the algorithm fix the data themselves.
The worst way to handle scheduling failure is to "do nothing." Providing current configuration plus actionable suggestions lets users locate the problem themselves.

6. Sandbox Simulation: See the Impact Before Deciding to Change

After scheduling, the most common operation is "can this order move forward by two days?" PMClite's approach is a sandbox: all changes are simulated in memory first, listing displacements, conflicts, and delivery risks, and only committed after confirmation.

L0 sandbox (calcScheduleImpact)

Input: target line + new start date. Output:

Displaced work orders are by default shifted as a whole to the next working day after the target order's end date, preserving their original span.

L2.5 sandbox (scheduleByProcess + empty calendar simulation)

The process-level scheduling sandbox takes a different path: it calls scheduleByProcess with a brand-new empty calendar, so the simulation result never contaminates real scheduling data.

const simCalendars = {};
db.industryConfig.lines.forEach(l => {
    simCalendars[l] = {};
    simCapacityMap[l] = getLineCapacityPerDay(l);
});
const plan = scheduleByProcess(draft, simCalendars, simCapacityMap);

The simulation result then does three things:

  1. Merge original progress: reported completedQty / status are preserved and not overwritten by rescheduling;
  2. Conflict detection (_calcL25SandboxConflicts): compares each process segment's date interval on its work center against other active work orders;
  3. Delivery risk: end date of the last process vs sales order commitment date.

The preview UI (_renderL25SandboxPreview) has four sections: a process schedule comparison table (original vs new, changed rows marked "adjusted"), a summary bar (capacity consumed / completion date / main line / cycle time), a conflict list (up to 10 items), and a delivery-risk banner.

If conflicts exist before applying, another confirmation layer appears, explicitly listing conflicting work order numbers, with a "view conflicts first" exit — this detail avoids "applying and only then discovering lines are fighting."

7. Gantt Chart: Two Versions Coexist

PMClite keeps two Gantt charts, switched by a flag (localStorage.enable_gantt_v2). This is the product of incremental refactoring.

7.1 Classic table version (buildGanttHTML)

Conflict detection is optimized: _buildGanttConflictCache groups by line first, sorts within each group by scheduledStart ascending, then compares sequentially with early pruning (other.start > w.end triggers break). Groups typically contain 20–50 rows, so O(M²) is perfectly acceptable and an order of magnitude faster than global O(N²). A _buildGanttConflictCacheNaive rollback path is retained (window.__ganttConflictAlgo = 'naive').

7.2 v2 version (renderGanttV2)

The core change in v2 is the introduction of resource view / order waterfall view dual modes and timeline zoom.

The data transformation layer (convertWOToGanttData) converts work orders into task arrays:

Time coordinates use "hours" rather than dates: start = (timestamp - baseTs) / 3600000, multiplied by HOUR_WIDTH = DAY_WIDTH / 24 at render time. This lets day view and hour view share the same task data.

The dynamic time window (_ganttV2ComputeWindow) is a practical design:

dayWidth >= 360  → 8 days (hour view)
dayWidth <= 90   → 30 days (compact view)
otherwise        → 16 days (day view)

But the window is not fixed. It scans the startDate / endDate of incoming tasks and expands dynamically, leaving 2 days of buffer on each side, with a maximum span of 180 days to prevent a single anomalous record from blowing up the DOM.

Three zoom levels: compact (90px/day) / day (180px/day) / hour (360px/day). In hour view, the timeline header renders 0:00 / 6:00 / 12:00 / 18:00 / 24:00 ticks, and the track background overlays 6-hour dashed lines.

Order waterfall view (_ganttV2RenderOrderWaterfall) places all process segments of the same order on one row, framed by a light container bar for the overall span, with solid process bars rendered inside. Positions where postWaitMinutes > 0 between segments are marked with hatched dashed lines. If adjacent processes start on the same day, topOffset stacking staggers them to avoid visual overlap.

Delivery line: in order view, an orange dashed line is drawn at the right boundary of the linked sales order's deliveryDate, with a small "Delivery YYYY-MM-DD" flag. This is the most direct visual signal for the PMC.

Mobile fallback: when innerWidth < 768, the entire Gantt chart is replaced by a card list (_renderGanttV2MobileList), showing work order number, product, quantity, line, start/end dates, and a process progress bar per card. Touch dragging is unreliable on narrow screens; falling back directly is more practical than forcing support.

7.3 Dragging: two different paths

Dragging has completely different semantics for L0 and L2.5.

L0 drag (_handleL0Drag): drag the entire work order bar. On release, it does not change data directly. Instead, it puts the target date into window.__pendingSandboxStart and opens the sandbox simulation modal. The user sees displacements and risks before confirming. This design avoids "one shaky hand messing up the schedule."

L2.5 process-segment drag (_handleL25Drag): drag a single process. On release, _calcProcessDragImpact does three things:

  1. Validate that it cannot start earlier than the previous process's end + postWait;
  2. Link subsequent processes with the rule "preserve span, push later on conflict," generating an affected list;
  3. Check whether the last process crosses the sales order commitment date.

The confirmation modal lists each item as "process name: original schedule ⇒ new schedule (+N days)" along with a delivery-risk banner. After confirmation, processProgress and scheduledStart/End are written in one pass, and a trace record is written to the timeline table.

The classic table version has a third drag path (_initGanttDragDrop): it converts pixel movement into days, and on release uses confirm() to show a confirmation box with capacity conflict hints, directly changing dates on the work order table. This logic does not interfere with v2 dragging because the two Gantt charts are never rendered at the same time.

8. AI Scheduling: AI Scores, Local Engine Executes

This is the most easily misunderstood part. The division of labor in the code is very explicit:

AI only outputs priority scores and line suggestions. It does not output dates. Dates are computed by the local engine.

8.1 Prompt input and output

buildSchedulingContext() compresses work orders into a compact structure. Each entry contains: work order number, product, quantity, priority, status, production mode, mode parameter summary, estimated hours, kit status, and delivery date.

buildPMCPrompt() hard-codes scoring rules in the prompt (high = 30 / medium = 20 / low = 10; delivery ≤3 days +40; ≤7 days +25; overdue +50; kit complete +10; shortage -15; no BOM -30; in progress +5), and requires strict JSON output:

{
  "schedule": [
    {"woId": 1, "priorityScore": 85, "lineHint": "Line A", "reasoning": "Overdue order, prioritize"}
  ],
  "overallStrategy": "Overall strategy (within 30 characters)",
  "riskAlerts": ["Risk 1", "Risk 2"]
}

The prompt ends with a set of hard constraints: output JSON only, reasoning ≤20 characters, overallStrategy ≤30 characters, riskAlerts at most 3, schedule must include all incoming work orders, and the first and last characters must be braces.

8.2 Local execution

After receiving AI scores, runLocalScheduler() reorders work orders by descending score, then uses the same calendar-consumption logic as _autoSchedule. lineHint is used as the preferred line (if invalid, it falls back to all lines). The returned result includes processProgress (L2.5 process segments), which _applyAISchedule() writes in one pass.

8.3 Failure fallback

callAIChat() has several layers of defense:

When AI fails entirely, the modal offers three exits: Use local auto-schedule (calls _fallbackToLocalSchedule), Retry AI, Go to settings. The fallback path never leaves the user stuck on a failure page.

8.4 Rush-order rescheduling

The flow of _showInsertOrderModal → _insertWorkOrderAndReschedule is: create work order → save → automatically trigger _runAIScheduling(true, newWoId) after 800ms. The rush-order prompt additionally includes insertedWorkOrder and existingSchedule (line/date/quantity of in-progress work orders), and explicitly requires "prioritize the new work order's delivery date while minimizing adjustments to existing schedules."

9. Scheduling Quality Loop

Scheduling is not a one-time action. PMClite builds a loop from "after-the-fact observation" to "parameter calibration."

9.1 Scheduling KPIs (calcScheduleKPIs)

Four cards, all based on the last 30 days of data:

MetricCalculation
On-time delivery rateActual completion date of completed work orders vs linked sales order commitment date; on-time / (on-time + late)
Peak line loadNext 7 days, per line: accumulated scheduled work order hours / line capacity; take the maximum
Changeover countNumber of times adjacent work orders on the same line have different products
Average delayActual completion date vs planned completion date; average days overdue

9.2 Labor deviation monitoring (renderLaborHealthCard)

Deviation calculation at three granularities:

The grading thresholds are unified: |deviation| ≤ 10% healthy, 10%–30% elevated, > 30% large deviation.

The dashboard shows plant-wide average deviation, Top 5 product deviations, and Top 5 process deviations. Process rows have a "Calibrate" button.

9.3 Labor calibration wizard (_openLaborCalibrationWizard)

This is the most critical step in the loop. The flow:

  1. Collect the most recent 20 completed work order samples;
  2. Calculate total planned / total actual / overall deviation / sample standard deviation;
  3. Rule-based attribution (_attributeLaborDeviation): hours set too low, hours set too high, high variance, too few samples, missing post-wait, low whole-order precision;
  4. AI attribution (optional; falls back to rule-based on failure);
  5. Compute suggested value (_computeCalibratedValue): reverse-derive parameters by mode, weighted average, newer samples weighted higher;
  6. Impact preview (_calcCalibrationImpact): temporarily change parameters, recompute hours for unfinished work orders, estimate impact days at 8h/day.

When applied, only one field changes: for L0, the mode parameter in the product's productionParams; for L2.5, the process row's standardMinutes. Product-level calibration appends a record to calibrationHistory (keeping the most recent 20), traceable.

9.4 Changeover time learning (learnChangeoverTimes)

It samples from historical work orders adjacent different-product pairs where "same line, previous order completed, next order started, gap 0.2–8 hours," and takes the median of the gap (robust to outliers) as the suggested changeover time.

It is not applied automatically. The modal explicitly states: "The changeover gap is not necessarily equal to changeover time (it may include waiting, material changes, lunch breaks). Combine with shop-floor experience when judging."

9.5 Precision upgrade suggestions (_detectUpgradeSuggestions)

A rule engine with two types of suggestions:

Each suggestion has a button that jumps directly to the corresponding product's routing page.

9.6 Scheduling self-check (_runSchedulingSanityChecks)

There is a self-check button on the settings page. It runs typical examples from six industries to verify that calcResourceHours converts correctly:

ModeExampleExpected value
fixed_takt30 sec/unit × 1000 units8.33h
flexible_takt30 min/unit ÷ 10 stations × 1000 units50.00h
single_station45 sec/unit ÷ 3 machines × 1000 units4.17h
batch100 units/furnace × 8h/furnace × 250 units24.00h
continuous5 tons/h × 100 tons20.00h
project15 days/set × 8h/day × 3 sets360.00h

The error threshold is 0.5h; all must pass to show green. When scheduling results look abnormal, run this self-check first — it quickly rules out "the conversion function has been broken."

10. PMC Decision Desk: The Upstream of Scheduling

Before scheduling, the PMC needs to know "what must be handled today." The decision desk (renderPmcDecision) is an event-driven queue. Events are derived by a front-end rule engine (derivePmcEvents) and only run in host/standalone mode:

RuleTrigger conditionSeverity
Material shortageActive work order fails kit checkStarts within 48h → red, otherwise amber
Delivery riskPlanned completion date > sales order commitment datered
Capacity overloadLine load on a given day > 100%>115% → red, otherwise amber

Each event has a fingerprint for deduplication (same work order + same shortage list is not generated twice), an sla_hours (red = 4h, amber = 24h), and an owner_role (shortage goes to purchasing; delivery and capacity go to PMC).

Events can be escalated (generate collaboration records, push to DingTalk/WeCom groups, SLA timeout checked every 60 seconds with a flashing red dot), closed, and viewed with a full history. Report-type events (report_confirm) have a dedicated button; confirming them directly updates the work order's actualQty / actualHours / progress / status.

11. Engineering Details

A few implementation points that do not affect functionality but affect experience:

12. Getting Started Path

For a freshly installed instance, the shortest path is:

  1. Settings → Industry wizard (_openIndustryWizard): choose an industry, answer 3–5 numbers (how many lines, how many stations/machines per line, how many hours per day, per-unit cycle), automatically configure line resourceParams and product default productionParams, and set default constraint policies;
  2. Products → Apply industry template (_openBatchApplyTemplate): batch-apply default parameters to products without parameters. Products that already have processes are unchecked by default;
  3. BOM → Routing: configure processes for products that need precision scheduling (sequence, process name, work center, per-unit time, setup, post-wait);
  4. Production → Schedule health check: run once and fix blocking issues;
  5. Production → One-click auto-schedule: after scheduling, check the precision badge and Gantt chart;
  6. Production → Decision desk: start here daily to handle shortage/delivery/capacity events.

Closing Thoughts

The technical characteristic of PMClite's scheduling module is: every layer of calculation is explainable, every decision is traceable, and every failure has a clear reason output.

It does not pursue "computing the theoretical optimum." It pursues "computing a plan that the PMC can understand, modify, and take responsibility for." Six production modes unified into one conversion entry, a three-level precision model, configurable soft/hard constraints, sandbox-before-change, AI scoring without dates — all these designs point to the same principle:

Translate algorithmic uncertainty into information the user can judge.
The value of a scheduling tool is not in making decisions for people, but in laying out the consequences of each decision in advance.

Want to run this scheduling logic on your own data?

On-premise · One-time purchase · Live in 1–3 days · 30-day full-feature trial

Explore PMClite →

Algorithms and implementation details referenced in this article reflect our public demo builds; the shipped product takes precedence. PMClite is an independent product and has no commercial relationship with any third-party vendor mentioned in this article.