Avaliacoes

O modulo de avaliacoes gerencia o ciclo pos-negociacao entre produtores e fornecedores. Apos uma proposta ser aceita e confirmada, ambas as partes passam por etapas de confirmacao, entrega e avaliacao mutua.

Fluxo completo

O fluxo segue quatro etapas sequenciais:

Proposta aceita e confirmada
         |
         v
  (1) Confirmacao de conclusao
         |
         v  (apos carencia de 48h)
  (2) Avaliacao da negociacao
         |
         v
  (3) Entrega e recebimento
         |
         v
  (4) Avaliacao da entrega

1. Confirmacao de conclusao

Apos a proposta ser aceita (status = accepted) e confirmada (confirmed_at preenchido), cada parte deve informar se o negocio foi concluido:

• Produtor: campo producer_deal_status (valores: completed ou outro)
• Fornecedor: campo supplier_deal_status (valores: completed ou outro)

A data da confirmacao e registrada em producer_deal_confirmed_at / supplier_deal_confirmed_at.

2. Avaliacao da negociacao

Disponivel apenas para quem confirmou a conclusao como completed. O prazo para avaliar conta a partir da data de confirmacao de conclusao.

Campos da avaliacao (OrderReview):

3. Entrega e recebimento

Apos a negociacao, o fornecedor deve registrar a entrega dos produtos:

Fornecedor marca entrega:

• Cria/atualiza registro em OrderDeliveryStatus com supplier_marked_delivered_at = now().
• Produtor e notificado para confirmar o recebimento.

Produtor confirma recebimento:

• Preenche producer_confirmed_at e producer_confirmation com um dos valores:
  • received — recebeu normalmente
  • received_with_issues — recebeu com problemas (campo producer_issue_description obrigatorio)
  • not_received — nao recebeu (penaliza o fornecedor)

Se o produtor nao confirmar dentro do prazo, o recebimento e auto-confirmado como received.

4. Avaliacao da entrega

Apos o recebimento ser confirmado (manual ou automaticamente), ambas as partes podem avaliar a entrega.

Campos da avaliacao (OrderReview):

Prazo de carencia de 48 horas

A avaliacao da negociacao so fica disponivel apos 48 horas da confirmacao da proposta (setting review_available_after_hours, padrao 48).

O comando agendado reviews:check-deadlines verifica propostas confirmadas ha mais de 48 horas e envia notificacoes de disponibilidade para ambas as partes, desde que ainda nao tenham sido notificadas.

Prazos

Todos os prazos sao configuraveis via tabela de settings do sistema:

Sistema de reputacao

A reputacao e baseada em pontos acumulados na tabela user_reputation_points. Cada registro possui:

• user_id — usuario que recebeu os pontos
• source_type — tipo da acao que gerou os pontos
• source_id — ID do registro relacionado (review, proposal, delivery status)
• points — valor (positivo ou negativo)
• description — descricao legivel

Pontuacao por acao

Os valores sao configuraveis via settings:

Pontos por estrelas recebidas

A pontuacao que o avaliado recebe varia conforme a nota dada pelo avaliador:

• Negociacao: configurado por points_neg_rating_{1..5} (padrao 0 para cada nivel)
• Entrega: configurado por points_del_rating_{1..5} (padrao 0 para cada nivel)

O administrador pode ajustar esses valores nas settings para incentivar determinados comportamentos.

Consultas de reputacao

O ReviewService oferece:

• getReputationStats(userId) — pontuacao total, media de notas (negociacao e entrega separadas), contagem de avaliacoes e historico dos ultimos 50 registros de pontos.
• getPublicProfile(userId) — media geral, media por tipo (negociacao/entrega) e total de avaliacoes recebidas.
• getRanking(type, limit, orderBy) — ranking de usuarios por pontos ou por media de notas, filtravel por perfil (producer/supplier/todos).

Penalidades por nao avaliar

O comando reviews:check-deadlines processa expiracoes diariamente:

Avaliacao de negociacao expirada

Se o usuario confirmou conclusao como completed mas nao avaliou dentro de review_negotiation_deadline_days (15 dias a partir da confirmacao de conclusao):

• Recebe penalidade de points_review_expired (-5 pontos)
• source_type = negotiation_review_expired
• A penalidade e aplicada uma unica vez por proposta/usuario

Entrega nao marcada

Se o fornecedor nao marcou a entrega dentro de review_delivery_deadline_days (30 dias a partir da confirmacao da proposta):

• Recebe penalidade de points_delivery_expired (-15 pontos)
• source_type = delivery_expired

Recebimento nao confirmado

Se o produtor nao confirmou o recebimento dentro de review_receipt_deadline_days (7 dias apos o fornecedor marcar entrega):

• O recebimento e auto-confirmado como received
• Ambas as partes sao notificadas que a avaliacao da entrega esta disponivel
• O produtor nao recebe penalidade de pontos, mas perde a oportunidade de reportar problemas

Avaliacao de entrega expirada

Se o usuario nao avaliou a entrega dentro de review_delivery_rating_deadline_days (7 dias apos confirmacao do recebimento):

• Recebe penalidade de points_review_expired (-5 pontos)
• source_type = delivery_review_expired

Notificacoes e lembretes

O sistema envia notificacoes em diferentes momentos do fluxo. Todas passam pelo NotificationService e podem ser encaminhadas por email e/ou WhatsApp conforme configuracao do NotificationChannelConfig.

Notificacoes automaticas

Lembretes

Enviados review_reminder_days_before (5 dias) antes do vencimento de cada prazo:

Deduplicacao

O sistema verifica se a notificacao ja foi enviada para o mesmo usuario e proposta antes de criar uma nova, evitando duplicatas.

Comando agendado

O comando reviews:check-deadlines executa tres etapas em sequencia:

1. Notificacoes de disponibilidade — propostas que passaram a carencia de 48h
2. Lembretes — prazos proximos do vencimento
3. Expiracoes e penalidades — prazos vencidos

Saida tipica:

Verificando avaliações disponíveis...
  Notificações de disponibilidade enviadas: 3
Enviando lembretes...
  Lembretes de negociação: 2
  Lembretes de entrega (fornecedor): 1
  Lembretes de recebimento (produtor): 0
  Lembretes de avaliação de entrega: 1
Processando expirações...
  Avaliações de negociação expiradas: 0
  Entregas não marcadas: 0
  Recebimentos auto-confirmados: 1
  Avaliações de entrega expiradas: 0
Total de ações: 8