@jetta/blocks-allocator 0.0.0-stage → 0.1.0-0

package/src/validation/Item_Continuation_Lock_Flag.js

@@ -0,0 +1,52 @@
+const ITEM_CONTINUATION_LOCK_KEY = 'allocation.blocks.enable_item_continuation_lock'
+const CONFLICT_MESSAGE =
+    'allocation.blocks.enable_item_continuation_lock must be false when relational_allocation_enabled is true'
+
+/**
+ * Returns true when relational allocation is enabled.
+ * @param {object} algoritmo
+ * @returns {boolean}
+ */
+function is_relational_allocation_enabled(algoritmo)
+{
+    const raw = algoritmo?.relational_allocation_enabled
+    return raw === true || raw === 'true'
+}
+
+/**
+ * Resolves whether item continuation lock is enabled.
+ * Omitted values default to true (legacy behavior).
+ * @param {object} algoritmo
+ * @returns {boolean}
+ */
+function is_item_continuation_lock_enabled(algoritmo)
+{
+    const raw = algoritmo?.[ITEM_CONTINUATION_LOCK_KEY]
+    if (raw === undefined)
+    {
+        return true
+    }
+    return raw === true || raw === 'true'
+}
+
+/**
+ * Returns true when relational allocation conflicts with continuation lock.
+ * @param {object} algoritmo
+ * @returns {boolean}
+ */
+function has_relational_continuation_lock_conflict(algoritmo)
+{
+    if (!is_relational_allocation_enabled(algoritmo))
+    {
+        return false
+    }
+    return is_item_continuation_lock_enabled(algoritmo)
+}
+
+module.exports = {
+    ITEM_CONTINUATION_LOCK_KEY,
+    CONFLICT_MESSAGE,
+    is_relational_allocation_enabled,
+    is_item_continuation_lock_enabled,
+    has_relational_continuation_lock_conflict
+}

package/src/validation/Item_Validation.js

@@ -0,0 +1,29 @@
+const Validation = require('./Validation')
+const Invalid_Input_Type_Exception = require('./exceptions/Invalid_Input_Type_Exception')
+
+class Item_Validation extends Validation
+{
+    #item_list
+    constructor(item_list)
+    {
+        super()
+        this.#item_list = item_list
+    }
+
+    validate()
+    {
+        this.#has_any_longeron()
+    }
+
+    #has_any_longeron()
+    {
+        const has_longeron = this.#item_list.some(item => item.tipo.toLowerCase() === 'longarina')
+
+        if (has_longeron)
+        {
+            throw new Invalid_Input_Type_Exception()
+        }
+    }
+}
+
+module.exports = Item_Validation

package/src/validation/Relational_Colocation_Validator.js

@@ -0,0 +1,60 @@
+const Relational_Colocation_Violation_Exception = require('../exceptions/Relational_Colocation_Violation_Exception')
+const Cargo_Profile = require('../models/Cargo_Profile')
+
+function validate_transport_colocation(transport)
+{
+    if (!Cargo_Profile.enforce_relational_group_co_location())
+    {
+        return
+    }
+
+    const groups = collect_allocated_groups(transport)
+
+    for (const [group_id, sequences] of groups.entries())
+    {
+        const unique_sequences = [...new Set(sequences)]
+        if (unique_sequences.length > 1)
+        {
+            throw new Relational_Colocation_Violation_Exception(
+                {
+                    relational_group_id: group_id,
+                    container_sequences: unique_sequences
+                }
+            )
+        }
+    }
+}
+
+function collect_allocated_groups(transport)
+{
+    const groups = new Map()
+
+    for (const sequence of transport.get_container_sequence_list())
+    {
+        const container = transport.get_container_by_sequence(sequence)
+        const allocated_items = container.get_allocated_items()
+
+        for (const allocated_item of allocated_items)
+        {
+            const source_item = allocated_item.get_allocation_item()
+            const group_id = source_item.get_relational_group_id()
+            if (!group_id)
+            {
+                continue
+            }
+
+            if (!groups.has(group_id))
+            {
+                groups.set(group_id, [])
+            }
+            groups.get(group_id).push(sequence)
+        }
+    }
+
+    return groups
+}
+
+module.exports = {
+    validate_transport_colocation,
+    collect_allocated_groups
+}

package/src/validation/Relational_Completeness_Validator.js

