@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/validation/schemas/allocation_request_schema.js

@@ -0,0 +1,178 @@
+const Invalid_Input_Exception = require('../exceptions/Invalid_Input_Exception')
+const { VALID_DENSITY_GROUP_STRATEGIES } = require('../../Allocation_Optimization/density_groups/Density_Groups_Strategy')
+const {
+    collect_block_module_config_errors,
+} = require('../validate_block_module_config')
+
+/**
+ * Zod schemas for the top-level allocation request. `Blocks_Wall_Allocation` calls `parse_allocation_request`
+ * before `State_Builder`; transport factories assume validated non-empty `envs` and container lists.
+ */
+const { z } = require('zod')
+const { transport_env_schema } = require('./transport_env_schema')
+const { item_schema } = require('./item_schema')
+
+const DENSITY_GROUPS_ENABLE_KEY = 'allocation.items.density_groups.enable'
+const DENSITY_GROUPS_COUNT_KEY = 'allocation.items.density_groups.count'
+const DENSITY_GROUPS_STRATEGY_KEY = 'allocation.items.density_groups.strategy'
+const DENSITY_GROUPS_WEIGHT_AHEAD_THRESHOLD_PP_KEY = 'allocation.items.density_groups.weight_ahead_threshold_pp'
+const DENSITY_GROUPS_SPACE_AHEAD_THRESHOLD_PP_KEY = 'allocation.items.density_groups.space_ahead_threshold_pp'
+
+function is_density_groups_enabled(algoritmo)
+{
+    const raw = algoritmo[DENSITY_GROUPS_ENABLE_KEY]
+    return raw === true || raw === 'true'
+}
+
+const algoritmo_empty_space_merge_schema = z.looseObject({
+    empty_space_merge_gap_percent_width: z.coerce.number().min(0).max(100).optional(),
+    empty_space_merge_gap_percent_length: z.coerce.number().min(0).max(100).optional(),
+    empty_space_merge_max_vertical_offset_mm: z.coerce.number().nonnegative().optional()
+})
+
+const algoritmo_density_groups_schema = z.looseObject({
+    [DENSITY_GROUPS_ENABLE_KEY]: z.union([z.boolean(), z.string()]).optional(),
+    [DENSITY_GROUPS_COUNT_KEY]: z.coerce.number().int().optional(),
+    [DENSITY_GROUPS_STRATEGY_KEY]: z.string().optional(),
+    [DENSITY_GROUPS_WEIGHT_AHEAD_THRESHOLD_PP_KEY]: z.coerce.number().optional(),
+    [DENSITY_GROUPS_SPACE_AHEAD_THRESHOLD_PP_KEY]: z.coerce.number().optional()
+}).superRefine((algoritmo, ctx) =>
+{
+    if (!is_density_groups_enabled(algoritmo))
+    {
+        return
+    }
+    const count = algoritmo[DENSITY_GROUPS_COUNT_KEY]
+    if (count !== undefined && (count < 2 || count > 10))
+    {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'allocation.items.density_groups.count must be between 2 and 10 when density groups are enabled',
+            path: [DENSITY_GROUPS_COUNT_KEY]
+        })
+    }
+    const strategy = algoritmo[DENSITY_GROUPS_STRATEGY_KEY]
+    if (strategy !== undefined && !VALID_DENSITY_GROUP_STRATEGIES.includes(strategy))
+    {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'allocation.items.density_groups.strategy must be round_robin or adaptive when density groups are enabled',
+            path: [DENSITY_GROUPS_STRATEGY_KEY]
+        })
+    }
+    validate_density_group_threshold_pp(
+        algoritmo,
+        ctx,
+        DENSITY_GROUPS_WEIGHT_AHEAD_THRESHOLD_PP_KEY,
+        'weight_ahead_threshold_pp'
+    )
+    validate_density_group_threshold_pp(
+        algoritmo,
+        ctx,
+        DENSITY_GROUPS_SPACE_AHEAD_THRESHOLD_PP_KEY,
+        'space_ahead_threshold_pp'
+    )
+})
+
+/**
+ * Validates an adaptive density-group threshold expressed in percentage points.
+ * @param {object} algoritmo - Parsed algoritmo object.
+ * @param {import('zod').RefinementCtx} ctx - Zod refinement context.
+ * @param {string} key - Flat config key.
+ * @param {string} label - Human-readable field label for error messages.
+ * @returns {void}
+ */
+function validate_density_group_threshold_pp(algoritmo, ctx, key, label)
+{
+    const value = algoritmo[key]
+    if (value === undefined)
+    {
+        return
+    }
+    if (value < 0 || value > 100)
+    {
+        ctx.addIssue({
+            code: 'custom',
+            message: `allocation.items.density_groups.${label} must be between 0 and 100 when density groups are enabled`,
+            path: [key]
+        })
+    }
+}
+
+const cargo_config_schema = z.looseObject({
+    algoritmo: z.record(z.string(), z.unknown())
+        .and(algoritmo_empty_space_merge_schema)
+        .and(algoritmo_density_groups_schema)
+})
+
+const BLOCK_MODULE_LIST_KEY = 'allocation.blocks.block_module_list'
+
+const allocation_request_schema = z.looseObject({
+    config: cargo_config_schema,
+    envs: z.array(transport_env_schema).min(1),
+    items: z.array(item_schema).min(1),
+    available_blocks: z.array(z.string()).optional()
+}).superRefine((request, ctx) =>
+{
+    const algoritmo = request.config?.algoritmo
+    if (!algoritmo)
+    {
+        return
+    }
+
+    const errors = collect_block_module_config_errors(algoritmo, request.available_blocks)
+    errors.forEach((message) =>
+    {
+        ctx.addIssue({
+            code: 'custom',
+            message,
+            path: ['config', 'algoritmo', BLOCK_MODULE_LIST_KEY]
+        })
+    })
+})
+
+function format_zod_error(zod_error)
+{
+    return zod_error.issues.map(issue =>
+    {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)'
+        return `${path}: ${issue.message}`
+    }).join('; ')
+}
+
+/**
+ * Parses allocation request JSON without throwing.
+ * @param {unknown} input_data - Raw request body.
+ * @returns {{ success: true, data: object } | { success: false, error: object }}
+ */
+function safe_parse_allocation_request(input_data)
+{
+    return allocation_request_schema.safeParse(input_data)
+}
+
+/**
+ * Parses and returns typed data, or throws {Invalid_Input_Exception} with a flattened Zod message.
+ * @param {unknown} input_data - Raw request body.
+ * @returns {object} Parsed payload (unknown keys preserved where `.passthrough()` applies).
+ * @throws {Invalid_Input_Exception} When validation fails; the error message contains flattened Zod issues.
+ */
+function parse_allocation_request(input_data)
+{
+    const result = safe_parse_allocation_request(input_data)
+    if (!result.success)
+    {
+        const { Logger } = require('@jetta/logger')
+        const logger = new Logger('allocation_request_schema')
+        logger.error(`Invalid allocation input: ${format_zod_error(result.error)}`)
+        throw new Invalid_Input_Exception()
+    }
+    return result.data
+}
+
+module.exports = {
+    allocation_request_schema,
+    cargo_config_schema,
+    parse_allocation_request,
+    safe_parse_allocation_request,
+    format_zod_error
+}

