Documentação para Desenvolvedores de Avaliações

As Avaliações são modelos estruturados para coletar, moderar e renderizar feedback público no FaceFlow.

Elas permitem que equipes técnicas gerenciem conteúdo sensível à reputação como saída governada do site em vez de depoimentos livremente gerados e sem controle.

Responsabilidade Principal

Um modelo de Avaliação é responsável por:

• modelos de avaliação configuráveis
• campos de avaliação estruturados
• captura de submissões públicas
• política de moderação e verificação
• saída de exibição incorporável
• controle de publicação

Isso torna as Avaliações adequadas para seções do site orientadas à confiança que precisam tanto de visibilidade pública quanto de controle operacional.

Modelo Central de Avaliação

Um modelo de Avaliação normalmente combina:

• campos centrais de identidade da avaliação
• campos de avaliação
• dimensões de avaliação personalizadas opcionais
• configurações de moderação
• comportamento de verificação
• configurações de apresentação e exibição

Na prática, a camada de Avaliação define tanto quais feedbacks podem ser coletados quanto quais feedbacks aprovados podem ser publicados de volta no site.

Conceitualmente:

{
  "name": "customer-success-reviews",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

Fluxo de Submissão e Publicação

Em alto nível:

1. um modelo de Avaliação é definido centralmente
2. ele é incorporado em uma Página através de um Componente
3. visitantes enviam feedback
4. regras de moderação e verificação são aplicadas
5. entradas aprovadas são renderizadas de volta na experiência do site

Conceitualmente:

review widget render
  -> visitor submission
  -> pending review state
  -> moderation / verification
  -> approved review published

É por isso que as Avaliações devem ser tratadas como conteúdo público governado, não apenas outro formulário de entrada.

Estrutura de Avaliação

Modelos de Avaliação podem suportar:

• avaliação geral
• título da avaliação
• conteúdo da avaliação
• dimensões de avaliação personalizadas para um feedback mais estruturado

Exemplo:

overall_rating
service_rating
communication_rating
value_rating

Use dimensões extras apenas quando elas melhorarem a confiança e a interpretação.

Exemplo de Modelo de Avaliação

Uma revisão técnica deve ser capaz de inspecionar a forma do modelo claramente:

{
  "name": "service-review",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

Isso ajuda as equipes a revisar o que está sendo coletado, o que é obrigatório e quanta carga de moderação o modelo provavelmente criará.

Moderação e Verificação

Moderação e verificação são centrais para o design das Avaliações.

As equipes técnicas devem decidir:

• se as entradas requerem aprovação
• se verificação adicional é necessária
• quem é responsável pelas decisões de publicação
• como o conteúdo sensível à reputação deve ser tratado

Quanto maior o risco para a reputação, mais fortes devem ser, normalmente, os controles.

Incorporação de Avaliações

As Avaliações são tipicamente incorporadas em seções de Página através de Componentes.

Um marcador de incorporação comum é:

<div data-review-embed="service-review"></div>

Exemplo de seção:

<section class="customer-proof">
  <header>
    <h2>What customers say</h2>
  </header>
  <div data-review-embed="customer-success-reviews"></div>
</section>

Isso mantém a coleta e a exibição de avaliações reutilizáveis, permitindo que a Página posicione o conteúdo de confiança onde ele tem mais impacto.

Incorporações Fixas vs Incorporações Baseadas em Campo

Existem dois padrões comuns de incorporação.

Use um id fixo de modelo de avaliação gerenciado quando o template deve sempre renderizar um modelo de Avaliação específico:

<div data-review-embed="customer-success-reviews"></div>

Use uma incorporação baseada em campo quando um Componente expõe um campo reviewSelect e os autores devem escolher o modelo de Avaliação gerenciado no momento da autoria:

<div data-review-embed="{serviceReview}"></div>

Regra de decisão:

• incorporação fixa -> um fluxo de confiança estável de responsabilidade do template
• incorporação baseada em campo -> Componente reutilizável com fluxo de avaliação selecionável pelo autor

Padrão de Integração

O caminho de execução limpo é:

Review model
-> Component embed via reviewSelect or explicit data-review-embed marker
-> Page composition
-> public submission, moderation, and approved display output

Isso mantém a lógica de fluxo de trabalho sensível à reputação centralizada em vez de espalhá-la por marcação de página pontual.

Orientações Operacionais

Um bom design de Avaliação normalmente favorece:

• um modelo de Avaliação por contexto de negócio
• responsabilidade de moderação clara
• dimensões de avaliação estruturadas apenas onde adicionam valor real
• uma experiência de submissão curta o suficiente para preservar a qualidade
• um modelo de publicação que suporte confiança em vez de ruído

Se um modelo de Avaliação se tornar muito amplo, a qualidade e a moderação geralmente se tornam mais difíceis de gerenciar.

Orientações para o Contrato de Avaliação

Mantenha o modelo de avaliação proporcional ao fluxo público.

Padrões típicos:

• seção simples de confiança -> avaliação geral + título + corpo da avaliação
• fluxo de qualidade de serviço -> avaliação geral mais um pequeno número de dimensões, como serviço, comunicação ou valor

Se um fluxo público curto precisar de muitas entradas de avaliação, a qualidade da submissão e a taxa de conclusão geralmente caem.

Orientações Técnicas

• separar modelos de Avaliação por contexto de negócio
• alinhar a política de moderação e verificação com a sensibilidade à reputação
• manter a coleta pública de avaliações curta o suficiente para manter a qualidade das submissões
• tratar o conteúdo de avaliações publicadas como saída governada
• coleta de avaliações, moderação e exibição juntos como um único fluxo de trabalho

Anti-padrões

Evitar:

• um único modelo de Avaliação gigante usado para contextos de negócios não relacionados
• muitas dimensões de avaliação para um fluxo público curto
• publicar sem responsabilidade de moderação clara
• tratar Avaliações como depoimentos não gerenciados colados em Componentes
• projetar o fluxo de entrada sem revisar o modelo de exibição e aprovação

Padrão de Construção de Exemplo

Review model:
  customer-success-reviews

Component:
  review-strip

Embed:
  <div data-review-embed="customer-success-reviews"></div>

Esse padrão mantém o conteúdo de confiança reutilizável e governado.

Relacionado

• Visão Geral do Produto de Reviews
• Guia de Avaliações
• Componentes
• Páginas
• Usuários