@jetta/blocks-allocator 0.2.1-0 → 0.2.1-2

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/candidate_item_fits_axle_load.js

@@ -0,0 +1,19 @@
+const layout_fits_axle_load = require('./layout_fits_axle_load')
+
+/**
+ * Whether placing this allocated item on top of pending axle items stays within axle caps.
+ * @param {object} data - Chooser bag with transport, container, pending_axle_items.
+ * @param {object} allocated_item
+ * @returns {boolean}
+ */
+function candidate_item_fits_axle_load(data, allocated_item)
+{
+    const pending_axle_items = data.pending_axle_items ?? []
+    return layout_fits_axle_load({
+        transport: data.transport,
+        container: data.container,
+        extra_items: pending_axle_items.concat(allocated_item)
+    })
+}
+
+module.exports = candidate_item_fits_axle_load

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/clone_env_with_layout_items.js

@@ -0,0 +1,26 @@
+const clone = require('../../../tools/Clone')
+const map_allocated_item_to_axle_wire = require('./map_allocated_item_to_axle_wire')
+
+/**
+ * Deep-clones the axle env template and writes current plus extra items per container.
+ * @param {object} transport
+ * @param {object} current_container
+ * @param {object[]} extra_items - Pending wall, earlier slots, and candidate for current container.
+ * @returns {object}
+ */
+function clone_env_with_layout_items(transport, current_container, extra_items)
+{
+    const env = clone(transport.get_axle_env_template())
+    const extra_item_list = extra_items ?? []
+    for (const container_data of env.containers ?? [])
+    {
+        const sequence = Number(container_data.sequencia)
+        const live_container = transport.get_containers().get(sequence)
+        const committed_items = live_container?.get_allocated_items?.() ?? []
+        const pending_items = live_container === current_container ? extra_item_list : []
+        container_data.items = committed_items.concat(pending_items).map(map_allocated_item_to_axle_wire)
+    }
+    return env
+}
+
+module.exports = clone_env_with_layout_items

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/evaluate_layout_axle_load.js

@@ -0,0 +1,63 @@
+const { calculate_weight_on_axles_physics } = require('@jetta/axle-load-calculator')
+const { gt } = require('@jetta/number-compare')
+const { Logger } = require('@jetta/logger')
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const clone_env_with_layout_items = require('./clone_env_with_layout_items')
+const axle_load_exceeds_limit = require('./axle_load_exceeds_limit')
+const { max_axle_load_ratio } = axle_load_exceeds_limit
+
+const logger = new Logger('Axle Load Slot Gate')
+
+/**
+ * Hottest axle ratio for the layout, or undefined when physics cannot run.
+ * @param {object} data
+ * @param {object} data.transport
+ * @param {object} data.container
+ * @param {object[]} data.extra_items
+ * @returns {number|undefined}
+ */
+function score_layout_axle_load(data)
+{
+    const env = clone_env_with_layout_items(data.transport, data.container, data.extra_items)
+    try
+    {
+        return ratio_from_physics(env)
+    }
+    catch (error)
+    {
+        logger.warn(`axle calculator rejected layout: ${error.message}`)
+        return undefined
+    }
+}
+
+/**
+ * Runs axle physics for the current layout plus extra items on the active container.
+ * @param {object} data
+ * @param {object} data.transport
+ * @param {object} data.container
+ * @param {object[]} data.extra_items
+ * @returns {boolean} True when no axle exceeds the folga-adjusted cap.
+ */
+function evaluate_layout_axle_load(data)
+{
+    const ratio = score_layout_axle_load(data)
+    if (ratio === undefined)
+    {
+        return false
+    }
+    return gt(ratio, 1) === false
+}
+
+/**
+ * @param {object} env
+ * @returns {number}
+ */
+function ratio_from_physics(env)
+{
+    const output = calculate_weight_on_axles_physics({ envs: [env] })
+    const folga_percent = Cargo_Profile.axle_weight_gap_percent()
+    return max_axle_load_ratio(output.envs[0], folga_percent)
+}
+
+module.exports = evaluate_layout_axle_load
+module.exports.score_layout_axle_load = score_layout_axle_load

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/layout_fits_axle_load.js