@@ -0,0 +1,146 @@
+const Cargo_Profile = require('../models/Cargo_Profile')
+const Relational_Allocation_Incomplete_Exception = require('../exceptions/Relational_Allocation_Incomplete_Exception')
+
+function validate_relational_completeness(transport, item_list)
+{
+    if (!Cargo_Profile.enforce_relational_group_co_location())
+    {
+        return
+    }
+
+    const allocated_counts = count_allocated_by_user_id(transport)
+    const groups = build_group_expectations(item_list, allocated_counts)
+    if (groups.size === 0)
+    {
+        return
+    }
+
+    for (const [group_id, group] of groups.entries())
+    {
+        validate_group_completeness(group_id, group, allocated_counts)
+    }
+}
+
+function build_group_expectations(item_list, allocated_counts)
+{
+    const groups = new Map()
+
+    for (const item of item_list)
+    {
+        const group_id = item.get_relational_group_id && item.get_relational_group_id()
+        if (!group_id)
+        {
+            continue
+        }
+
+        if (!groups.has(group_id))
+        {
+            groups.set(group_id, {
+                links: item.get_relational_links(),
+                expected_counts: {}
+            })
+        }
+
+        const user_id = item.get_user_id()
+        const group = groups.get(group_id)
+        const already_allocated = allocated_counts[user_id] || 0
+        const remaining = item.get_amount()
+        group.expected_counts[user_id] = already_allocated + remaining
+    }
+
+    return groups
+}
+
+function count_allocated_by_user_id(transport)
+{
+    const counts = {}
+
+    for (const sequence of transport.get_container_sequence_list())
+    {
+        const container = transport.get_container_by_sequence(sequence)
+        for (const allocated_item of container.get_allocated_items())
+        {
+            const source_item = allocated_item.get_allocation_item()
+            const user_id = source_item.get_user_id()
+            counts[user_id] = (counts[user_id] || 0) + 1
+        }
+    }
+
+    return counts
+}
+
+function validate_group_completeness(group_id, group, allocated_counts)
+{
+    const user_ids = Object.keys(group.links || {})
+    const allocated_in_group = user_ids.map(user_id => allocated_counts[user_id] || 0)
+    const total_allocated = allocated_in_group.reduce((sum, count) => sum + count, 0)
+
+    if (total_allocated === 0)
+    {
+        return
+    }
+
+    if (!is_valid_integer_multiple(allocated_in_group, user_ids, group.links))
+    {
+        throw new Relational_Allocation_Incomplete_Exception(
+            {
+                relational_group_id: group_id,
+                allocated_counts: pick_counts(user_ids, allocated_counts),
+                expected_counts: group.expected_counts
+            }
+        )
+    }
+}
+
+function is_valid_integer_multiple(allocated_counts, user_ids, links)
+{
+    let reference_k = null
+
+    for (let index = 0; index < user_ids.length; index++)
+    {
+        const user_id = user_ids[index]
+        const allocated = allocated_counts[index]
+        const link_qty = links[user_id]
+
+        if (link_qty == null || link_qty <= 0)
+        {
+            return false
+        }
+
+        if (allocated % link_qty !== 0)
+        {
+            return false
+        }
+
+        const k = allocated / link_qty
+        if (k < 1 || !Number.isInteger(k))
+        {
+            return false
+        }
+
+        if (reference_k == null)
+        {
+            reference_k = k
+        }
+        else if (reference_k !== k)
+        {
+            return false
+        }
+    }
+
+    return reference_k != null
+}
+
+function pick_counts(user_ids, allocated_counts)
+{
+    const picked = {}
+    for (const user_id of user_ids)
+    {
+        picked[user_id] = allocated_counts[user_id] || 0
+    }
+    return picked
+}
+
+module.exports = {
+    validate_relational_completeness
+}

package/src/validation/Relational_Continuation_Lock_Validation.js