package/src/validation/schemas/container_row_schema.js

@@ -0,0 +1,16 @@
+const { z } = require('zod')
+const allocated_item_schema = require('./allocated_item_schema')
+
+/**
+ * One container row under `envs[*].containers` (Portuguese field names from the API).
+ */
+const container_row_schema = z.looseObject({
+    sequencia: z.coerce.number(),
+    largura: z.coerce.number().positive(),
+    altura: z.coerce.number().positive(),
+    comprimento: z.coerce.number().positive(),
+    pesoDeCarga: z.coerce.number().positive(),
+    items: z.array(allocated_item_schema).optional()
+})
+
+module.exports = { container_row_schema }

package/src/validation/schemas/item_schema.js

@@ -0,0 +1,60 @@
+const { z } = require('zod')
+
+function item_has_weight(data)
+{
+    const w = data.peso ?? data.weight ?? data.wg
+    return typeof w === 'number' && !Number.isNaN(w)
+}
+
+function item_width_ok(data)
+{
+    const v = data.largura ?? data.width ?? data.w
+    return typeof v === 'number' && !Number.isNaN(v) && v > 0
+}
+
+function item_height_ok(data)
+{
+    const v = data.altura ?? data.height ?? data.h
+    return typeof v === 'number' && !Number.isNaN(v) && v > 0
+}
+
+function item_length_ok(data)
+{
+    const v = data.comprimento ?? data.length ?? data.d
+    return typeof v === 'number' && !Number.isNaN(v) && v > 0
+}
+
+function validate_allocation_item_phys(data, ctx)
+{
+    if (!item_has_weight(data))
+    {
+        ctx.addIssue('Item must include peso, weight, or wg')
+    }
+    if (!item_width_ok(data))
+    {
+        ctx.addIssue('Item must include positive largura, width, or w')
+    }
+    if (!item_height_ok(data))
+    {
+        ctx.addIssue('Item must include positive altura, height, or h')
+    }
+    if (!item_length_ok(data))
+    {
+        ctx.addIssue('Item must include positive comprimento, length, or d')
+    }
+}
+
+/**
+ * One SKU in `input_data.items` (to allocate). Extra API fields are kept via `.passthrough()`.
+ */
+const item_schema = z.looseObject({
+    _id: z.string().min(1),
+    qtd: z.coerce.number().nonnegative(),
+    stacking: z.record(z.string(), z.unknown()),
+    pesoMaxSuportado: z.coerce.number().nonnegative(),
+    empilhamentoMaximo: z.coerce.number().nonnegative(),
+    restricoes: z.record(z.string(), z.unknown()).optional().default({}),
+    rotacao: z.record(z.string(), z.boolean())
+}).superRefine(validate_allocation_item_phys)
+
+module.exports = { item_schema }

