Pular para conteúdo

Acertar a documentação que envelheceu em silêncio: ROADMAP, inventário de telas e o worker

Motivação

Documentação errada é pior que documentação ausente: ninguém desconfia dela. O ROADMAP.md estava parado desde 2026-07-24 enquanto as specs 0005 a 0054 eram entregues, e descrevia um produto que não é mais este — dava a cobrança recorrente como ausente, a taxa setup como pendente e os bureaus de crédito como fora de escopo, sendo que os três foram entregues. O CLAUDE.md do apps/web descrevia o scaffold do Refine: API falsa, auth mock, identidade "John Doe". E o CLAUDE.md da raiz não mencionava o worker arq, que roda nos três ambientes.

Dois desses erros custam trabalho de verdade. O inventário de telas é a régua obrigatória de escopo para correção que atravessa telas (regra do CLAUDE.md da raiz, nascida do fix 0015) — e faltavam duas telas nele, então uma correção escopada por ele deixaria as duas de fora por desenho. E a lição sobre a sider mandava editar custom-sider/index.tsx, arquivo onde os grupos já não vivem: seguir a instrução mudaria a sider do desktop e deixaria a gaveta do mobile para trás.

Comportamento atual

  • ROADMAP.md congelado em julho: cobrança recorrente "não implementada", taxa setup "falta", bureaus "fora do escopo", Contract/Proposal como entidades vivas, repasse mensal descrito como regra única do domínio, e uma lista de dívida técnica com três itens já resolvidos (e2e bloqueado, infra/prd nunca buildou, restos do template).
  • apps/web/CLAUDE.md: inventário sem Minha Imobiliária e sem Novidades; seção Architecture descrevendo o template do Refine; docs.garantora.test, que não existe desde que o local virou origem única; passo 2 da lição da sider apontando para o arquivo errado.
  • CLAUDE.md da raiz: sem infra/dev-remote/ na estrutura, sem o worker arq/Redis, sem make worker-dev, e afirmando que pages/blog-posts/ e pages/categories/ são restos do template.

Comportamento desejado

Cada afirmação desses arquivos confere com o código de hoje, e as que mudaram dizem o que mudou — não só o valor novo. As contagens que envelhecem viram comando.

Escopo

ROADMAP.md, CLAUDE.md da raiz, apps/web/CLAUDE.md e a linha de ajuda de local-up no Makefile. Nenhum código de produto.

Fora do escopo

O apps/api/CLAUDE.md está errado do mesmo jeito, e não foi tocado aqui. O diagrama de domínio dele ainda fala em Persons, Proposals, ProposalTenants/ProposalOwners, Analysis, PersonDocuments e PropertyOwners — nomes que a spec 0007 aposentou —, cita POST /proposals/{id}/analysis/approve, e abre dizendo que "each tenant is a real estate company (imobiliária)", quando o tenant é a garantidora e a imobiliária é a parceira. É uma reescrita de diagrama de domínio, com mais superfície de erro que tudo o que este ajuste fez junto, e merece uma rodada própria.

A dívida técnica em si também fica de fora: este ajuste corrige a lista, não paga nenhum item dela.

Alterações propostas

  • ROADMAP.md — reescrito contra o código, com arquivo:linha em cada afirmação. O cabeçalho registra o que estava errado e por quê; a situação por processo, as tabelas de implementado/parcial/ausente e o plano de entregas passam a refletir as specs 0048, 0050, 0051, 0052 e 0054; a dívida técnica ganha os três itens resolvidos numa seção própria, em vez de sumirem sem explicação.
  • CLAUDE.md (raiz) — infra/dev-remote/ na estrutura, o worker arq/Redis e o que ele processa, make worker-dev nos comandos, Redis no local-up, e o item do template trocado pelo que se mediu.
  • apps/web/CLAUDE.md — Minha Imobiliária e Novidades (mais unauthorized e not-found) no inventário; Architecture, Providers e Theming descrevendo o app real; a URL de documentação corrigida; o passo 2 da lição da sider apontando para navigation/nav-groups.tsx.
  • Makefile — a linha de ajuda de local-up menciona o Redis, que a stack sobe desde que o worker existe.

Impactos

Nenhum no produto: nada em apps/*/src foi tocado, não há comportamento novo para alguém de fora perceber, e por isso este ajuste não publica versão nem tag.

Reverte uma decisão registrada, e é o aviso que o CLAUDE.md pede: a decisão de 2026-07-26 de deixar os bureaus de crédito fora do escopo foi revertida pelas specs 0050 e 0052, que integraram API Full / SCPC Boa Vista e Quod. O ROADMAP agora marca a decisão como revertida em vez de apagá-la — o que continua valendo dela é que o bureau não decide: a recomendação segue na regra 3×.

Registra também uma entrega que foi desfeita: a Cláusula Obrigatória da spec 0003 saiu do produto no fix 0009, e estava listada como implementada sem ressalva.

Validação

make preflight — limpo, incluindo a checagem de citação arquivo:linha, que passou a examinar as citações novas do ROADMAP.

Cada afirmação reescrita foi conferida contra o código antes de ser escrita, não depois: ausência de Claim, approved_initial_fee_value no AnalysisDecisionRequest, ParticipantRole.CO_RESPONSIBLE, o calendário mensal em guarantee_service.py, os três canais de BillingChannel, a ausência de partner_agency_id nos filtros do resumo, a ausência de "autentique" em apps/api/, o cliente HTTP do bureau, os dois jobs agendados do worker, e as sete afirmações da lista de dívida técnica.

Não há suíte a rodar: o diff não tem uma linha de TypeScript nem de Python.

Documentos relacionados

ADR-0004 — documentação como código, que é o que torna esta correção um diff revisável em vez de uma página editada em silêncio. ADR-0003 — a origem única em localhost:8080, que aposentou o docs.garantora.test citado no apps/web/CLAUDE.md.