# Upvote

> O módulo de espaço Upvote, da aba Comunidade. Um quadro em que os membros propõem tópicos, votam (um voto por pessoa, retirável) e comentam, e a equipe aprova, muda o estado, junta duplicados, arquiva com motivo e reabre. Ordenações, filtros, colunas, leitura pública, limites, avisos por e-mail, e as mesmas ações pelo assistente e pela API.

O **Upvote** é um quadro em que os membros dizem o que querem: cada pessoa propõe **tópicos** (uma ideia, um pedido, uma melhoria), todos votam nos que apoiam, e os mais votados sobem. A equipe responde mudando o estado de cada tópico (**Planejado**, **Em andamento**, **Feito** ou **Arquivado**, com o motivo), e quem votou é avisado.

É um [módulo de espaço](/conceitos/modulos) da aba **Comunidade** de **Adicionar Espaço**. **Um espaço é um quadro**: para ter quadros separados (produto, eventos, conteúdo), crie vários espaços. Quem cria o espaço: proprietário ou administrador.

## Upvote, Enquete ou Pesquisa?

| | [Enquete](/espacos/enquetes) | [Pesquisa](/espacos/pesquisas) | **Upvote** |
|---|---|---|---|
| Quem pergunta | A equipe | A equipe | **Os membros** propõem |
| Opções | Fixas, escritas pela equipe | Questionário em seções | Lista aberta, que cresce todo dia |
| Onde vive | Num post do Feed ou do Conteúdo | Espaço próprio e link público | Espaço próprio |
| Voto | Escolhe opção; só a equipe vê quem votou em quê | Resposta identificada ou anônima | Um voto por tópico, em quantos tópicos quiser; retirável |
| Fim | Encerra num prazo | Período, com resultado e NPS | Nunca encerra; cada tópico tem o seu desfecho |
| Para quê | Decidir entre poucas opções agora | Medir satisfação e clima | Descobrir o que a comunidade quer e mostrar o que foi feito |

**A regra de bolso:** a equipe quer saber entre A, B ou C → Enquete; quer medir → Pesquisa; quer que os membros digam o que querem e mostrar o que fez com isso → Upvote.

## Quem pode o quê

| Ação | Quem |
|---|---|
| Ler o quadro, os tópicos e os comentários | Quem abre o espaço; num espaço **público**, também o visitante sem login |
| Votar, remover o voto e comentar | Quem abre o espaço, com login |
| Propor um tópico | Quem o **Quem pode postar** do espaço permite |
| Editar e apagar o próprio tópico | O autor, até outra pessoa votar nele |
| Aprovar, editar, mudar o estado, juntar, arquivar, reabrir, ver quem votou e apagar | A **equipe**: proprietário, administrador e moderador. O financeiro não entra |
| Ligar a aprovação prévia | Proprietário e administrador |

## Como funciona

### O quadro

Cada tópico aparece num card com o **botão de voto à esquerda** (a seta e o número, preenchido quando você votou), o título, um trecho da descrição, o autor, os comentários e o selo do estado.

- **Ordenar por:** **Mais votados** (o padrão; no empate, o mais novo), **Novos** e **Em alta** (os mais votados nos últimos 7 dias, atualizado de hora em hora).
- **Filtros:** **Todos** (todos menos os arquivados), **Abertos**, **Planejados**, **Em andamento**, **Feitos**, **Arquivados**, **Meus tópicos** e **Votei**.
- **Visualização:** **Lista** ou **Colunas** (Aberto, Planejado, Em andamento e Feito, cada uma pelos mais votados). No celular, as colunas viram abas por estado, uma por vez.

A lista ganha uma linha só com os estados e menus compactos, **Ordenar** e **Filtro** (inclusive **Todos os tópicos**), e as colunas deixam de repetir o estado em cada cartão. No tópico, a barra mantém **Editar** e **Mudar estado**, e o resto vai para **Mais ações**.

### O voto