package/src/validation/schemas/transport_env_schema.js

@@ -0,0 +1,19 @@
+const { z } = require('zod')
+const { container_row_schema } = require('./container_row_schema')
+
+const corner_props_schema = z.object({
+    espacoSuperiorFrente: z.coerce.number().nonnegative(),
+    espacoSuperiorPorta: z.coerce.number().nonnegative()
+})
+
+/**
+ * One transport environment from `input_data.envs` (first entry is used for blocks + transport factory).
+ */
+const transport_env_schema = z.looseObject({
+    _id: z.string(),
+    tipo: z.string().min(1),
+    containers: z.array(container_row_schema).min(1),
+    props: corner_props_schema.optional()
+})
+
+module.exports = { transport_env_schema }

package/src/validation/validate_block_module_config.js

@@ -0,0 +1,147 @@
+const { VALID_BLOCK_MODULE_NAMES } = require('../input_preparation/block_preparation/Block_Module_Name')
+const str_to_bool = require('../tools/String_To_Boolean')
+
+const Invalid_Block_Module_Config_Exception = require('./exceptions/Invalid_Block_Module_Config_Exception')
+
+const BLOCK_MODULE_LIST_KEY = 'allocation.blocks.block_module_list'
+const USE_UNITARY_ITEMS_KEY = 'allocation.blocks.use_unitary_items_as_block'
+const ENABLE_MANUAL_BLOCKS_KEY = 'allocation.blocks.enable_manual_blocks'
+const MANUAL_BLOCKS_MODULE = 'manual_blocks'
+
+/**
+ * @param {object} algoritmo - Cargo profile algoritmo object.
+ * @returns {boolean} Whether manual blocks are enabled (default true).
+ */
+function is_manual_blocks_enabled(algoritmo)
+{
+    return str_to_bool(algoritmo[ENABLE_MANUAL_BLOCKS_KEY], true)
+}
+
+/**
+ * @param {string} module_name - Candidate module name.
+ * @returns {boolean} True when the module is not manual_blocks.
+ */
+function is_not_manual_blocks(module_name)
+{
+    return module_name !== MANUAL_BLOCKS_MODULE
+}
+
+/**
+ * Builds the effective block module list without mutating the input config.
+ * @param {object} algoritmo - Cargo profile algoritmo object.
+ * @param {string[]|undefined} available_blocks - Optional manual block paths.
+ * @returns {string[]}
+ */
+function build_effective_block_module_list(algoritmo, available_blocks)
+{
+    const enable_manual_blocks = is_manual_blocks_enabled(algoritmo)
+    let block_module_list = [...(algoritmo[BLOCK_MODULE_LIST_KEY] || [])]
+
+    if (enable_manual_blocks && available_blocks !== undefined && available_blocks.length > 0)
+    {
+        block_module_list.push(MANUAL_BLOCKS_MODULE)
+    }
+    if (!enable_manual_blocks)
+    {
+        block_module_list = block_module_list.filter(is_not_manual_blocks)
+    }
+
+    const use_unitary_items_as_block = algoritmo[USE_UNITARY_ITEMS_KEY] === false ? false : true
+    const create_unitary_blocks = str_to_bool(use_unitary_items_as_block)
+    if (create_unitary_blocks || block_module_list.length === 0)
+    {
+        block_module_list.push('single_item_blocks')
+    }
+
+    return [...new Set(block_module_list)]
+}
+
+/**
+ * @param {string} module_name - Module name to validate.
+ * @returns {string|null} Error message when invalid; null when valid.
+ */
+function unknown_module_message(module_name)
+{
+    if (VALID_BLOCK_MODULE_NAMES.includes(module_name))
+    {
+        return null
+    }
+
+    return `Unknown module: "${module_name}". Valid modules: ${VALID_BLOCK_MODULE_NAMES.join(', ')}`
+}
+
+/**
+ * Validates explicit and effective block module configuration.
+ * @param {object} algoritmo - Cargo profile algoritmo object.
+ * @param {string[]|undefined} available_blocks - Optional manual block paths.
+ * @returns {string[]} Validation error messages.
+ */
+function collect_block_module_config_errors(algoritmo, available_blocks)
+{
+    const errors = []
+
+    if (Object.prototype.hasOwnProperty.call(algoritmo, BLOCK_MODULE_LIST_KEY))
+    {
+        const explicit_list = algoritmo[BLOCK_MODULE_LIST_KEY]
+        if (!Array.isArray(explicit_list))
+        {
+            errors.push(`${BLOCK_MODULE_LIST_KEY} must be an array`)
+        }
+        else
+        {
+            explicit_list.forEach((module_name, index) =>
+            {
+                const message = unknown_module_message(module_name)
+                if (message)
+                {
+                    errors.push(`${BLOCK_MODULE_LIST_KEY}[${index}]: ${message}`)
+                }
+            })
+        }
+    }
+
+    const effective_list = build_effective_block_module_list(algoritmo, available_blocks)
+    if (effective_list.length === 0)
+    {
+        errors.push(`${BLOCK_MODULE_LIST_KEY}: must resolve to a non-empty module list`)
+        return errors
+    }
+
+    effective_list.forEach((module_name) =>
+    {
+        const message = unknown_module_message(module_name)
+        if (message)
+        {
+            errors.push(message)
+        }
+    })
+
+    return [...new Set(errors)]
+}
+
+/**
+ * Validates block module configuration or throws.
+ * @param {object} algoritmo - Cargo profile algoritmo object.
+ * @param {string[]|undefined} available_blocks - Optional manual block paths.
+ * @throws {Invalid_Block_Module_Config_Exception} When configuration is invalid.
+ * @returns {void}
+ */
+function validate_block_module_config(algoritmo, available_blocks)
+{
+    const errors = collect_block_module_config_errors(algoritmo, available_blocks)
+    if (errors.length > 0)
+    {
+        const { Logger } = require('@jetta/logger')
+        const logger = new Logger('validate_block_module_config')
+        logger.error(errors.join('; '))
+        throw new Invalid_Block_Module_Config_Exception()
+    }
+}
+
+module.exports = {
+    BLOCK_MODULE_LIST_KEY,
+    ENABLE_MANUAL_BLOCKS_KEY,
+    build_effective_block_module_list,
+    collect_block_module_config_errors,
+    validate_block_module_config,
+}