Conceitos Básicos

Entenda os conceitos fundamentais da plataforma Divino Cestas e como eles se relacionam.

🎓 Glossário Rápido

Termo	Significado
Ciclo	Período de ofertas, pedidos e entregas
Cesta	Tipo de pacote de produtos
Oferta	Produtos disponibilizados por fornecedor
Composição	Definição do conteúdo das cestas
Pedido	Encomenda de cesta por consumidor
Ponto de Entrega	Local de retirada das cestas
CSA	Community Supported Agriculture

🔄 Ciclo (Delivery Cycle)

Um Ciclo é o período completo que envolve ofertas, pedidos e entregas de cestas.

Características

• Nome: Identificação do ciclo (ex: "Ciclo Verão 2024")
• Datas: Define o período ativo do ciclo
• Status: Ativo ou Inativo (calculado automaticamente)
• Entregas: Múltiplas datas de entrega dentro do ciclo
• Cestas: Tipos de cestas disponíveis no ciclo

Linha do Tempo de um Ciclo

┌────────────────── CICLO ──────────────────┐
│                                            │
│  ┌──────────┐  ┌───────────┐  ┌─────────┐│
│  │ OFERTAS  │→ │  PEDIDOS  │→ │ENTREGAS ││
│  └──────────┘  └───────────┘  └─────────┘│
│   Fornecedores  Consumidores   Retirada   │
│   cadastram     encomendam     de cestas  │
│   produtos      cestas                     │
└────────────────────────────────────────────┘

Janelas de Tempo

Período	Descrição	Responsável
Data Oferta Início	Fornecedores começam a cadastrar ofertas	Fornecedores
Data Oferta Fim	Deadline para ofertas	Fornecedores
Data Pedido Início	Consumidores começam a fazer pedidos	Consumidores
Data Pedido Fim	Deadline para pedidos	Consumidores
Data Retirada	Entregas das cestas	Todos

Exemplo de Ciclo

{
  id: 42,
  nome: "Ciclo Primavera 2024",
  dataOfertaInicio: "2024-09-01",
  dataOfertaFim: "2024-09-15",
  dataPedidoInicio: "2024-09-16",
  dataPedidoFim: "2024-09-25",
  dataRetiradaInicio: "2024-10-01",
  dataRetiradaFim: "2024-10-05",
  ativo: true
}

Estados do Ciclo

🔴 Inativo → Aguardando início
🟡 Ofertas Abertas → Fornecedores cadastrando
🟢 Pedidos Abertos → Consumidores encomendando
🔵 Em Preparação → Montando cestas
⚫ Finalizado → Entregas concluídas

🧺 Cesta (Basket)

Uma Cesta é um tipo de pacote de produtos que pode ser encomendado pelos consumidores.

Tipos de Cestas

Cesta 1: Ofertas Padrão

• Cestas pré-configuradas
• Composição definida pelo administrador
• Produtos variados de múltiplos fornecedores

Cesta 5: Itens Extras/Adicionais

• Produtos avulsos
• Pedidos individuais
• Compras complementares

Características

{
  id: 1,
  nome: "Cesta Básica de Hortaliças",
  descricao: "Cesta com hortaliças da estação",
  valorReferencia: 50.00,
  pesoAproximado: 5000, // gramas
  ativo: true
}

Relacionamentos

Cesta
  │
  ├─▶ CicloCestas (associação com ciclos)
  │     │
  │     └─▶ Composicoes (o que vai na cesta)
  │
  └─▶ PedidoConsumidores (pedidos)

🥬 Produto (Product)

Produtos são os alimentos oferecidos pelos fornecedores.

Atributos

{
  id: 15,
  nome: "Alface Crespa",
  unidade: "maço",
  pesoGramas: 200,
  valorReferencia: 3.50,
  descritivo: "Alface orgânica",
  categoriaid: 2,
  ativo: true
}

Unidades de Medida

• maço - Alface, couve, rúcula
• kg - Batata, cenoura, tomate
• unidade - Abóbora, melancia
• dúzia - Ovos
• litro - Leite, mel

Categorias

Produtos são organizados em categorias:

• 🥬 Hortaliças Folhosas
• 🥕 Raízes e Tubérculos
• 🍅 Frutos
• 🌾 Grãos e Cereais
• 🥚 Produtos de Origem Animal
• 🍯 Processados