@@ -0,0 +1,37 @@
+const Validation = require('./Validation')
+const Relational_Config_Mismatch_Exception = require('../exceptions/Relational_Config_Mismatch_Exception')
+const { has_relational_continuation_lock_conflict } = require('./Item_Continuation_Lock_Flag')
+
+/**
+ * Rejects relational allocation when item continuation lock remains enabled.
+ */
+class Relational_Continuation_Lock_Validation extends Validation
+{
+    #algoritmo
+
+    /**
+     * @param {object} input_data - Parsed allocation request.
+     */
+    constructor(input_data)
+    {
+        super()
+        this.#algoritmo = input_data?.config?.algoritmo || {}
+    }
+
+    /**
+     * Validates the relational / continuation-lock config combination.
+     * @returns {void}
+     * @throws {Relational_Config_Mismatch_Exception}
+     */
+    validate()
+    {
+        if (!has_relational_continuation_lock_conflict(this.#algoritmo))
+        {
+            return
+        }
+
+        throw new Relational_Config_Mismatch_Exception()
+    }
+}
+
+module.exports = Relational_Continuation_Lock_Validation

package/src/validation/Relational_Proportional_Normalizer.js

@@ -0,0 +1,194 @@
+const Cargo_Profile = require('../models/Cargo_Profile')
+
+/**
+ * Trims excess allocated items so each relational group matches a valid integer k.
+ * @param {object} transport
+ * @param {object[]} item_list
+ */
+function normalize_relational_proportional_allocation(transport, item_list)
+{
+    if (!Cargo_Profile.enforce_relational_group_co_location())
+    {
+        return
+    }
+
+    const groups = build_relational_groups(item_list)
+
+    for (const sequence of transport.get_container_sequence_list())
+    {
+        const container = transport.get_container_by_sequence(sequence)
+        trim_container_relational_excess(container, groups, item_list)
+    }
+}
+
+function build_relational_groups(item_list)
+{
+    const groups = new Map()
+
+    for (const item of item_list)
+    {
+        const group_id = item.get_relational_group_id && item.get_relational_group_id()
+        if (!group_id)
+        {
+            continue
+        }
+
+        if (!groups.has(group_id))
+        {
+            groups.set(group_id, {
+                links: item.get_relational_links(),
+                items_by_user_id: new Map()
+            })
+        }
+
+        groups.get(group_id).items_by_user_id.set(item.get_user_id(), item)
+    }
+
+    return groups
+}
+
+function trim_container_relational_excess(container, groups, item_list)
+{
+    const allocated_items = container.get_allocated_items()
+
+    for (const [group_id, group] of groups.entries())
+    {
+        const user_ids = Object.keys(group.links || {})
+        const indices_by_user_id = collect_indices_by_user_id(allocated_items, user_ids, group_id)
+        const counts = user_ids.map(user_id => indices_by_user_id.get(user_id)?.length || 0)
+        const k = compute_valid_k_from_counts(counts, user_ids, group.links)
+
+        if (k < 1)
+        {
+            continue
+        }
+
+        if (is_valid_integer_multiple(counts, user_ids, group.links))
+        {
+            continue
+        }
+
+        const remove_indices = []
+
+        for (const user_id of user_ids)
+        {
+            const target = group.links[user_id] * k
+            const indices = indices_by_user_id.get(user_id) || []
+            const excess = indices.length - target
+
+            if (excess > 0)
+            {
+                remove_indices.push(...indices.slice(-excess))
+            }
+        }
+
+        remove_indices.sort((left, right) => right - left)
+
+        const restored_counts = new Map()
+
+        for (const index of remove_indices)
+        {
+            const user_id = allocated_items[index]?.get_allocation_item()?.get_user_id()
+            if (user_id)
+            {
+                restored_counts.set(user_id, (restored_counts.get(user_id) || 0) + 1)
+            }
+
+            allocated_items.splice(index, 1)
+        }
+
+        for (const [user_id, count] of restored_counts.entries())
+        {
+            const stock_item = group.items_by_user_id.get(user_id)
+            if (stock_item)
+            {
+                stock_item.update_amount(stock_item.get_amount() + count)
+            }
+        }
+    }
+}
+
+function collect_indices_by_user_id(allocated_items, user_ids, group_id)
+{
+    const indices_by_user_id = new Map()
+    const user_id_set = new Set(user_ids)
+
+    for (let index = 0; index < allocated_items.length; index++)
+    {
+        const source_item = allocated_items[index].get_allocation_item()
+        const user_id = source_item.get_user_id()
+        const item_group_id = source_item.get_relational_group_id && source_item.get_relational_group_id()
+
+        if (!user_id_set.has(user_id) || item_group_id !== group_id)
+        {
+            continue
+        }
+
+        if (!indices_by_user_id.has(user_id))
+        {
+            indices_by_user_id.set(user_id, [])
+        }
+
+        indices_by_user_id.get(user_id).push(index)
+    }
+
+    return indices_by_user_id
+}
+
+function compute_valid_k_from_counts(counts, user_ids, links)
+{
+    let k = Infinity
+
+    for (let index = 0; index < user_ids.length; index++)
+    {
+        const user_id = user_ids[index]
+        const allocated = counts[index]
+        const link_qty = links[user_id]
+
+        if (allocated > 0 && link_qty > 0)
+        {
+            k = Math.min(k, Math.floor(allocated / link_qty))
+        }
+    }
+
+    return k === Infinity ? 0 : k
+}
+
+function is_valid_integer_multiple(allocated_counts, user_ids, links)
+{
+    let reference_k = null
+
+    for (let index = 0; index < user_ids.length; index++)
+    {
+        const user_id = user_ids[index]
+        const allocated = allocated_counts[index]
+        const link_qty = links[user_id]
+
+        if (link_qty == null || link_qty <= 0 || allocated === 0)
+        {
+            continue
+        }
+
+        if (allocated % link_qty !== 0)
+        {
+            return false
+        }
+
+        const k = allocated / link_qty
+
+        if (reference_k == null)
+        {
+            reference_k = k
+        }
+        else if (reference_k !== k)
+        {
+            return false
+        }
+    }
+
+    return reference_k != null
+}
+
+module.exports = {
+    normalize_relational_proportional_allocation
+}

package/src/validation/Validation.js

@@ -0,0 +1,9 @@
+class Validation
+{
+    validate()
+    {
+        throw new Error('this is a virtual method.')
+    }
+}
+
+module.exports = Validation

package/src/validation/Validation_Runner.js

@@ -0,0 +1,20 @@
+const Item_Validation = require('./Item_Validation')
+const Relational_Continuation_Lock_Validation = require('./Relational_Continuation_Lock_Validation')
+
+function _assemble_validation_list(input_data)
+{
+    return [
+        new Item_Validation(input_data.items),
+        new Relational_Continuation_Lock_Validation(input_data)
+    ]
+}
+
+
+module.exports = function(input_data)
+{
+    const validation_list = _assemble_validation_list(input_data)
+    for (const validation of validation_list)
+    {
+        validation.validate()
+    }
+}

package/src/validation/exceptions/Invalid_Block_Module_Config_Exception.js

@@ -0,0 +1,14 @@
+const { build_message_entry } = require('../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+
+class Invalid_Block_Module_Config_Exception extends Error
+{
+    constructor()
+    {
+        const message_key = ALLOCATOR_MESSAGE.INVALID_BLOCK_MODULE_CONFIG
+        super(message_key)
+        this.message_entry = build_message_entry(message_key)
+    }
+}
+
+module.exports = Invalid_Block_Module_Config_Exception

package/src/validation/exceptions/Invalid_Input_Exception.js

@@ -0,0 +1,14 @@
+const { build_message_entry } = require('../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+
+class Invalid_Input_Exception extends Error
+{
+    constructor()
+    {
+        const message_key = ALLOCATOR_MESSAGE.INVALID_INPUT
+        super(message_key)
+        this.message_entry = build_message_entry(message_key)
+    }
+}
+
+module.exports = Invalid_Input_Exception

package/src/validation/exceptions/Invalid_Input_Type_Exception.js

@@ -0,0 +1,14 @@
+const { build_message_entry } = require('../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+
+class Invalid_Input_Type_Exception extends Error
+{
+    constructor()
+    {
+        const message_key = ALLOCATOR_MESSAGE.INVALID_INPUT_TYPE
+        super(message_key)
+        this.message_entry = build_message_entry(message_key)
+    }
+}
+
+module.exports = Invalid_Input_Type_Exception

package/src/validation/schemas/allocated_item_schema.js

@@ -0,0 +1,18 @@
+const { z } = require('zod')
+
+/**
+ * One pre-placed item on a container row (`containers[*].items[*]`), English geometry field names.
+ */
+const allocated_item_schema = z.looseObject({
+    _id: z.string().min(1),
+    x: z.number().nonnegative(),
+    y: z.number().nonnegative(),
+    z: z.number().nonnegative(),
+    w: z.number().positive(),
+    h: z.number().positive(),
+    d: z.number().positive(),
+    wg: z.number().positive(),
+    supported_weight: z.number().nonnegative()
+})
+
+module.exports = allocated_item_schema