From 9914a3475ed73126995c89786b2a0170445106ce Mon Sep 17 00:00:00 2001 From: Karina Date: Tue, 18 Aug 2026 10:00:25 -0300 Subject: [PATCH] docs(produto): separa status do documento do status da implementacao --- .../documento-0-visao-geral.md | 18 +- .../adminstrativo/painel-administrativo.md | 4 + .../conteudos-informativos-e-educacionais.md | 4 +- docs/02 - produto/convite/invite-request.md | 4 +- docs/02 - produto/convite/invite.md | 4 +- .../estado-das-funcionalidades.md | 166 ++++++++++++++++++ .../feedback/feedback-reputacao.md | 4 +- .../jornada-de-entrada-how-to-join-ux.md | 4 +- .../jornada-de-entrada-how-to-join.md | 4 +- .../permissoes-papeis/permissoes.md | 4 +- docs/02 - produto/portfolio/portfolio.md | 4 +- docs/02 - produto/projetos/gestao-projetos.md | 4 +- docs/02 - produto/skills/gestao-skills.md | 4 +- .../02 - produto/tech-stacks/gestao-stacks.md | 4 +- docs/02 - produto/usuario/perfis-usuario.md | 4 +- 15 files changed, 223 insertions(+), 13 deletions(-) create mode 100644 docs/02 - produto/estado-das-funcionalidades.md diff --git a/docs/00 - governanca/documento-0-visao-geral.md b/docs/00 - governanca/documento-0-visao-geral.md index c6a42611..77a85793 100644 --- a/docs/00 - governanca/documento-0-visao-geral.md +++ b/docs/00 - governanca/documento-0-visao-geral.md @@ -65,14 +65,30 @@ Podem evoluir conforme o produto amadurece. ### Camada 2 --- Documentos de Produto (Evolutivos) - Sistema de Feedback e Reputação; -- Convites de Acesso; +- Convites de Acesso e Solicitação de Convite; - Jornada de Entrada e How-to-Join; - Gestão de Projetos; - Perfis de Usuário; - Permissões e Papéis; +- Portfólio Público; +- Gestão de Skills; +- Gestão de Tech Stacks; - Conteúdos Informativos e Educacionais; - Painel Administrativo. +**Estado das Funcionalidades** --- índice consolidado que responde o que já +está no ar e o que falta, com o estado de cada item verificado contra o código: +[`docs/02 - produto/estado-das-funcionalidades.md`](../02%20-%20produto/estado-das-funcionalidades.md). + +Cada documento desta camada declara dois estados no cabeçalho: + +- **Status do documento** --- o texto é confiável e está consolidado? +- **Status da implementação** --- isto está funcionando na plataforma? + +A separação existe porque documento consolidado e funcionalidade entregue são +coisas distintas: uma especificação pode estar perfeitamente alinhada ao +`schema.prisma` sem que exista tela para a pessoa usar. + ### Camada 3 --- Documentos Técnicos (Evolutivos) - Modelagem de Dados; diff --git a/docs/02 - produto/adminstrativo/painel-administrativo.md b/docs/02 - produto/adminstrativo/painel-administrativo.md index f56bead8..e37b5b01 100644 --- a/docs/02 - produto/adminstrativo/painel-administrativo.md +++ b/docs/02 - produto/adminstrativo/painel-administrativo.md @@ -3,6 +3,10 @@ Classificação: Documento de Produto\ Camada: 2 --- Produto +**Status do documento:** consolidado +**Status da implementação:** 🟢 completa — painel e subtelas em uso +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) + ## 1. Objetivo Centralizar gestão de usuários, convites e cadastros. diff --git a/docs/02 - produto/conteudos/conteudos-informativos-e-educacionais.md b/docs/02 - produto/conteudos/conteudos-informativos-e-educacionais.md index b787c13a..ee6b3383 100644 --- a/docs/02 - produto/conteudos/conteudos-informativos-e-educacionais.md +++ b/docs/02 - produto/conteudos/conteudos-informativos-e-educacionais.md @@ -2,7 +2,9 @@ **Classificação:** Documento de Produto / Conteúdo **Camada:** 2 - Documentos de Produto e Funcionalidades -**Status:** Documento inicial consolidado +**Status do documento:** Documento inicial consolidado +**Status da implementação:** 🔴 não iniciada — a tela de FAQ é um placeholder +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/convite/invite-request.md b/docs/02 - produto/convite/invite-request.md index 887fad54..14cc7b4c 100644 --- a/docs/02 - produto/convite/invite-request.md +++ b/docs/02 - produto/convite/invite-request.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Versão consolidada baseada no schema.prisma +**Status do documento:** Versão consolidada baseada no schema.prisma +**Status da implementação:** 🟢 completa — formulário público e aprovação pelo admin +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/convite/invite.md b/docs/02 - produto/convite/invite.md index 1177997e..7b88a9e6 100644 --- a/docs/02 - produto/convite/invite.md +++ b/docs/02 - produto/convite/invite.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Versão consolidada alinhada ao schema.prisma +**Status do documento:** Versão consolidada alinhada ao schema.prisma +**Status da implementação:** 🟢 completa — criação, uso no cadastro e gestão no painel +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/estado-das-funcionalidades.md b/docs/02 - produto/estado-das-funcionalidades.md new file mode 100644 index 00000000..516899cb --- /dev/null +++ b/docs/02 - produto/estado-das-funcionalidades.md @@ -0,0 +1,166 @@ +# Estado das Funcionalidades + +**Classificação:** Documento de Produto / Consolidado +**Camada:** 2 — Documentos de Produto e Funcionalidades +**Status do documento:** consolidado +**Última verificação contra o código:** 16/08/2026 + +--- + +## 1. Para que serve + +Este documento responde a uma pergunta só: **o que já está funcionando e o que +ainda falta.** + +Ele existe porque os documentos de produto descrevem como cada funcionalidade +*deve* se comportar, mas não dizem se ela está no ar. Quem precisa decidir o que +construir em seguida teria que abrir treze arquivos e conferir cada um contra o +código. + +> ⚠️ **Este documento não substitui os documentos de produto.** Ele aponta para +> eles. As regras de negócio, os critérios e os detalhes continuam lá. + +--- + +## 2. Legenda + +| Situação | Significa | +|---|---| +| 🟢 **Completa** | Backend e interface prontos, em uso | +| 🟡 **Parcial** | Parte funciona; falta algo para a pessoa conseguir usar de ponta a ponta | +| 🔴 **Não iniciada** | Especificada em documento, sem implementação utilizável | +| ⚪ **Só documento** | Especificação escrita, sem contrapartida no código | + +--- + +## 3. Visão geral + +| Funcionalidade | Situação | O que falta | Documento | +|---|---|---|---| +| Autenticação e sessão | 🟢 | — | [permissoes.md](permissoes-papeis/permissoes.md) | +| Convites | 🟢 | — | [invite.md](convite/invite.md) | +| Solicitação de convite | 🟢 | — | [invite-request.md](convite/invite-request.md) | +| Skills | 🟢 | — | [gestao-skills.md](skills/gestao-skills.md) | +| Tech stacks | 🟢 | — | [gestao-stacks.md](tech-stacks/gestao-stacks.md) | +| Painel administrativo | 🟢 | — | [painel-administrativo.md](adminstrativo/painel-administrativo.md) | +| Portfólio público | 🟢 | — | [portfolio.md](portfolio/portfolio.md) | +| Perfil de usuário | 🟢 | — | [perfis-usuario.md](usuario/perfis-usuario.md) | +| Projetos em equipe | 🟡 | Encerramento manual e notificação da equipe | [gestao-projetos.md](projetos/gestao-projetos.md) | +| Certificados | 🟡 | Tela para a pessoa cadastrar os próprios certificados | [portfolio.md](portfolio/portfolio.md) | +| Jornada de entrada | 🟡 | Página existe; onboarding pós-cadastro não | [how-to-join.md](jornada-de-entrada/jornada-de-entrada-how-to-join.md) | +| **Feedback e reputação** | 🔴 | **A tela onde se avalia o colega** | [feedback-reputacao.md](feedback/feedback-reputacao.md) | +| Dashboard do membro | 🔴 | A tela inteira | — | +| Conteúdos informativos (FAQ) | 🔴 | A tela inteira | [conteudos-informativos-e-educacionais.md](conteudos/conteudos-informativos-e-educacionais.md) | +| Fórum | ⚪ | Tudo | — | + +--- + +## 4. O que exige decisão agora + +### 🔴 Feedback e reputação + +**É a funcionalidade mais avançada entre as não concluídas — e a que menos +parece.** + +O que já existe: + +``` +✅ POST/GET /api/feedback criar e listar +✅ GET /api/feedback/[id] consultar +✅ GET /api/dashboard/feedbacks agregação para o painel +✅ PortfolioFeedbackSection exibição no portfólio público +✅ Modelo Feedback no schema.prisma com rating, comment, anonymous +``` + +O que falta: + +``` +⛔ /dashboard/feedbacks — 10 linhas +``` + +Ou seja: **dá para gravar feedback pela API e ele aparece no portfólio, mas não +existe tela onde a pessoa avalia o colega.** O caminho está construído dos dois +lados e falta o meio. + +**Decisões pendentes de produto**, registradas no documento da funcionalidade mas +ainda não fechadas: + +- a avaliação é granular por competência ou uma nota única? +- o que fica visível no portfólio público — média, distribuição, comentários? +- como evitar que uma nota baixa desmotive, dado que o objetivo é formar pessoas? +- feedback anônimo é opcional ou padrão? + +> 💡 O modelo `Feedback` já tem os campos `rating`, `comment` e `anonymous`. +> Granularidade por competência exigiria mudança de schema — vale decidir **antes** +> de construir a tela. + +### 🔴 Dashboard do membro + +`/dashboard` é a **primeira tela que a pessoa vê ao entrar**, e hoje é um +placeholder de 24 linhas. Não há documento de produto para ela. + +Existe o épico [#630](https://github.com/TryCatch-ForMatch/trycatch/issues/630) +com as issues #631, #635, #636 e #637, mas nenhum documento na camada 2. + +### 🟡 Projetos em equipe + +O grosso funciona: criar, listar, detalhar, editar, assumir stack. Falta o +encerramento manual, previsto no épico +[#553](https://github.com/TryCatch-ForMatch/trycatch/issues/553). + +> ⚠️ **A regra de bloqueio de edição após formação da equipe está desativada.** +> Ela travava a edição por completo por um defeito na comparação de datas. A +> direção acordada é **notificar as pessoas envolvidas** em vez de bloquear — +> decisão de produto ainda a desenhar. + +--- + +## 5. Onde a documentação diverge do código + +Levantado em 16/08/2026. O Documento 0, seção 4, trata divergência entre +documentação e código como falha de qualidade. + +| Documento | Diz | Realidade | +|---|---|---| +| `feedback-reputacao.md` | *"Versão consolidada alinhada ao schema.prisma"* | Sem tela de avaliação | +| `conteudos-informativos-e-educacionais.md` | *"Documento inicial consolidado"* | FAQ é placeholder | +| `jornada-de-entrada-how-to-join-ux.md` | *"Estrutura proposta para validação de UX"* | Página pública existe | + +A causa não é descuido: **o campo `Status` desses documentos descreve o estado do +documento, não o da funcionalidade.** "Alinhada ao schema" significa que o texto +bate com o banco — não que exista tela. + +Por isso os documentos de produto passam a ter **dois campos** (ver seção 6). + +--- + +## 6. Como manter isto atualizado + +Cada documento de produto deve declarar os dois estados no cabeçalho: + +```markdown +**Status do documento:** consolidado · alinhado ao schema.prisma +**Status da implementação:** 🟡 parcial — API pronta, tela de avaliação pendente +``` + +O primeiro responde *"este texto é confiável?"*. O segundo, *"isto está no ar?"*. + +**Quando atualizar:** + +- ao mergear um PR que conclui ou avança uma funcionalidade; +- ao criar um documento de produto novo; +- ao descobrir divergência entre documento e código. + +**Quem atualiza:** quem abre o PR que muda o estado. A revisão confere. + +> 💡 Este documento é um índice, não a fonte da verdade. A fonte é o código. Ao +> encontrar divergência, corrija aqui **e** avise — divergência costuma indicar +> que algo mudou sem passar pela documentação. + +--- + +## 7. Histórico de Revisão + +| Data | Alteração | +|---|---| +| 16/08/2026 | Criação, a partir de levantamento das rotas de API, telas e componentes | diff --git a/docs/02 - produto/feedback/feedback-reputacao.md b/docs/02 - produto/feedback/feedback-reputacao.md index 0b826048..e5ced984 100644 --- a/docs/02 - produto/feedback/feedback-reputacao.md +++ b/docs/02 - produto/feedback/feedback-reputacao.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Versão consolidada alinhada ao schema.prisma +**Status do documento:** Versão consolidada alinhada ao schema.prisma +**Status da implementação:** 🔴 não iniciada — API e exibição prontas, falta a tela de avaliação +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join-ux.md b/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join-ux.md index de61f0dc..98c412fd 100644 --- a/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join-ux.md +++ b/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join-ux.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / UX\ Camada: 2 --- Produto\ -Status: Estrutura proposta para validação de UX baseada na issue #570 +**Status do documento:** Estrutura proposta para validação de UX baseada na issue #570 +**Status da implementação:** 🟡 parcial — página pública existe; onboarding pós-cadastro não +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join.md b/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join.md index b2cd1985..48980c07 100644 --- a/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join.md +++ b/docs/02 - produto/jornada-de-entrada/jornada-de-entrada-how-to-join.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Jornada\ Camada: 2 --- Produto\ -Status: Versão inicial baseada na issue #569 +**Status do documento:** Versão inicial baseada na issue #569 +**Status da implementação:** 🟡 parcial — página pública existe; onboarding pós-cadastro não +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/permissoes-papeis/permissoes.md b/docs/02 - produto/permissoes-papeis/permissoes.md index 3c0d3e21..2b1c82f2 100644 --- a/docs/02 - produto/permissoes-papeis/permissoes.md +++ b/docs/02 - produto/permissoes-papeis/permissoes.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Versão consolidada baseada no schema.prisma +**Status do documento:** Versão consolidada baseada no schema.prisma +**Status da implementação:** 🟢 completa — papéis aplicados via checkAuth nas rotas +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/portfolio/portfolio.md b/docs/02 - produto/portfolio/portfolio.md index be148277..744b39e5 100644 --- a/docs/02 - produto/portfolio/portfolio.md +++ b/docs/02 - produto/portfolio/portfolio.md @@ -2,7 +2,9 @@ **Classificação:** Documento de Produto / Funcionalidade\ **Camada:** 2 — Documentos de Produto e Funcionalidades\ -**Status:** Implementado (versão consolidada com visibilidade e segurança) +**Status do documento:** Implementado (versão consolidada com visibilidade e segurança) +**Status da implementação:** 🟢 completa — portfólio público, listagem e controle de visibilidade +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) --- diff --git a/docs/02 - produto/projetos/gestao-projetos.md b/docs/02 - produto/projetos/gestao-projetos.md index b38eb9d6..a12ae502 100644 --- a/docs/02 - produto/projetos/gestao-projetos.md +++ b/docs/02 - produto/projetos/gestao-projetos.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Versão atualizada com regra de edição controlada e encerramento +**Status do documento:** Versão atualizada com regra de edição controlada e encerramento +**Status da implementação:** 🟡 parcial — falta encerramento manual e notificação da equipe +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) manual ------------------------------------------------------------------------ diff --git a/docs/02 - produto/skills/gestao-skills.md b/docs/02 - produto/skills/gestao-skills.md index 5187a707..c60c4b6d 100644 --- a/docs/02 - produto/skills/gestao-skills.md +++ b/docs/02 - produto/skills/gestao-skills.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Versão consolidada baseada no schema.prisma +**Status do documento:** Versão consolidada baseada no schema.prisma +**Status da implementação:** 🟢 completa — CRUD no painel e vínculo com usuários e projetos +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/tech-stacks/gestao-stacks.md b/docs/02 - produto/tech-stacks/gestao-stacks.md index 7eeb0bf1..915491fd 100644 --- a/docs/02 - produto/tech-stacks/gestao-stacks.md +++ b/docs/02 - produto/tech-stacks/gestao-stacks.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Versão consolidada baseada no schema.prisma +**Status do documento:** Versão consolidada baseada no schema.prisma +**Status da implementação:** 🟢 completa — CRUD no painel e vínculo com projetos +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------ diff --git a/docs/02 - produto/usuario/perfis-usuario.md b/docs/02 - produto/usuario/perfis-usuario.md index 7679693d..34b2fa30 100644 --- a/docs/02 - produto/usuario/perfis-usuario.md +++ b/docs/02 - produto/usuario/perfis-usuario.md @@ -2,7 +2,9 @@ Classificação: Documento de Produto / Funcionalidade\ Camada: 2 --- Produto\ -Status: Atualizado após implementação do Portfólio Público e correções de Disponibilidade +**Status do documento:** Atualizado após implementação do Portfólio Público e correções de Disponibilidade +**Status da implementação:** 🟡 parcial — perfil e disponibilidade prontos; falta cadastrar certificados +**Estado consolidado:** ver [estado-das-funcionalidades.md](../estado-das-funcionalidades.md) ------------------------------------------------------------------------