Sessão 3 — Expansão pra site de documentação

Minhas palavras

(preencher)

---

Detalhamento (IA)

Contexto

Sessao 2 subiu /scopo como pagina unica de 849 linhas lendo docs/ em build. Funcionou como painel visual — mas a analise externa do desbloqueio P1-P6 expos que documentacao densa + auditavel externamente e uma regra do metodo, nao so um efeito colateral. Isso mudou a ambicao: de "uma pagina que mostra o escopo" pra "site de documentacao navegavel do projeto inteiro".

Esta sessao transforma /scopo numa base de secoes reutilizaveis e abre rotas dedicadas por tipo de documento + consolida P1-P6 em ADRs proprios.

O que foi construido

1. Desbloqueio P1-P6 materializado em ADRs (commits 59770c2 + ec0f066):

• docs/decisoes/0004-cliente-alvo-v1.md — posto SP (vertical + municipio)
• docs/decisoes/0005-modelagem-dominio.md — Empresa / CatalogoLicenca / LicencaDaEmpresa
• docs/decisoes/0006-responsabilidade-tecnica.md — Rafa CTO, Claude executor
• docs/decisoes/0007-modelo-cobranca.md — ~R$10/licenca ativa, split 50/50
• docs/decisoes/0008-modelo-operacional.md — Rafa arquiteta, Ale prospecta
• ADR 0003 marcado como superado (propostas viraram ADRs proprios)
• Todos em status "aceito por coerencia, aguarda ratificacao com Ale"
• TASKS.md reorganizado: Sprint 0 em 5 frentes paralelas (A custo, B mercado, C catalogo, D parceria, E DoD) — 14 tasks sem bloqueio cruzado
• STATUS.md foi pra 18%, 0 bloqueios criticos
• aprendizados.md ganhou regra "bloqueio humano nao trava execucao indefinidamente" (vira candidata a entrar nas 17)

2. Refactor de fundacao (commit 0d784b1):

• 17 Section() inline em app/scopo/page.tsx extraidas pra components/sections/*.tsx isolados (Hero, Status, Versoes, Blocos, C4, Dominio, Fluxos, Perguntas, Riscos, ADRs, Stack, BlocoRegra, Sprint, NaoResolvido, Aprendizados, Playbook, Footer)
• /scopo continua visualmente identico — so importa dos novos modulos
• Fundacao pra reuso nas rotas novas

3. Navegacao global (commit efb4753):

• components/layout/TopNav.tsx — nav fixa no topo de todas as paginas + widget de mini-status (fase, %, bloqueios)
• components/layout/PageLayout.tsx — wrapper com eyebrow/title/description/breadcrumb
• lib/docs.ts ganha getADRByNumero, getSessaoByNumero, getEnsaioBySlug, loadVersoesSummary (pra alimentar rotas dinamicas)
• layout.tsx injeta TopNav globalmente

4. Hub em / (commit 3b22336):

• Raiz deixa de ser redirect pra /scopo
• Agora e hub do projeto: VersionCard v1-v4 (ativa/backlog) + DocCard navegacao por tipo (ADRs, Requisitos, Arquitetura, Playbook, Aprendizados, Escopo v1)

5. /scopo-v1 + redirect permanente (commit 65efa19):

• Nova rota /scopo-v1 com recorte especifico da v1: bloco A (Mapeamento), fluxos v1, 4 blocos, perguntas, nav pros docs complementares
• Nao duplica ADRs nem arquitetura completa
• /scopo vira permanentRedirect 308 pra /scopo-v1 (backwards compat)

6. Rotas dedicadas por tipo de documento (commit c090ea6):

• /adrs (index) + /adrs/[numero] (detail)
• /requisitos, /arquitetura, /aprendizados
• /playbook (index) + /playbook/sessao/[numero] + /playbook/ensaio/[slug]
• Rotas dinamicas usam generateStaticParams pra pre-renderizar em build
• components/markdown/Prose.tsx renderiza markdown completo (react-markdown + remark-gfm) nas rotas detail

7. /panorama (commit f9d39aa):

• Rota unica que monta todas as sections na mesma pagina
• Pra bater o olho e ver o projeto inteiro sem clicar
• Sem gestao (TASKS/sprint ficam fora do site publico)
• Linkado no TopNav e no hub

Arquitetura resultante

/                       hub com cards de versoes + tipos de doc
/panorama               tudo na mesma pagina (consolidado)
/scopo                  redirect 308 -> /scopo-v1 (legado)
/scopo-v1               recorte focado na v1 ativa
/adrs                   index de ADRs
/adrs/0001              detail markdown
/requisitos             render de docs/requisitos.md
/arquitetura            render de docs/arquitetura.md
/playbook               index de sessoes + ensaios
/playbook/sessao/01     detail de sessao
/playbook/ensaio/slug   detail de ensaio
/aprendizados           render de docs/aprendizados.md

Todas sao server components com force-static — leem filesystem em build, runtime e CDN puro.

Divida tecnica acumulada

Da sessao 2, nada foi pago:

1. Migrar pro docker --context vps-rafael compose up (Regra 7) — ainda pendente, esperando permissoes do sandbox
2. Limpar workspace /home/claude/apps/scopo-glc no VPS apos migracao
3. Script ./deploy.sh ou hook pra git push -> rebuild automatico

Novo nesta sessao: nenhum. Toda a expansao do site foi feita em codigo, sem mexer em infra.

Verificacao

• git log --oneline origin/master..HEAD -> 8 commits
• git push origin master -> 7402a58..f9d39aa master -> master ok
• Rebuild do site na VPS depende do fluxo: como deploy ainda e manual (divida da sessao 2), push nao dispara rebuild automatico. Pra ver /panorama, /adrs, /requisitos etc em https://scopo-glc.rafaelcamargo.online, precisa re-rodar o container na VPS.

Commits (8, empurrados nesta sessao)

59770c2 chore(adrs): promove P1-P6 a ADRs 0004-0008 aceitos por coerencia
ec0f066 chore: reflete desbloqueio P1-P6 em TASKS STATUS requisitos aprendizados
0d784b1 refactor(web): extrai sections inline do /scopo para components/sections
efb4753 feat(web): navegacao global com TopNav PageLayout e helpers
3b22336 feat(web): hub em / com cards de versoes e documentacao
65efa19 feat(web): /scopo-v1 focado em recorte v1 + redirect permanente /scopo
c090ea6 feat(web): rotas dedicadas por tipo de documento com markdown rendering
f9d39aa feat(web): /panorama com visao consolidada do projeto

Proximo passo (sessao 4)

1. Rafa cola bloco de permissoes em .claude/settings.local.json (Bash(docker --context vps-rafael *), Bash(docker compose *), Bash(ssh vps-rafael *))
2. Sessao 4 migra deploy pro docker-compose, rebuild puxa todas as rotas novas em prod
3. Confirma URLs /panorama, /adrs, /requisitos etc no ar
4. Agenda call com Ale pra ratificar ADRs 0004-0008 (bloqueio ha 3 sessoes)
5. Se call acontecer, abre Sprint 1 tecnica (dependia de ADRs ratificados)