@@ -0,0 +1,36 @@
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const evaluate_layout_axle_load = require('./evaluate_layout_axle_load')
+
+/**
+ * Returns whether the layout may be committed under the optional axle slot gate.
+ * @param {object} data
+ * @param {object} [data.transport]
+ * @param {object} [data.container]
+ * @param {object[]} [data.extra_items]
+ * @returns {boolean}
+ */
+function layout_fits_axle_load(data)
+{
+    if (!Cargo_Profile.enable_axle_load_slot_gate())
+    {
+        return true
+    }
+    if (!transport_has_axles(data.transport))
+    {
+        return true
+    }
+    return evaluate_layout_axle_load(data)
+}
+
+/**
+ * @param {object|undefined} transport
+ * @returns {boolean}
+ */
+function transport_has_axles(transport)
+{
+    const env = transport?.get_axle_env_template?.()
+    return Array.isArray(env?.eixos) && env.eixos.length > 0
+}
+
+module.exports = layout_fits_axle_load
+module.exports.transport_has_axles = transport_has_axles

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/map_allocated_item_to_axle_wire.js

@@ -0,0 +1,21 @@
+/**
+ * Maps an allocated item to the ms-faixas axle-calculator item contract.
+ * Longitudinal chassis position is JSON `y` (allocator `z`).
+ * @param {object} allocated_item
+ * @returns {object}
+ */
+function map_allocated_item_to_axle_wire(allocated_item)
+{
+    return {
+        id: allocated_item.get_id(),
+        x: allocated_item.get_x(),
+        y: allocated_item.get_z(),
+        z: allocated_item.get_y(),
+        peso: allocated_item.get_weight(),
+        comprimento: allocated_item.get_length(),
+        largura: allocated_item.get_width(),
+        altura: allocated_item.get_height()
+    }
+}
+
+module.exports = map_allocated_item_to_axle_wire

package/src/Allocation_Optimization/item_consumption_heuristic/select_axle_balanced_slot_item.js

@@ -0,0 +1,143 @@
+const { lt } = require('@jetta/number-compare')
+const { get_item, remove_item_from_candidate_list } = require('./slot_candidate_order')
+const { score_without_commit, commit_scored_candidate } = require('./slot_candidate_acceptance')
+
+/**
+ * Legal SKU across every weight band with the lowest hottest-axle ratio.
+ * Ties keep band order, then candidate order inside the band.
+ * @param {object} data
+ * @param {object} context
+ * @returns {object|undefined}
+ */
+function commit_lowest_ratio_across_bands(data, context)
+{
+    const ranked = rank_every_band(data, context)
+    for (const selected of ranked)
+    {
+        const committed = commit_scored_candidate(data, context.container, selected)
+        if (committed)
+        {
+            return committed
+        }
+    }
+    return undefined
+}
+
+/**
+ * Best legal SKU across every band. Does not commit stacking.
+ * @param {object} data
+ * @param {object} context
+ * @returns {{ allocated_item: object, ratio: number, allocation_item: object }|undefined}
+ */
+function lowest_ratio_across_bands(data, context)
+{
+    const ranked = rank_every_band(data, context)
+    return ranked[0]
+}
+
+/**
+ * Preferred SKU scored without a stacking commit.
+ * @param {object} data
+ * @param {object} context
+ * @returns {{ allocated_item: object, ratio: number, allocation_item: object }|undefined}
+ */
+function score_preferred(data, context)
+{
+    const allocation_item = data.item_list.find(item => item.get_id() === data.previous_chosen_item_id)
+    if (!allocation_item)
+    {
+        return undefined
+    }
+    return score_without_commit(data, context, allocation_item)
+}
+
+/**
+ * @param {{ ratio: number }|undefined} preferred
+ * @param {{ ratio: number }|undefined} best
+ * @returns {boolean}
+ */
+function preferred_wins(preferred, best)
+{
+    if (!preferred)
+    {
+        return false
+    }
+    if (!best)
+    {
+        return true
+    }
+    return lt(best.ratio, preferred.ratio) === false
+}
+
+/**
+ * @param {object} data
+ * @param {object} context
+ * @returns {object[]}
+ */
+function rank_every_band(data, context)
+{
+    const scored = []
+    for (const band of context.ordered_bands)
+    {
+        scored.push(...rank_band(data, context, band.items.slice()))
+    }
+    return rank_by_ratio(scored)
+}
+
+/**
+ * @param {object} data
+ * @param {object} context
+ * @param {object[]} pending
+ * @returns {object[]}
+ */
+function rank_band(data, context, pending)
+{
+    const scored = []
+    while (pending.length > 0)
+    {
+        const allocation_item = get_item(pending, data.qty_of_slots, context.container)
+        const candidate = score_without_commit(data, context, allocation_item)
+        if (candidate)
+        {
+            scored.push(candidate)
+        }
+        remove_item_from_candidate_list(pending, allocation_item)
+    }
+    return rank_by_ratio(scored)
+}
+
+/**
+ * @param {{ ratio: number }[]} scored
+ * @returns {{ ratio: number }[]}
+ */
+function rank_by_ratio(scored)
+{
+    const ranked = []
+    for (const candidate of scored)
+    {
+        insert_by_ratio(ranked, candidate)
+    }
+    return ranked
+}
+
+/**
+ * @param {{ ratio: number }[]} ranked
+ * @param {{ ratio: number }} candidate
+ * @returns {void}
+ */
+function insert_by_ratio(ranked, candidate)
+{
+    let index = 0
+    while (index < ranked.length && lt(ranked[index].ratio, candidate.ratio))
+    {
+        index += 1
+    }
+    ranked.splice(index, 0, candidate)
+}
+
+module.exports = {
+    commit_lowest_ratio_across_bands,
+    lowest_ratio_across_bands,
+    score_preferred,
+    preferred_wins
+}

