Skip to content

Customizacao Recursiva Produtos

Jump to bottom
luizkim edited this page Aug 15, 2026 · 1 revision

Customização recursiva de produtos (CustomizeScreen)

Documentação técnica do fluxo que permite personalizar grupos de um produto-filho (e níveis seguintes) a partir da CustomizeScreen, com persistência e apresentação fiéis da árvore no pedido/carrinho.

Issues de origem (RC5 v1.4.19):

Repo Issue Papel
ui-products#6 CustomizeScreen + modal aninhado UI de entrada
ui-shop#5 Integração SHOP + Cart Canal Shop
ui-orders#5 Cart / OrderDetails árvore PDV / Histórico
api-platform-orders#5 Persistência recursiva Backend

Problema de negócio

Antes, ao selecionar uma opção que também era um produto customizável (ex.: batata com grupos próprios), o usuário conseguia marcar a opção, mas não conseguia configurar os grupos internos do filho. O backend e o Cart materializavam apenas o primeiro nível (sub_products imediatos).

Solução (visão geral)

CustomizeScreen (raiz)
  └─ NestedCustomizationModal (filho / neto / …)
       └─ domain/customizationTree (normalização, preço, validade)
            └─ payload recursivo → OrderProductService
                 └─ OrderProductTreeNormalizer / Consolidator / PriceCalculator
                      └─ Cart / OrderDetails (árvore fiel)
  1. UI (ui-products) detecta opção com grupos próprios e abre superfície aninhada (NestedCustomizationModal).
  2. Domínio customizationTree.js normaliza IDs, quantidades, mínimos/máximos por grupo, cálculo de preço (sum / biggest / average / free) e valida a árvore (incluindo descendentes inválidos).
  3. Backend (api-platform-orders) aceita e consolida a árvore recursiva no comando autoritativo de produtos do pedido (OrderProductService + helpers OrderProductTree*).
  4. Apresentação (ui-orders / ui-shop) renderiza pai → incorporados → filhos → netos conforme vínculos reais (orderProductComponents / orderProduct), preservando quantidades absolutas em todos os níveis.

Contratos principais (frontend)

Artefato Responsabilidade
src/react/pages/CustomizeScreen.js Tela raiz de customização do produto
src/react/components/NestedCustomizationModal.js Modal adaptativo para níveis filhos
src/react/domain/customizationTree.js Árvore unitária, preço, validade de grupos, sub_products
Testes NestedCustomizationModal.test.js, customizationTree.test.js

Funções de domínio relevantes:

  • buildUnitCustomizationTree / findUnitTreeNode
  • calculateCustomizationGroupPrice / calculateCustomizationTreePrice
  • resolveGroupMinimum / resolveGroupMaximum
  • summarizeCustomizationGroups (status de grupo e descendentes)

Contratos principais (backend)

Artefato Responsabilidade
OrderProductService Entrada do comando de produtos do pedido
OrderProductTreeNormalizer Normaliza payload recursivo
OrderProductTreeConsolidator Consolida vínculos pai/filho
OrderProductTreePriceCalculator Preço da árvore
OrderProductServiceHelpers Helpers extraídos (limite de tamanho de arquivo)
Testes OrderProductServiceRecursiveTreeTest, consolidation/price

A API continua sendo o comando autoritativo: a UI envia a árvore; o serviço valida produto+grupo em cada nível e persiste a hierarquia em OrderProduct.

Fluxo operacional (resumo)

  1. Usuário abre customização do produto raiz (PDV, Shop ou fluxo equivalente).
  2. Seleciona opção que possui grupos próprios → abre NestedCustomizationModal.
  3. Completa grupos do filho (mínimos obrigatórios, máximos, preço).
  4. Confirma nível → árvore sobe para o pai; preço e validade agregam descendentes.
  5. Salvar pedido → backend consolida árvore recursiva.
  6. Cart / OrderDetails exibem a hierarquia completa (não mais lista rasa de componentes).

Visões de app (APP_TYPE)

Visão Comportamento
PDV / Manager CustomizeScreen + Cart em ui-orders
Shop Mesma CustomizeScreen compartilhada; Cart do Shop alinhado à árvore transacional (ui-shop#5)
Histórico / OrderDetails Renderização fiel da árvore persistida

Não há regra de negócio distinta por APP_TYPE para a recursão: o contrato de árvore é compartilhado.

Modularização e limites

  • Lógica de árvore isolada em domain/customizationTree.js (sem UI).
  • Modal aninhado isolado de CustomizeScreen (evita arquivo monolítico).
  • Backend: consolidação/normalização/preço extraídos de OrderProductService (OrderProductTree*) para respeitar limite de tamanho de arquivo.

Manutenção

  • Ao adicionar novo priceCalculation, atualizar calculateCustomizationGroupPrice e testes de domínio.
  • Ao mudar shape de sub_products / orderProductComponents, alinhar Normalizer, Cart e testes de árvore recursiva.
  • Não reintroduzir consolidação “só 1º nível” no serviço de pedido.

Links relacionados

Módulo Entrada
ui-products (Home) Home
ui-orders app-community wiki ui-orders
ui-shop app-community wiki ui-shop
api-platform-orders repo
App Home app-community wiki

Evidência de publicação

  • Feature em master desde commits ac36fe1 (ui-products) e 1c69816 (api-platform-orders).
  • Publicada no RC5 v1.4.19 (app-community#350 / PR#353).
  • Dual-gate: qa:accepted + security:accepted nas quatro issues.

Clone this wiki locally