📦 Oferta (Supplier Offer)

Uma Oferta é a disponibilização de produtos por um fornecedor em um ciclo específico.

Estrutura

Oferta (por Fornecedor + Ciclo)
  │
  ├─▶ OfertaProdutos
  │     ├─ Produto A - 50 kg - R$ 5,00/kg
  │     ├─ Produto B - 30 maços - R$ 3,50/maço
  │     └─ Produto C - 20 unidades - R$ 8,00/un

Processo de Oferta

1. Fornecedor acessa ciclo ativo
   ↓
2. Seleciona produtos do catálogo
   ↓
3. Define quantidade disponível
   ↓
4. Define preço
   ↓
5. Salva oferta
   ↓
6. Oferta fica disponível para composição

Exemplo

{
  oferta: {
    id: 123,
    cicloid: 42,
    usuarioid: 5, // Fornecedor
    finalizada: true
  },
  produtos: [
    {
      produtoid: 15,
      produtoNome: "Alface Crespa",
      quantidade: 50,
      unidade: "maço",
      valor: 3.50
    },
    {
      produtoid: 23,
      produtoNome: "Tomate Italiano",
      quantidade: 30,
      unidade: "kg",
      valor: 8.00
    }
  ]
}

🎨 Composição (Basket Composition)

A Composição define quais produtos das ofertas vão para cada cesta em um ciclo.

Fluxo de Composição

Ofertas Disponíveis
  ↓
Administrador seleciona produtos
  ↓
Define quantidades por cesta
  ↓
Gera Composição
  ↓
Consumidores veem cestas disponíveis

Estrutura

Composicao
  ├─ cicloCestaId (qual cesta, qual ciclo)
  ├─ quantidadeCestas (total de cestas disponíveis)
  └─ ComposicaoOfertaProdutos
       ├─ OfertaProduto A - 200g por cesta
       ├─ OfertaProduto B - 1 maço por cesta
       └─ OfertaProduto C - 500g por cesta

Exemplo Visual

🧺 Cesta Básica de Hortaliças (50 cestas disponíveis)
  ├─ 🥬 Alface Crespa - 1 maço (Fornecedor João)
  ├─ 🥕 Cenoura - 500g (Fornecedor Maria)
  ├─ 🍅 Tomate - 300g (Fornecedor José)
  ├─ 🥔 Batata - 1kg (Fornecedor Ana)
  └─ 🧅 Cebola - 500g (Fornecedor Pedro)
  
  Total estimado: 2,3kg
  Valor de referência: R$ 45,00

Cálculo de Quantidades

// Exemplo
Oferta: 50 kg de Tomate
Composição: 300g por cesta
Cestas possíveis: 50000g ÷ 300g = 166 cestas

// Sistema calcula automaticamente
// quantas cestas podem ser montadas
// baseado nas ofertas disponíveis

🛒 Pedido de Consumidor (Consumer Order)

Um Pedido é a encomenda feita por um consumidor em um ciclo.

Processo de Pedido

1. Consumidor acessa ciclo ativo
   ↓
2. Visualiza cestas disponíveis
   ↓
3. Seleciona cesta(s)
   ↓
4. Escolhe ponto de entrega
   ↓
5. Revisa pedido
   ↓
6. Confirma pedido
   ↓
7. Pedido registrado

Estrutura do Pedido

{
  pedido: {
    id: 456,
    cicloid: 42,
    usuarioid: 78, // Consumidor
    pontoEntregaId: 3,
    finalizado: true,
    dataConfirmacao: "2024-09-20T10:30:00"
  },
  produtos: [
    {
      cestaId: 1,
      cestaNome: "Cesta Básica",
      quantidade: 2, // 2 cestas
      valorUnitario: 45.00,
      valorTotal: 90.00
    }
  ]
}

Status do Pedido

Status	Descrição
🟡 Rascunho	Pedido iniciado mas não finalizado
🟢 Confirmado	Pedido confirmado pelo consumidor
🔵 Preparando	Cesta sendo montada
✅ Entregue	Consumidor retirou a cesta

📍 Ponto de Entrega (Delivery Point)

Pontos de Entrega são os locais onde as cestas são retiradas pelos consumidores.