package/src/Allocation_Optimization/item_consumption_heuristic/select_slot_item.js

@@ -0,0 +1,149 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const No_Suitable_Item_Exception = require('../block_builder/exceptions/No_Suitable_Item_Exception')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+const { distribute_items_by_weight_range } = require('./Weight_Slot_Distribution')
+const {
+    resolve_choose_item_heuristic_context,
+    format_slot_label_for_exception
+} = require('./Choose_Item_Heuristic_Context')
+const {
+    calculate_total_stack_slots,
+    sort_stacking_slots_by_proximity
+} = require('./Stack_Slot_Calculator')
+const { get_item, remove_item_from_candidate_list } = require('./slot_candidate_order')
+const { try_accept_candidate, commit_scored_candidate } = require('./slot_candidate_acceptance')
+const {
+    commit_lowest_ratio_across_bands,
+    lowest_ratio_across_bands,
+    score_preferred,
+    preferred_wins
+} = require('./select_axle_balanced_slot_item')
+
+/**
+ * Chooses a slot item. When the axle gate is on, the legal SKU with the lowest hottest-axle ratio wins.
+ * @param {object} data
+ * @returns {object}
+ */
+function select_slot_item(data)
+{
+    const context = build_band_context(data)
+    if (Cargo_Profile.enable_axle_load_slot_gate())
+    {
+        const selected = commit_lowest_ratio_across_bands(data, context)
+        if (!selected)
+        {
+            throw unsuitable(context.slot)
+        }
+        return selected
+    }
+    for (const band of context.ordered_bands)
+    {
+        const selected = first_accepted_in_band(data, context, band.items)
+        if (selected)
+        {
+            return selected
+        }
+    }
+    throw unsuitable(context.slot)
+}
+
+/**
+ * Same-id preference. Under the axle gate, that SKU wins only when it is not strictly hotter.
+ * @param {object} data
+ * @returns {object}
+ */
+function select_preferred_or_heuristic(data)
+{
+    if (!Cargo_Profile.enable_axle_load_slot_gate())
+    {
+        return preferred_or_first(data)
+    }
+    return preferred_or_balanced(data)
+}
+
+/**
+ * @param {object} data
+ * @returns {object}
+ */
+function preferred_or_first(data)
+{
+    const { container, item_list, previous_chosen_item_id, item_position } = data
+    const allocation_item = item_list.find(item => item.get_id() === previous_chosen_item_id)
+    if (allocation_item)
+    {
+        const accepted_item = try_accept_candidate(data, container, allocation_item, item_position)
+        if (accepted_item)
+        {
+            return accepted_item
+        }
+    }
+    return select_slot_item(data)
+}
+
+/**
+ * @param {object} data
+ * @returns {object}
+ */
+function preferred_or_balanced(data)
+{
+    const context = build_band_context(data)
+    const preferred = score_preferred(data, context)
+    const best = lowest_ratio_across_bands(data, context)
+    const winner = preferred_wins(preferred, best) ? preferred : best
+    if (!winner)
+    {
+        throw unsuitable(context.slot)
+    }
+    return commit_scored_candidate(data, context.container, winner)
+}
+
+/**
+ * @param {object} data
+ * @returns {object}
+ */
+function build_band_context(data)
+{
+    const { slot, container, item_position } = resolve_choose_item_heuristic_context(data)
+    const total_slots = calculate_total_stack_slots(container.get_height(), slot)
+    const stacking_slots = distribute_items_by_weight_range(data.item_list, total_slots)
+    const ordered_bands = sort_stacking_slots_by_proximity(stacking_slots, slot.get_y(), slot.get_height())
+    return { slot, container, item_position, ordered_bands }
+}
+
+/**
+ * @param {object} data
+ * @param {object} context
+ * @param {object[]} candidate_items
+ * @returns {object|undefined}
+ */
+function first_accepted_in_band(data, context, candidate_items)
+{
+    while (candidate_items.length > 0)
+    {
+        const allocation_item = get_item(candidate_items, data.qty_of_slots, context.container)
+        const accepted_item = try_accept_candidate(data, context.container, allocation_item, context.item_position)
+        if (accepted_item)
+        {
+            return accepted_item
+        }
+        remove_item_from_candidate_list(candidate_items, allocation_item)
+    }
+    return undefined
+}
+
+/**
+ * @param {object} slot
+ * @returns {No_Suitable_Item_Exception}
+ */
+function unsuitable(slot)
+{
+    return new No_Suitable_Item_Exception(
+        ALLOCATOR_MESSAGE.NO_SUITABLE_ITEM,
+        [format_slot_label_for_exception(slot)]
+    )
+}
+
+module.exports = {
+    select_slot_item,
+    select_preferred_or_heuristic
+}