Cada pessoa tem **um voto por tópico** e vota em quantos tópicos quiser. Clicar de novo remove o voto. Quem propõe já começa votando no próprio tópico (e pode remover).

Todos veem a contagem; **quem votou, só a equipe vê**, em **Quem votou**, com a data em que cada pessoa entrou na comunidade (ajuda a perceber contas duplicadas).

Votar e remover o voto só valem em tópicos **Abertos**, **Planejados** ou **Em andamento**. Em **Feito** e **Arquivado**, a votação congela: não dá para votar nem para remover o voto.

### Os estados

| Estado | O que quer dizer | Voto | Comentário |
|---|---|---|---|
| **Aberto** | Recebendo votos | Sim | Sim |
| **Planejado** | A equipe vai fazer | Sim | Sim |
| **Em andamento** | A equipe está fazendo | Sim | Sim |
| **Feito** | Pronto | Congelado | Sim |
| **Arquivado** | Não vai seguir, com o motivo à vista de todos | Congelado | Não |

Só a equipe muda o estado. Cada mudança aceita uma **Nota para quem votou** (*"saiu na versão de março"*); arquivar exige o **Motivo**. **Reabrir** leva um tópico Feito ou Arquivado de volta a Aberto. Os votos sempre ficam.

### Já existe algo parecido?

Ao propor, a partir da terceira palavra do título aparecem até 5 tópicos do mesmo quadro que dividem palavras com ele, sob **Já existe algo parecido?**. Se um deles for o que você quer, **Votar neste** dá o seu voto a ele em vez de criar outro.

### Juntar duplicados

Quando dois tópicos pedem a mesma coisa, a equipe usa **Juntar em…** no repetido e escolhe o original, que precisa estar Aberto, Planejado ou Em andamento, no mesmo quadro. O repetido é arquivado como *"Duplicado de <título>"*, com o link; os votos passam para o original **sem contar duas vezes** quem votou nos dois; os comentários ficam no repetido. **Um tópico juntado não reabre.**

### Comentários

Quem abre o espaço comenta e responde (um nível de resposta), até 2.000 caracteres. O autor do comentário e a equipe apagam; apagar um comentário leva as respostas dele. Tópico arquivado não recebe mais comentários.

### Aprovação prévia

Com **Aprovação prévia** ligada, os tópicos dos membros só aparecem no quadro depois que a equipe aprovar. Até lá, o tópico fica **Aguardando aprovação**, visível só para o autor (em **Meus tópicos**) e para a equipe, e não recebe voto nem comentário. Se o autor editar o texto de um tópico já aprovado, ele volta para a aprovação. Os tópicos da equipe entram direto.

A equipe vê a barra **Gerenciar quadro**, com quantos tópicos estão aguardando e o botão **Fila de aprovação**, que lista os pendentes com **Aprovar** e **Recusar** (o recusado fica visível só para o autor e a equipe). Os pendentes também aparecem na [moderação](/membros/moderacao).

### Leitura pública

Num espaço com visibilidade **Público**, o visitante sem login lê tudo (o quadro, os tópicos, a contagem, os estados e os comentários), menos quem votou. Votar, comentar ou propor abre *"Entre para votar no que você apoia"* (ou *"Entre para comentar"*, *"Entre para propor um tópico"*), com **Entrar** e **Criar conta**; depois, a pessoa volta ao quadro. Em espaço que não é público, só quem abre o espaço lê.

### Limites

| Limite | Valor |
|---|---|
| Tópicos novos | 5 por pessoa por dia (a equipe não tem limite; os pendentes e os apagados contam) |
| Votos | 120 por pessoa por hora |
| Título | 140 caracteres |
| Descrição | 5.000 caracteres |
| Fotos | Até 4 por tópico (JPG, PNG ou WebP) |
| Nota ou motivo | 500 caracteres |

### Avisos por e-mail

