Skip to content

feat(community): retrospectiva multi-fonte - #437

Draft
Clintonrocha98 wants to merge 3 commits into
4.xfrom
feature/retrospective-multi-source
Draft

feat(community): retrospectiva multi-fonte#437
Clintonrocha98 wants to merge 3 commits into
4.xfrom
feature/retrospective-multi-source

Conversation

@Clintonrocha98

@Clintonrocha98 Clintonrocha98 commented Jul 20, 2026

Copy link
Copy Markdown
Member

O que é isso

A retrospectiva é aquela página que conta o que a comunidade fez num período: quem participou, o que rolou, os destaques. É um "resumo do capítulo" da He4rt, feito para ser publicado e compartilhado.

Este é o PR guarda-chuva da feature: ele acompanha o trabalho inteiro. As entregas de verdade vêm em PRs menores, um de cada vez, apontando para esta branch.

O problema hoje

A retrospectiva atual só enxerga o GitHub: pull requests, código, quem contribuiu nos repositórios. Só que a comunidade é muito mais que isso. A vida acontece no Discord (conversas, tempo em call, reações, gente nova chegando), no WhatsApp e em outras plataformas, e nada disso aparece hoje.

O que esta feature entrega

  1. Retrospectiva de várias plataformas, não só GitHub. Cada plataforma vira um bloco na mesma página: o bloco do GitHub, o bloco do Discord, e por aí vai.
  2. Fácil de ligar uma plataforma nova. A ideia é que somar uma fonte nova (hoje Discord e WhatsApp, amanhã o que vier) seja simples, sem reescrever a página toda.
  3. O time monta e publica a edição. Em vez de a página ser só uma tela que muda sozinha, o time (Marketing/Admin) monta a retrô, escolhe o que aparece e publica. Quem visita vê o resultado pronto, tipo um "Retrospectiva do ano" que você assiste.
  4. Edição publicada fica registrada. Ao publicar, os números são congelados. A "Retro de Junho" continua mostrando o que era junho, mesmo tempos depois.

Como vai ser entregue (em fases, uma por vez)

  • Fase 1 — juntar as fontes. Trazer o Discord para a página junto do GitHub e deixar a estrutura pronta para plugar novas plataformas. A parte do GitHub continua igual à de hoje; ganha o bloco do Discord embaixo.
  • Fase 2 — montar e publicar. Poder criar, curar e publicar edições da retrospectiva, com a página pública mostrando a versão publicada.
  • Fase 3 — editor visual. Uma tela para montar a retrô de forma visual, com pré-visualização ao vivo. É melhoria de experiência: a feature já funciona 100% sem ela.
  • Depois — WhatsApp. Somar o WhatsApp como próxima plataforma, com cuidado de privacidade (sem expor telefones).

Para quem quiser o detalhe técnico

O desenho completo, com as decisões e os porquês, está documentado no módulo community:

  • app-modules/community/docs/specs/2026-07-19-retrospectiva-multi-fonte.md
  • app-modules/community/docs/adr/0001-retrospectiva-multi-fonte-via-contrato-de-source.md
  • app-modules/community/docs/adr/0002-retrospectiva-persistida-com-snapshot-ao-publicar.md

PR em draft de propósito: é o ponto de encontro da feature. Sai do draft quando as fases estiverem prontas para virar 4.x.