package/src/Allocation_Optimization/item_consumption_heuristic/slot_candidate_acceptance.js

@@ -0,0 +1,110 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const Allocated_Item = require('../../models/Allocated_Item')
+const candidate_item_fits_axle_load = require('./axle_load/candidate_item_fits_axle_load')
+const candidate_item_axle_score = require('./axle_load/candidate_item_axle_score')
+
+/**
+ * Builds the allocated item at the slot position.
+ * @param {object} allocation_item
+ * @param {object} item_position
+ * @returns {object}
+ */
+function build_allocated_item(allocation_item, item_position)
+{
+    return new Allocated_Item(allocation_item, item_position.x, item_position.y, item_position.z)
+}
+
+/**
+ * Accepts the first legal candidate and commits stacking.
+ * @param {object} data
+ * @param {object} container
+ * @param {object} allocation_item
+ * @param {object} item_position
+ * @returns {object|undefined}
+ */
+function try_accept_candidate(data, container, allocation_item, item_position)
+{
+    const allocated_item = build_allocated_item(allocation_item, item_position)
+    if (!candidate_item_fits_axle_load(data, allocated_item))
+    {
+        return undefined
+    }
+    if (should_defer_loose_on_block_stacking_validation(data.block))
+    {
+        return allocated_item
+    }
+    if (!container.is_a_valid_stacking(allocated_item))
+    {
+        return undefined
+    }
+    return allocated_item
+}
+
+/**
+ * Scores a candidate without writing the stacking index.
+ * @param {object} data
+ * @param {object} context
+ * @param {object} allocation_item
+ * @returns {{ allocated_item: object, ratio: number, allocation_item: object }|undefined}
+ */
+function score_without_commit(data, context, allocation_item)
+{
+    const allocated_item = build_allocated_item(allocation_item, context.item_position)
+    const score = candidate_item_axle_score(data, allocated_item)
+    if (!score.fits || !stacking_probe_allows(data, context.container, allocated_item))
+    {
+        return undefined
+    }
+    return { allocated_item, ratio: score.ratio, allocation_item }
+}
+
+/**
+ * Commits the chosen candidate into the live stacking index.
+ * @param {object} data
+ * @param {object} container
+ * @param {{ allocated_item: object }} scored
+ * @returns {object|undefined}
+ */
+function commit_scored_candidate(data, container, scored)
+{
+    if (should_defer_loose_on_block_stacking_validation(data.block))
+    {
+        return scored.allocated_item
+    }
+    if (!container.is_a_valid_stacking(scored.allocated_item))
+    {
+        return undefined
+    }
+    return scored.allocated_item
+}
+
+/**
+ * @param {object} data
+ * @param {object} container
+ * @param {object} allocated_item
+ * @returns {boolean}
+ */
+function stacking_probe_allows(data, container, allocated_item)
+{
+    if (should_defer_loose_on_block_stacking_validation(data.block))
+    {
+        return true
+    }
+    if (typeof container.probe_stacking === 'function')
+    {
+        return container.probe_stacking(allocated_item)
+    }
+    return container.is_a_valid_stacking(allocated_item)
+}
+
+function should_defer_loose_on_block_stacking_validation(block)
+{
+    return Cargo_Profile.stack_loose_on_tie_ratio_blocks()
+        && block?.get_slot_list?.().length === 1
+}
+
+module.exports = {
+    try_accept_candidate,
+    score_without_commit,
+    commit_scored_candidate
+}