| Quem recebe | Quando |
|---|---|
| O autor e quem votou | O tópico muda para **Planejado**, **Em andamento**, **Feito** ou **Arquivado** (com a nota ou o motivo), é **reaberto** ou é **juntado** a outro |
| A equipe | Um tópico novo é proposto |

O membro **não** recebe e-mail a cada tópico novo. Os avisos chegam também no sino. Só recebe quem **ainda tem acesso ao espaço** no momento do aviso. Dá para desligar na categoria **Upvote: tópicos que você apoia**, em [E-mails desta comunidade](/notificacoes/emails-desta-comunidade), ou pelo link do rodapé.

## Passo a passo

### Criar um quadro

*Papel: proprietário ou administrador.*

1. No menu, em **Adicionar Espaço**, abra a aba **Comunidade** e escolha **Upvote**.
2. Dê o nome, a descrição, a visibilidade (**Público** deixa qualquer pessoa ler) e o **Quem pode postar**. Ligue **Aprovação prévia** se quiser aprovar cada tópico.
3. Crie. Depois, **Configurar**, na barra **Gerenciar quadro**, liga e desliga a aprovação prévia.

### Propor um tópico

1. No quadro, clique em **Novo tópico** (no celular, no rodapé: *"Tem uma ideia? Proponha."*).
2. Escreva o **Título** e confira **Já existe algo parecido?**: se um tópico for o que você quer, **Votar neste**.
3. Escreva a **Descrição** e, se quiser, **Adicionar fotos** (até 4).
4. Clique em **Publicar tópico**.

### Gerenciar um tópico

*Papel: proprietário, administrador ou moderador.*

Abra o tópico. A barra **Gerenciar tópico** mostra os votos, o estado e as ações:

- **Aprovar**: quando o tópico está aguardando aprovação.
- **Editar**: título, descrição e fotos.
- **Mudar estado**: escolha o estado e, se quiser, a nota para quem votou. **Salvar estado** avisa o autor e quem votou.
- **Juntar em…**: escolha o tópico original e confirme.
- **Arquivar**: com o motivo, obrigatório.
- **Reabrir**: de Feito ou Arquivado para Aberto.
- **Quem votou**: a lista, com a data de entrada de cada pessoa.
- **Apagar**: o tópico sai do quadro com os votos, os comentários e as fotos. Se a ideia ainda vale, arquivar com um motivo guarda o histórico.

## Exemplos

**Quadro de sugestões de uma escola online.** Espaço **Público** "O que você quer aprender", **Quem pode postar = Qualquer um**. Os alunos propõem cursos; *"Excel avançado"* chega a 80 votos, a equipe muda para **Planejado** com a nota *"Gravamos em novembro"*, e os 80 recebem o aviso.

**Melhorias de um coworking.** Espaço para membros com **Aprovação prévia**. Um residente propõe *"Mais tomadas na sala 2"*; a equipe aprova, ele recebe votos, vira **Em andamento** e depois **Feito**. Um segundo pedido igual é juntado ao primeiro, levando os votos.

## Erros comuns e como resolver

| Situação | O que fazer |
|---|---|
| Não aparece **Novo tópico** | O **Quem pode postar** do espaço não inclui o seu papel |
| Não dá para votar | O tópico está Feito, Arquivado ou aguardando aprovação; ou você não entrou (visitante) |
| Não dá para editar o próprio tópico | Outra pessoa já votou nele; agora só a equipe edita |
| Não dá para comentar | O tópico está arquivado ou aguardando aprovação |
| Limite de 5 tópicos por dia | Espere completar 24 horas desde o primeiro tópico |
| Não dá para reabrir | O tópico foi juntado a outro: os votos já estão lá |
| Arquivar não salva | Informe o motivo, obrigatório |

## Perguntas frequentes

**Os membros sabem em que eu votei?**
Não. Só a equipe vê quem votou.

**Quem sai da comunidade perde o voto?**
Não. Os votos continuam na contagem; os avisos param, porque a pessoa não tem mais acesso.