@Clintonrocha98
docs(community): plano, spec e ADRs da retrospectiva multi-fonte
2e418e7 
Registra o design acordado: contrato de Source em community, snapshot ao publicar, fluxo faseado e as divergencias conscientes da spec-base.
@Clintonrocha98 Clintonrocha98 mentioned this pull request Jul 20, 2026
Merged
@Clintonrocha98
feat(community): retrospectiva multi-fonte — contrato + GitHub/Discor…
9651efa 
…d (Fase 1) (#438)

## Fase 1 — Juntar as fontes

Primeira fatia da [retrospectiva
multi-fonte](#437).
Transforma a retrospectiva (hoje só GitHub, read model ao vivo no
`portal`) numa peça **plugável por fonte**: adicionar uma plataforma
passa a ser 1 classe + 1 tag no módulo dono do dado, sem tocar o
`portal`.

Aponta para a branch de integração `feature/retrospective-multi-source`.

### O que entra

**`community` (domínio) — o contrato**
- `RetrospectiveSource`: `key()` + `collect(Period, SourceFilters):
SourceResult`.
- DTOs tipados: `Period`, `SourceFilters` (hideBots + exclusions),
`Metric`, `HeadlineMetrics`, `SourceResult`, e a interface `Slide`
(`kind()` + `toArray()`).
- Nenhum import de Integration: o contrato mora no domínio, as fontes o
implementam.

**`integration-github` — `GithubSource`**
- Refatora o antigo `CommunityRetrospective` do portal preservando o
cálculo **1:1** (bots, PRs merged/unmerged, repos só com PR no recorte,
destaques por linhas).
- Empacota a saída em slides tipados (`github.panorama`, `github.repos`,
`github.highlights`, `github.core`, `github.community`).

**`activity` — `DiscordSource`** (mora aqui porque o dado — `Voice`,
`Message`, `Reaction`, `MembershipEvent` — é do `activity`)
- 5 slides: `discord.voice_board`, `discord.messages`,
`discord.new_members`, `discord.reactions`, `discord.top_message`.
- Agrega **tudo em SQL** escopado pela janela (as tabelas são grandes em
prod; `messages` ~2GB). Filtra por `sent_at`/`occurred_at` (tempo do
evento), nunca `created_at`. `hideBots` via `source_kind`. Nome de
exibição resolvido só para o topo de cada ranking.

**`portal` — orquestração**
- `RetrospectiveDeck` resolve as fontes por **tagged service**
(`retrospective.source`), ordena (github → discord) e descarta as sem
dado.
- A página compõe: cover (chips por fonte, sem soma cruzada) → bloco de
cada fonte (`kind` → componente Blade por convenção) → closing.
- Os filtros ricos do visitante (repos/tipos/desfecho/pessoa/ordenação)
foram **aposentados**: viram configuração editorial na Fase 2. Restam
recorte de período e ocultar bots.

### Fora de escopo (fica pra depois)
- Persistência/snapshot da edição e curadoria (Fase 2).
- Deck Builder visual (Fase 3).
- WhatsApp (PR aditivo).

### Notas
- **Sem migrations** nesta fase (nenhuma tabela nova).
- Testes: `GithubSource` (golden 1:1, herdado do read model antigo),
`DiscordSource` (agregações + escopo temporal + hideBots),
`RetrospectiveDeck` (ordem/descarte) e página multi-fonte.
- Na suíte completa local há 3 falhas em `BackfillRepositoryTest`
(timezone, `+00:00` vs `-03:00`) e alguns erros de `out of shared
memory` no `DROP` sob paralelismo. **Ambos são
pré-existentes/ambientais** (confirmado: o backfill falha igual na base,
e os testes de `activity` passam isolados) — não têm relação com esta
mudança.
@Clintonrocha98 Clintonrocha98 mentioned this pull request Jul 22, 2026
Merged
@Clintonrocha98
feat(community): retrospectiva persistida com snapshot ao publicar (F…
d9ed218 
…ase 2) (#444)

## Fase 2 — Persistir e publicar

Segunda fatia da [retrospectiva
multi-fonte](#437). A Fase 1
tornou a retrospectiva plugável por fonte, mas ao vivo. Esta fase a
transforma numa **peça editorial persistida**: o operador cura e
publica; ao publicar, o dado é **congelado num snapshot**; a página
pública lê o congelado, sem tocar as fontes.

Aponta para a branch de integração `feature/retrospective-multi-source`.

### O que entra

**`community` (domínio) — a entidade e o ciclo**
- Entidade `Retrospective` (`community_retrospectives`, sem `tenant_id`)
+ enum `RetrospectiveStatus` (`draft|publishing|published`, contratos
Filament).
- VOs `DeckConfig` (curadoria: ordem, on/off, exclusions) e
`RetrospectiveSnapshot` (`SourceResult[]` congelados) via casts tipados
(`AsDeckConfig`, `AsRetrospectiveSnapshot`) — nunca `array` solto.
- `FrozenSlide`: reidrata o snapshot honrando o contrato `Slide` sem o
domínio importar as classes de slide de `integration-github` (Domain →
Integration é proibido).
- Actions `CompileSnapshot` (coleta + congela) e `ComposeDeck` (aplica a
curadoria sobre o snapshot), `PublishRetrospective` + job
`CompileRetrospectiveSnapshot` (congela na fila).

**`portal` — leitura do congelado**
- `RetrospectiveDeck` removido; a orquestração migrou para o domínio.
- A página pública lê a **edição publicada mais recente** (sem filtros
do visitante). Rota de preview
`/comunidade/retrospectiva/{retrospective}/preview` para o operador
(rascunho coletado ao vivo), com guard `403` no `mount`.

**`panel-admin` — o CRUD editorial**
- `RetrospectiveResource`: **completo em capacidade** (ordem/on-off de
fonte por repeater, exclusions, textos de capa/fecho, publicar). Feio de
propósito — o Deck Builder visual é a Fase 3.
- Preview do admin e página pública compartilham o **mesmo render path**
(`ComposeDeck`), então "ver preview" bate com o publicado.

### Refinamentos registrados nos docs (spec + ADR-0002)
- `label()` novo no contrato `RetrospectiveSource` (identidade estática
das fontes, para o CRUD listar sem coletar).
- `FrozenSlide` no lugar de um registro `kind → classe` (forçado pela
regra Domain → Integration).
- Exclusions **recompilam** o snapshot (mexem no dado); ordem/on-off
**re-derivam** dele.

### Fora de escopo (Fase 3)
- Deck Builder 3 colunas (drag-drop, preview ao vivo, inspector) — puro
upgrade de UX.

### Notas
- Migration nova: `community_retrospectives` (colunas `timestamptz`,
jsonb para `deck_config`/`snapshot`).
- Testes: 63 novos/reescritos (VOs round-trip, casts,
`CompileSnapshot`/`ComposeDeck`, publish+job, página pública lê
snapshot, preview autenticado, CRUD Filament). Bateria completa: 920/923
verdes — as 3 falhas são o `BackfillRepositoryTest` (timezone `+00:00`
vs `-03:00`), **pré-existentes/ambientais**, sem relação com esta
mudança.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@Clintonrocha98 Clintonrocha98

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Clintonrocha98