Integração de Stock Level no Cálculo de Preço

Data: 2025-01-06
Objetivo: Documentar como o stock_level é integrado no cálculo de preço do Pricing Agent

📋 Visão Geral

O stock_level (nível de estoque) agora é considerado no cálculo de preço, permitindo ajustar descontos baseado na situação de estoque do produto:

• Estoque Alto (high): Aumenta desconto para escoar estoque
• Estoque Normal (normal): Sem ajuste no desconto
• Estoque Baixo (low): Reduz desconto para evitar esgotamento

🏗️ Arquitetura

1. Tabela pricing_stock_level_factors

Armazena fatores multiplicadores para cada nível de estoque:

CREATE TABLE pricing_stock_level_factors (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    stock_level ENUM('low', 'normal', 'high') NOT NULL,
    factor DECIMAL(9,6) NOT NULL DEFAULT 1.000000,
    description VARCHAR(255),
    is_active TINYINT(1) DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_stock_level (stock_level)
);

Valores Padrão:
- low: 0.800000 (reduz desconto em 20%)
- normal: 1.000000 (sem ajuste)
- high: 1.200000 (aumenta desconto em 20%)

2. Stored Procedure sp_price_compute_v8

A stored procedure foi atualizada para:

1. Receber p_stock_level como parâmetro de entrada
2. Buscar fator na tabela pricing_stock_level_factors
3. Aplicar fator no cálculo do desconto final
4. Retornar o_stock_level_factor na saída

Fórmula Atualizada:

Desconto_Final = Desconto_Allowed × Curve_Factor × Stock_Level_Factor

3. Engine Python (agents/pricing/engine.py)

O engine foi atualizado para:

1. Normalizar stock_level (fallback para 'normal' se inválido)
2. Passar stock_level para a stored procedure
3. Retornar stock_level_factor na resposta

4. Context Builder (agents/pricing/context.py)

O context builder já busca stock_level automaticamente da tabela product_classification quando não fornecido no payload.

🔄 Fluxo de Cálculo

1. Context Builder busca stock_level (se não fornecido)
   ↓
2. Engine normaliza stock_level ('low' | 'normal' | 'high')
   ↓
3. Stored Procedure busca fator em pricing_stock_level_factors
   ↓
4. Aplica fator no desconto final:
   Desconto_Final = Desconto_Base × Curve_Factor × Stock_Level_Factor
   ↓
5. Retorna stock_level_factor na resposta

📊 Exemplo de Cálculo

Cenário:
- Desconto Base: 15%
- Curve Factor (A): 1.2
- Stock Level: high (fator: 1.2)

Cálculo:
1. Desconto Base: 15%
2. Após Curve Factor: 15% × 1.2 = 18%
3. Após Stock Level Factor: 18% × 1.2 = 21.6%

Outro Cenário:
- Desconto Base: 15%
- Curve Factor (A): 1.2
- Stock Level: low (fator: 0.8)

Cálculo:
1. Desconto Base: 15%
2. Após Curve Factor: 15% × 1.2 = 18%
3. Após Stock Level Factor: 18% × 0.8 = 14.4%

🎯 Lógica de Negócio

Estoque Alto (high)

• Objetivo: Escoar estoque parado
• Fator: > 1.0 (aumenta desconto)
• Exemplo: Fator 1.2 = +20% no desconto

Estoque Normal (normal)

• Objetivo: Manter equilíbrio
• Fator: 1.0 (sem ajuste)
• Exemplo: Fator 1.0 = sem alteração

Estoque Baixo (low)

• Objetivo: Preservar estoque
• Fator: < 1.0 (reduz desconto)
• Exemplo: Fator 0.8 = -20% no desconto

📝 Como Configurar

1. Criar Tabela e Valores Padrão

mysql -u user -p csuite_pricing < csuite-pricing/sql/create_pricing_stock_level_factors.sql

2. Atualizar Stored Procedure

mysql -u user -p csuite_pricing < csuite-pricing/sql/add_stock_level_to_sp_price_compute_v8.sql

3. Ajustar Fatores (Opcional)

-- Aumentar desconto para estoque alto
UPDATE pricing_stock_level_factors
SET factor = 1.300000  -- +30% no desconto
WHERE stock_level = 'high';

-- Reduzir desconto para estoque baixo
UPDATE pricing_stock_level_factors
SET factor = 0.700000  -- -30% no desconto
WHERE stock_level = 'low';

🔍 Verificação

Verificar se Tabela Existe

SELECT * FROM csuite_pricing.pricing_stock_level_factors;

Testar Stored Procedure

SET @o_stock_level_factor = NULL;

CALL csuite_pricing.sp_price_compute_v8(
    1,           -- brand_id
    123,         -- customer_id
    456,         -- sku_id
    100.00,      -- PT
    80.00,       -- PISO
    'A',         -- machine_curve
    'high',      -- stock_level (NOVO)
    10,          -- sku_qty
    1000.00,     -- order_value
    @o_status,
    @o_reason,
    @o_final_price,
    @o_discount_allowed,
    @o_tier_code,
    @o_market_context,
    @o_volume_12m,
    @o_brand_role,
    @o_curve_factor,
    @o_stock_level_factor  -- NOVO
);

SELECT @o_stock_level_factor AS stock_level_factor;

📚 Referências

• STOCK_LEVEL_INTEGRATION.md - Integração de stock_level na tabela product_classification
• STOCK_METRICS_CALCULATION.md - Cálculo de métricas de estoque
• PRICING_AGENT.md - Documentação completa do Pricing Agent

✅ Checklist de Implementação

• [x] Criar tabela pricing_stock_level_factors
• [x] Inserir valores padrão
• [x] Atualizar stored procedure sp_price_compute_v8
• [x] Atualizar engine.py para passar stock_level
• [x] Atualizar context.py para buscar stock_level automaticamente
• [ ] Criar interface admin para gerenciar fatores
• [ ] Atualizar documentação do Pricing Agent
• [ ] Testes de integração

Última atualização: 2025-01-06