package/src/Allocation_Optimization/item_consumption_heuristic/slot_candidate_order.js

@@ -0,0 +1,49 @@
+const No_Available_Items_Exception = require('./exceptions/No_Available_Items_Exception')
+const No_Slots_For_Items_Exception = require('./exceptions/No_Slots_For_Items_Exception')
+const { order_items_by_capacity_bias } = require('./Capacity_Bias_Item_Order')
+
+/**
+ * Removes one candidate from the working list.
+ * @param {object[]} candidate_item_list
+ * @param {object} allocation_item
+ * @returns {void}
+ */
+function remove_item_from_candidate_list(candidate_item_list, allocation_item)
+{
+    const index = candidate_item_list.indexOf(allocation_item)
+    if (index > -1)
+    {
+        candidate_item_list.splice(index, 1)
+    }
+}
+
+/**
+ * Next candidate in the existing capacity-bias order.
+ * @param {object[]} item_list
+ * @param {number|undefined} qty_of_slots
+ * @param {object} container
+ * @returns {object}
+ */
+function get_item(item_list, qty_of_slots, container)
+{
+    if (qty_of_slots === undefined)
+    {
+        throw new No_Slots_For_Items_Exception()
+    }
+    if (item_list.length === 0)
+    {
+        throw new No_Available_Items_Exception()
+    }
+    const ordered_item_list = order_items_by_capacity_bias(item_list, container)
+    const preferable_item_list = ordered_item_list.filter(item => item.get_amount() >= qty_of_slots)
+    if (preferable_item_list.length > 0)
+    {
+        return preferable_item_list[0]
+    }
+    return ordered_item_list[0]
+}
+
+module.exports = {
+    get_item,
+    remove_item_from_candidate_list
+}

package/src/models/Cargo_Profile.js

@@ -81,6 +81,33 @@ class Cargo_Profile
         return str_to_bool(this.#instance['allocation.blocks.enable_item_continuation_lock'], true)
     }
 
+    /**
+     * Whether slot item choice rejects SKUs that would overload axles.
+     * Defaults to false when omitted or when no cargo profile is loaded.
+     * @returns {boolean}
+     */
+    static enable_axle_load_slot_gate()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return false
+        }
+        return str_to_bool(this.#instance['allocation.blocks.enable_axle_load_slot_gate'], false)
+    }
+
+    /**
+     * Axle slack percent applied as pesoMaxFinal * (1 + percent / 100).
+     * @returns {number}
+     */
+    static axle_weight_gap_percent()
+    {
+        if (Cargo_Profile.#instance === null)
+        {
+            return 0
+        }
+        return finite_float_from_string_or_number(this.#instance.folga_de_peso_nos_eixos, 0)
+    }
+
     static enable_key_item_mapping()
     {
         return str_to_bool(this.#instance['allocation.blocks.preferential.enable'], true)

package/src/models/transport/Container.js

@@ -87,6 +87,17 @@ class Container extends Space
         return this.#stacking_feasibility_checker.validate_stackings(item_data)
     }
 
+    /**
+     * Checks stacking on a clone so the live index stays unchanged.
+     * @param {object} item
+     * @returns {boolean}
+     */
+    probe_stacking(item)
+    {
+        const probe = this.#stacking_feasibility_checker.clone()
+        return probe.validate_stackings(create_input(item))
+    }
+
     /**
      * Drops provisional stacking commits left by failed slot/wall attempts.
      * Restores the pre-attempt checkpoint when stacking was touched; otherwise a no-op.