docs(feedback): conclui spike de schema e registra decisao de notificar

[karinaperes]

Pull Request

📋 Descrição

Conclui a spike de schema dos atributos de Feedback e registra a decisão de
substituir o bloqueio de edição de projeto por notificação da equipe.

Duas decisões que estavam em aberto e travavam etapas seguintes.

---

🔗 Issue relacionada

Related to #553

---

✅ Alterações realizadas

• Backend
• Front-end
• Banco de Dados
• Testes
• Documentação

Novo: docs/03 - tecnico/spikes/spike-schema-atributos-feedback.md

A seção 12.1 do documento de feedback deixava explícito que a estrutura dos
atributos — tabela relacional ou array de enum — dependia de spike, considerando
o custo da agregação por perfil.

Resultado: tabela relacional, confirmando a proposta de produto.

O critério que decidiu não foi desempenho. Nenhuma das duas opções é
expressável no groupBy do Prisma, que não suporta COUNT(DISTINCT) sobre
tabela relacionada — em ambas o caminho é agregar em memória, e com cerca de 120
linhas por perfil isso é irrelevante. O argumento que motivava a spike não
diferencia as opções.

O que decidiu apareceu no SQL gerado:

-- Opção A (tabela relacional)
CREATE UNIQUE INDEX "FeedbackAttribute_feedbackId_attribute_key"
  ON "FeedbackAttribute"("feedbackId", "attribute");

-- Opção B (array de enum)
"attributes" "FeedbackAttrEnum"[],     -- sem restrição
Com array, o Postgres aceita o mesmo eixo repetido na mesma avaliação. Como o
valor público da corroboração é a contagem de pessoas e projetos, um dado
duplicado corrompe exatamente aquilo que a funcionalidade entrega — e a
integridade passaria a depender só do código da aplicação.

feedback-reputacao.md

Seção 12.1: pendência resolvida, com o critério da decisão.
Seção 20: spike marcada como concluída; sai da lista de decisões em aberto.
Seção 21: decisão registrada no histórico.
gestao-projetos.md — nova seção 6.4

A restrição da seção 6.3 passa a ser notificação, não bloqueio.

A regra foi implementada e desativada em 16/08/2026 por dois defeitos que só
apareceram no uso:

Escopo largo demais — name, deadline e totalValue eram tratados como estrutura, travando edições sem relação com a composição da equipe.
Falso positivo na comparação de datas — o formulário carregava o prazo sem a hora enquanto o banco guardava o timestamp completo. Os dois nunca coincidiam, então abrir a tela de edição e salvar sem alterar nada já disparava o bloqueio.
Na prática a regra não protegia a estrutura: travava a edição por completo, sem
saída pela interface — nem para o owner, nem para um ADMIN.

A regra da observação com data stamp continua valendo. Ela é o registro
histórico; a notificação é o aviso ativo.

🧪 Como testar
Ler a spike e conferir se o raciocínio se sustenta — em especial a seção 3.1, que é onde a decisão se apoia.
Reproduzir a validação, se quiser:

npx prisma validate --schema <arquivo>
npx prisma migrate diff --from-empty --to-schema <arquivo> --script
Os dois schemas comparados estão reproduzidos na seção 2 do documento.
Ler a seção 6.4 de gestao-projetos.md e avaliar se a mudança de premissa faz sentido para o projeto.
Conferir os links entre os três documentos.
⚠️ Observações
Isto não implementa nada. É decisão registrada. A migration e as rotas são
a etapa 3 da ordem de execução do documento de feedback, agora destravada.

O encerramento manual de projeto continua bloqueando o feedback. É a etapa
1, e sem ela nada dispara a avaliação — o feedback só é acionado quando o
projeto atinge CONCLUIDO.

O escopo do épico #553 aumentou. Ele previa a edição controlada e o
encerramento; agora incorpora também a notificação da equipe. As quatro
perguntas que faltam definir estão listadas no fim da seção 6.4: quem é
notificado, por qual canal, o que a mensagem informa, e se alguma alteração
ainda merece confirmação prévia.

Estado do código: a verificação de edição estrutural continua em
src/app/api/team-project/[id]/route.ts, desativada por constante e com o
motivo documentado. Os três testes que a cobriam estão como it.skip,
descrevendo o comportamento esperado caso a regra volte.

Continuam em aberto no feedback, e não dependiam desta spike: prazo do
blind duplo, N mínimo para exibição, destino do rating legado e existência
de fluxo de denúncia pelo avaliado.

✔️ Checklist
 O PR está relacionado a uma Issue. (Related to #553)
 O código foi testado. (spike executada com Prisma 7.9.1, mesma versão do projeto)
 Os testes existentes continuam passando. (só documentação)
 A documentação foi atualizada.
 Este PR resolve apenas um objetivo. (destravar decisões pendentes)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **Documentation**
  * Documented the decision to use a relational table for feedback attributes, ensuring unique attributes per evaluation.
  * Added a technical comparison of relational tables and enum arrays, including performance, indexing, and future SQL considerations.
  * Recorded the decision to replace edit blocking after team formation with notifications.
  * Documented pending notification details, including recipients, channels, message content, and confirmation requirements.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
trycatch	Ready	Preview	Aug 23, 2026 7:20pm
trycatch-prod	Ready	Preview	Aug 23, 2026 7:20pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ba53d7e-79b8-420f-a19e-49f241ebb0a6

📥 Commits

Reviewing files that changed from the base of the PR and between 3f2a690 and 96995ae.

📒 Files selected for processing (3)

• docs/02 - produto/feedback/feedback-reputacao.md
• docs/02 - produto/projetos/gestao-projetos.md
• docs/03 - tecnico/spikes/spike-schema-atributos-feedback.md

---

📝 Walkthrough

Walkthrough

A documentação registra a decisão por uma tabela relacional para atributos de feedback e detalha a substituição do bloqueio de edição em projetos por notificações aos participantes.

Changes

Schema de atributos de feedback

Layer / File(s)	Summary
Spike e decisão do schema docs/03 - tecnico/spikes/spike-schema-atributos-feedback.md	Compara tabela relacional e array de enum no Prisma. Registra a escolha de FeedbackAttribute, os efeitos na integridade e agregação, e os comandos de validação.
Alinhamento da documentação de produto docs/02 - produto/feedback/feedback-reputacao.md	Atualiza a decisão de produto, marca a spike como concluída e registra a tabela relacional como escolha por integridade.

Política de edição em projetos

Layer / File(s)	Summary
Política de notificações e histórico docs/02 - produto/projetos/gestao-projetos.md	Documenta a substituição do bloqueio de edição por notificações, mantém observações com timestamp e registra pendências de desenho, verificações desativadas e testes ignorados.

Estimated code review effort: 1 (Trivial) | ~5 minutes

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/spike-schema-feedback

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud