Produtos

O modulo de produtos organiza o catalogo de insumos agricolas em uma hierarquia de 4 niveis, permitindo classificacao precisa e busca eficiente durante a criacao de cotacoes.

Hierarquia de Produtos

A estrutura segue uma arvore de 4 niveis (N1 a N4):

ProductType (N1)
  └── ProductSubtype (N2)
        └── Product (N3)
              └── ProductVariation (N4)

Campos principais de cada nivel

ProductType (N1)

• description -- nome da categoria
• status -- ativo/inativo

ProductSubtype (N2)

• product_type_id -- FK para ProductType (N1)
• description -- nome do subtipo
• status -- ativo/inativo

Product (N3)

• product_type_id -- FK para ProductType (N1)
• product_subtype_id -- FK para ProductSubtype (N2)
• active_ingredient_id -- FK para ActiveIngredient
• measurement_unit_id -- FK para MeasurementUnit
• brand_id -- FK para Brand (marca principal)
• commercial_name -- nome comercial do produto
• description -- descricao tecnica
• status -- ativo/inativo

ProductVariation (N4)

• product_id -- FK para Product (N3)
• brand_id -- FK para Brand
• variation_name -- nome curto da variacao
• full_variation_name -- nome completo da variacao
• status -- ativo/inativo

Categorias de Insumos (N1)

O sistema possui 5 tipos de insumos cadastrados:

Entidades Auxiliares

Marcas (Brand)

Tabela brands com campos description e status.

Um produto possui duas formas de vinculo com marcas:

• Marca principal -- campo brand_id direto no Product (relacionamento belongsTo)
• Marcas secundarias -- tabela pivot product_brands (relacionamento belongsToMany) com campo status na pivot

Isso permite que o mesmo produto generico tenha multiplas marcas associadas (ex.: Abamectin fabricado por Nortox, Syngenta, etc.).

Principios Ativos (ActiveIngredient)

Tabela active_ingredients com campos description e status.

Cada produto (N3) pode estar vinculado a um principio ativo. O scope scopeActive permite filtrar apenas registros ativos.

Exemplos: Abamectin, Glifosato, Atrazina.

Unidades de Medida (MeasurementUnit)

Tabela measurement_units com campos:

• description -- nome completo (ex.: Litro, Quilograma)
• abbreviation -- sigla (ex.: L, KG)
• status -- ativo/inativo

O Product possui um accessor unit que retorna o symbol da unidade associada, ou 'UN' como fallback.

Alem das unidades globais, existe a tabela product_type_units (model ProductTypeUnit) que define unidades especificas por tipo de produto.

Culturas (PlantationCulture)

Tabela plantation_cultures com campos description e status.

Exemplos: soja, milho, cafe, algodao.

As culturas nao se vinculam diretamente a produtos, mas sim ao perfil do produtor (via tabela pivot producer_plantation_cultures). Isso permite que o sistema identifique quais culturas o produtor trabalha para sugerir insumos relevantes.

Biotecnologias

Nao existe um model de biotecnologia implementado no sistema atual.

Busca de Produtos nas Cotacoes

Quando o produtor cria uma cotacao (Order), ele adiciona itens (OrderItem) selecionando produtos do catalogo.

Fluxo de selecao

1. O produtor seleciona o tipo de insumo (N1 -- ProductType)
2. O sistema carrega os subtipos disponiveis (N2 -- via endpoint GET /product-types/{id}/subtypes)
3. O produtor seleciona o subtipo e o sistema carrega os produtos (N3 -- via endpoint GET /product-subtypes/{subtypeId}/products)
4. O produtor seleciona o produto e opcionalmente uma variacao (N4) e uma marca

Estrutura do OrderItem

Cada item da cotacao registra:

O campo accepts_similar permite que o fornecedor proponha um produto equivalente (mesma categoria e principio ativo, mas de outra marca ou variacao).

Endpoints da API

Fornecedor e Tipos de Produto

O fornecedor define em seu perfil quais tipos de produto ele trabalha, via tabela pivot supplier_product_types. Isso e usado para filtrar cotacoes relevantes para cada fornecedor.

Diagrama de Relacionamentos

ProductType (N1)
  ├── hasMany → ProductSubtype (N2)
  ├── hasMany → Product (N3)
  └── hasMany → ProductTypeUnit

ProductSubtype (N2)
  ├── belongsTo → ProductType (N1)
  └── hasMany → Product (N3)

Product (N3)
  ├── belongsTo → ProductType (N1)
  ├── belongsTo → ProductSubtype (N2)
  ├── belongsTo → ActiveIngredient
  ├── belongsTo → MeasurementUnit
  ├── belongsTo → Brand (marca principal)
  ├── belongsToMany → Brand (via product_brands)
  ├── hasMany → ProductVariation (N4)
  └── hasMany → OrderItem

ProductVariation (N4)
  ├── belongsTo → Product (N3)
  ├── belongsTo → Brand
  └── hasMany → OrderItem

Brand
  ├── hasMany → Product (marca principal)
  ├── belongsToMany → Product (via product_brands)
  ├── hasMany → ProductVariation
  └── hasMany → OrderItem