Características

{
  id: 3,
  nome: "Centro Comunitário da Vila",
  endereco: "Rua das Flores, 123",
  cidade: "São Paulo",
  referencia: "Próximo ao mercado municipal",
  responsavel: "Maria Silva",
  telefone: "(11) 98765-4321",
  ativo: true
}

Relacionamento com Ciclo

CicloEntregas
  ├─ cicloId: 42
  ├─ pontoEntregaId: 3
  ├─ dataEntrega: "2024-10-01"
  ├─ horaInicio: "14:00"
  ├─ horaFim: "18:00"
  └─ quantidadeCestas: 30

Múltiplos Pontos

Um ciclo pode ter vários pontos de entrega:

Ciclo Primavera 2024
  ├─ 📍 Centro Comunitário (30 cestas)
  ├─ 📍 Feira da Praça Central (45 cestas)
  └─ 📍 Associação de Bairro (25 cestas)

👥 Usuário (User)

Usuários têm diferentes perfis e permissões na plataforma.

Perfis

perfil: ['fornecedor', 'consumidor', 'admin']

🌱 Fornecedor (Supplier)

Pode:

• ✅ Criar ofertas em ciclos
• ✅ Editar suas ofertas
• ✅ Ver relatório de pedidos
• ❌ Não pode fazer pedidos de consumidor
• ❌ Não pode criar ciclos

🛒 Consumidor (Consumer)

Pode:

• ✅ Fazer pedidos em ciclos
• ✅ Visualizar suas encomendas
• ✅ Escolher pontos de entrega
• ❌ Não pode criar ofertas
• ❌ Não pode ver relatórios administrativos

👨‍💼 Admin (Administrator)

Pode:

• ✅ Criar e gerenciar ciclos
• ✅ Configurar cestas
• ✅ Fazer composições
• ✅ Gerenciar usuários
• ✅ Gerar todos os relatórios
• ✅ Fazer tudo que fornecedores e consumidores podem

👑 Master (Super Admin)

Pode:

• ✅ Tudo que admin pode
• ✅ Configurações avançadas do sistema
• ✅ Gerenciar outros admins

Estrutura de Usuário

{
  id: 5,
  nome: "João Silva",
  email: "joao@exemplo.com",
  perfil: ['fornecedor'],
  nomeoficial: "João Silva - Sítio Boa Vista",
  celular: "(11) 91234-5678",
  descritivo: "Produtor de hortaliças orgânicas",
  cientepolitica: true, // Ciente da política
  ativo: true
}

💰 Movimentação (Financial Movement)

Movimentações registram transações financeiras relacionadas aos ciclos.

Tipos de Movimentação

• 💵 Depósito: Pagamento de consumidor
• 💸 Retirada: Pagamento a fornecedor
• 📋 Ajuste: Correções administrativas

Estrutura

{
  id: 89,
  usuarioid: 5, // Fornecedor
  tipoMovimentacaoId: 2, // Retirada
  valor: 450.00,
  data: "2024-10-05",
  descricao: "Pagamento Ciclo Primavera 2024",
  arquivo: "comprovante_89.pdf",
  cicloid: 42
}

🔗 Fluxo Completo: Conceitos Integrados

1️⃣ Admin cria CICLO
   ↓
2️⃣ Fornecedores criam OFERTAS com PRODUTOS
   ↓
3️⃣ Admin cria COMPOSIÇÃO das CESTAS
   (seleciona produtos das ofertas)
   ↓
4️⃣ Consumidores fazem PEDIDOS
   (escolhem cestas e PONTO DE ENTREGA)
   ↓
5️⃣ Sistema gera relatórios
   (pedidos por fornecedor, por consumidor)
   ↓
6️⃣ Cestas são montadas e entregues
   ↓
7️⃣ MOVIMENTAÇÕES financeiras registradas
   ↓
8️⃣ Ciclo finalizado ✅

🔗 Próximos Passos

• Exemplo de Ciclo Completo - Veja um ciclo na prática
• Guia do Fornecedor - Como usar se você é fornecedor
• Guia do Consumidor - Como usar se você é consumidor
• Guia do Administrador - Como gerenciar a plataforma

---

Dúvidas sobre os conceitos? Consulte o FAQ ou o Troubleshooting.