**Dá para votar sem conta?**
Não. Num quadro público, o visitante lê; para votar, entra ou cria a conta.

## Pelo assistente

O assistente propõe, vota e gerencia tópicos com as mesmas regras de quem conectou. Ver [Ferramentas · Conteúdo](/mcp/ferramentas-conteudo#upvote).

- **Leitura:** `get_upvote_board`, `list_upvote_topics` (com ordenação e estado), `get_upvote_topic` e `find_similar_upvote_topics`.
- **Para quem abre o espaço:** `vote_upvote_topic`, `unvote_upvote_topic` e `create_upvote_comment`, sem confirmação; `create_upvote_topic` pede confirmação; `update_upvote_topic` e `delete_upvote_topic` (com confirmação), o autor até outra pessoa votar.
- **Da equipe:** `set_upvote_topic_status` (inclui arquivar), `reopen_upvote_topic` e `merge_upvote_topics`, todas com confirmação, mostrando o motivo e quantas pessoas serão avisadas; `merge_upvote_topics` não tem volta. `list_upvote_voters`, só leitura.
- **Do proprietário e do administrador:** `update_upvote_board`, que liga ou desliga a aprovação prévia.

Peça assim: *"Veja se já existe um tópico parecido com 'modo escuro no app' antes de criar; se existir, vote nele."* Ver a [receita](/mcp/receitas#91-veja-se-ja-existe-um-topico-parecido-antes-de-criar).

## Na API

As rotas ficam em `/api/upvotes`, com `X-CommunityId`; o caminho não leva a comunidade. As leituras aceitam ficar sem login num espaço público.

| Rota | O que faz | Quem |
|---|---|---|
| `GET /api/upvotes/spaces/{spaceId}` | O quadro: se a pessoa pode propor e gerenciar, e os limites | Quem lê |
| `PUT /api/upvotes/spaces/{spaceId}` | Liga ou desliga `requireApproval` | Proprietário e administrador |
| `GET` · `POST /api/upvotes/spaces/{spaceId}/topics` | Lista (`sort` = `top`, `new` ou `trending`; `status`; `mine`; `voted`; `cursor`) · propõe | Quem lê · quem pode postar |
| `GET /api/upvotes/spaces/{spaceId}/similar?title=` | Até 5 tópicos parecidos | Quem lê |
| `GET` · `PATCH` · `DELETE /api/upvotes/topics/{id}` | Detalhe · edita · apaga | Quem lê · autor (até outro voto) ou equipe |
| `PUT` · `DELETE /api/upvotes/topics/{id}/vote` | Vota · remove o voto | Quem abre o espaço |
| `GET /api/upvotes/topics/{id}/voters` | Quem votou | Equipe |
| `GET` · `POST /api/upvotes/topics/{id}/comments` · `DELETE /api/upvotes/comments/{id}` | Comentários | Quem lê · quem abre o espaço · autor ou equipe |
| `POST /api/upvotes/topics/{id}/status` · `…/reopen` · `…/merge` | Muda o estado (`status`, `note`) · reabre · junta (`targetId`) | Equipe |

Erros: `400` (arquivar sem motivo, texto vazio ou longo demais), `403` (sem permissão), `404` (tópico de outro quadro ou comunidade), `409` (votar em Feito, Arquivado ou pendente; comentar em arquivado; reabrir um tópico juntado), `429` (5 tópicos por dia, 120 votos por hora). A chave de API usa o módulo `upvotes` (ver [Autenticação](/api/autenticacao#o-escopo)). Ver [Upvotes](/api/referencia/upvotes).

## Relacionados

- [Enquetes](/espacos/enquetes)
- [Pesquisas](/espacos/pesquisas)
- [Moderação](/membros/moderacao)
- [Módulos](/conceitos/modulos)
- [E-mails desta comunidade](/notificacoes/emails-desta-comunidade)
- [Ferramentas · Conteúdo](/mcp/ferramentas-conteudo#upvote)