NNNN — ¶

Status: RASCUNHO → APROVADA → EM IMPLEMENTAÇÃO → CONCLUÍDA

A spec tem três partes, escritas em ordem, e quatro portões — cada um revisado por um subagente de contexto limpo, em até 3 rodadas. A máquina de revisão é do plugin superpowers; a régua é a rubrica correspondente em .claude/rubrics/. Achados vêm classificados: qualquer Critical reprova, Important em aberto reprova salvo decisão registrada do usuário, e Minor vira pendência aceita.

1. A Parte I diz qual é o problema e como se convive com ele hoje. Revisada na seção 6 (necessidade × jornada de hoje). É o portão mais barato de todos, e o único que pergunta contra que problema isto está sendo construído.
2. A Parte II diz como se usa o que vai existir. Revisada na seção 8 (jornada × viewports).
3. A Parte III diz como se constrói. Revisada na seção 16 (segurança × clareza técnica) — autorização, isolamento, e se sobrou decisão para quem vai codar.
4. A implementação é medida contra as três, na seção 17 (aderência × qualidade × testes) — uma revisão por fase, e uma da branch inteira antes de fechar.

Cada parte só se escreve depois que a anterior passou. Descrever tela sobre problema mal enquadrado, ou detalhar endpoint sobre experiência vaga, é o jeito mais caro de descobrir que era outra coisa.

Parte I — O problema¶

Aqui não entra solução: nem tela, nem endpoint, nem botão. Só o que dói, para quem, e o que se faz hoje. Se você já sabe qual é a tela, guarde para a Parte II.

1. Dor¶

O que dói hoje, do ponto de vista de quem usa o sistema — nunca do código. O custo de não fazer é parte da dor: tempo perdido, retrabalho, erro que chega ao cliente, informação que não existe quando alguém pergunta. Se não dá para explicar sem citar arquivo, provavelmente é tarefa técnica, não feature.

2. Quem sente¶

Os papéis afetados (ADMIN_TENANT, ANALYST, OPERATOR, AGENCY_USER, …), em que momento do fluxo, com que frequência e para quantas pessoas. Quem sente mais, primeiro. "O usuário" não é resposta — uma dor sem dono é uma preferência.

3. A jornada de hoje¶

Como a pessoa resolve isto agora, sem a feature — do gatilho ao desfecho, passo a passo. É a metade que costuma faltar, e é o que torna a dor conferível: uma jornada atual bem descrita prova que alguém foi olhar, em vez de imaginar.

• O caminho, ponta a ponta — incluindo o que acontece fora do sistema: a planilha paralela, o WhatsApp com a imobiliária, o telefonema, a conferência no papel. Um caminho que só passa por dentro do produto quase sempre é o imaginado, não o real.
• Onde exatamente quebra — em que passo dói, e por quê. "O processo é ruim" não localiza nada.
• O que já se tentou — contorno em uso, processo combinado, campo usado para outra coisa, feature antiga que não pegou.

4. Resultado esperado¶

O que passa a ser possível, e como se sabe que resolveu. Não precisa ser métrica instrumentada — precisa ser verificável: passos que somem, informação que deixa de ser pedida, erro que deixa de acontecer, tempo que cai.

5. Fora de escopo¶

O que não entra. Esta seção é o que impede a spec de crescer durante a implementação — seja explícito sobre o que foi cogitado e deixado de fora, e por quê. Lista genérica não vale.

6. Revisão do problema¶

Preenchido pela revisão do design (Superpowers brainstorming), rubrica .claude/rubrics/problema.md. Registrar todas as rodadas, inclusive as reprovadas.

Resultado: aprovada na rodada N.

Pendências aceitas: o que a revisão ainda apontou e se decidiu não resolver, com o porquê. Vazio se não houver.

Parte II — A experiência¶

Não preencher antes da revisão da seção 6 estar aprovada.

7. Jornada pretendida¶

A feature vista pelo usuário, antes de qualquer decisão técnica.

• Ponto de entrada: por onde ele chega — menu, link de outra tela, e-mail, retorno de uma ação.
• Jornada, caso feliz: os passos do começo ao fim. Passos, não telas.
• Custo de uso: o que ele precisa saber e digitar; e o que o sistema já sabe e por isso não deve perguntar.

7.1 Desktop¶

O que fica visível ao mesmo tempo, o que exige rolar, onde ficam as ações, quantos passos até concluir. Se é lista: quais colunas, e o que se faz a partir de uma linha.

7.2 Mobile (375px)¶

Obrigatório, e escrito — não prometido. "Será responsivo" não é resposta; a pergunta é o que acontece com este conteúdo em 375px:

• A tabela vira RecordCard com quais campos? Qual o LoadMore?
• Os filtros colapsam em MobileFilterBar/FilterPill? Quais sobrevivem?
• As ações cabem no topo, ou viram ícone de 44px?
• Algo não aparece no celular? Qual, e por quê?
• O formulário é longo? O que o teclado virtual cobre?

Se o comportamento é mesmo idêntico ao desktop, diga isso com o motivo ("são três campos empilhados; só muda a largura"). A frase sozinha, sobre uma tela larga, é lacuna.

Sem interface nenhuma (spec de infraestrutura ou ferramental)? Escreva "sem interface de usuário" aqui e diga por quê. Só vale se for verdade: se alguém vê ou opera algo, tem interface.

7.3 Estados¶

Vazio, carregando, erro e sem permissão. O que a tela mostra, e o que o usuário lê quando dá errado — com a saída, não só o aviso. Se um estado se comporta diferente nos dois viewports, diga onde.

8. Revisão da experiência¶

Preenchido pela revisão do design (Superpowers brainstorming), rubrica .claude/rubrics/experiencia.md. Registrar todas as rodadas, inclusive as reprovadas.

Resultado: aprovada na rodada N.

Pendências aceitas: o que a revisão ainda apontou e se decidiu não resolver, com o porquê. Vazio se não houver.

Parte III — Detalhamento¶

Não preencher antes das revisões das seções 6 e 8 estarem aprovadas.

9. Regras de negócio¶

Numeradas, para poderem ser citadas em revisão e nos testes.

• RN1. …
• RN2. …

Incluir aqui: validações, transições de status e o que acontece nos caminhos de erro. Autorização tem seção própria (10) — não dilua as regras de acesso no meio das demais.

10. Autorização e isolamento¶

Seção obrigatória. É onde se decide, antes de existir código, quem alcança o quê — e é o que o portão da seção 16 mede com mais rigor. Silêncio aqui não é "o padrão": o BaseRepository filtra por tenant sozinho, mas não resolve FK vinda do corpo, não escolhe entre 404 e 403, e não filtra nada para o ADMIN_GLOBAL.

10.1 Matriz de papéis¶

O negativo é tão importante quanto o positivo — é ele que vira teste.

10.2 Permissões¶

As resource:action exigidas por endpoint. Permissão nova precisa dizer em que papéis entra no rbac_seed.py. Permissão declarada e não exigida por nenhum endpoint é pior que ausente: responde "sim" a isto está protegido? sem proteger.

10.3 Isolamento por garantidora (tenant)¶

• FKs recebidas no corpo e onde cada uma é resolvida no escopo do solicitante antes de gravar — é o que fecha leitura-por-escrita.
• Registro de outro tenant → 404, nunca 403. 403 fica para o que o usuário não pode fazer no próprio tenant.

10.4 Isolamento por imobiliária¶

O que o AGENCY_USER alcança e o que responde 404. De onde vem o vínculo (partner_agency_id) — derivado, nunca aceito do corpo. Documento herda o escopo do dono: nem metadado, nem download, nem contagem.

10.5 Plataforma × cliente (SaaS admin)¶

• Quando quem chama é ADMIN_GLOBAL, o que este endpoint devolve? Ele não tem filtro de tenant. Cross-tenant é aceitável em dado de plataforma (garantidoras, convites, planos); não é aceitável em dado de negócio do cliente (inquilino, imóvel, análise, garantia, cobrança, documento).
• A tela do SaaS admin (/app/admin/*) passa a mostrar algo novo? Ela administra a plataforma — contagem agregada por garantidora é uma coisa, registro de inquilino é outra. E nenhuma tela da garantidora aceita tenant_id de fora.

Sem impacto de segurança? Escreva e justifique. Só vale se for verdade: endpoint novo, campo novo na resposta, filtro, item de menu ou coluna nova numa lista são exposição de dado.

11. Impacto por app¶

apps/api¶

• Modelos/migrations: …
• Endpoints: método, path, permissão exigida (a mesma da seção 10.2), request e response
• Regras no service: … — incluindo onde cada FK do corpo é resolvida no escopo
• Testes: os do caminho feliz e os de acesso negado (papel errado, tenant errado, imobiliária errada), que são o que sustenta a seção 10

apps/web¶

• Páginas/componentes: …
• data-testid: listar os atributos novos — é o que sustenta o e2e
• Sider: se for módulo novo, lembrar que App.tsx e components/custom-sider/index.tsx precisam ser atualizados
• Menu e rota por permissão: que papéis veem o item, e o que acontece com quem digita a URL direto — esconder o menu não protege a rota
• Responsividade & PWA: como a Parte II vira layout em desktop e mobile e, se relevante, impacto no PWA (offline, instalação, cache de assets)

apps/e2e¶

• Specs: cenários a cobrir
• Seeds: dados novos em tests/fixtures/seeds/

Se algum app não é afetado, escrever "sem impacto" explicitamente — vale mais que a seção ausente.

12. Contrato de API¶

POST /api/v1/<recurso>
Authorization: Bearer <token>

{ "campo": "valor" }

{ "id": "uuid", "campo": "valor" }

Para cada endpoint: permissão exigida, erros previstos e seus códigos de negócio — incluindo o 404 de registro alheio e o 403 de ação não permitida no próprio tenant.

Migration: nome, o que faz e o downgrade correspondente — é o caminho de volta de um deploy ruim, não higiene.

13. Critérios de aceite¶

Cada item precisa ser verificável por alguém que não escreveu o código. Cobrir também o que a Parte II prometeu — jornada, mobile e estados.

Se a feature toca autorização, exige-se pelo menos um CA negativo por papel afetado: "o AGENCY_USER da Imobiliária B recebe 404 ao abrir o imóvel da A" é critério; "respeita as permissões" não é.

• [ ] CA1. Dado … quando … então …
• [ ] CA2. …

14. Plano de implementação¶

Ordem obrigatória no monorepo: api → web → e2e.

• [ ] apps/api — model → schema → repository → service → router
• [ ] apps/api — migration Alembic
• [ ] apps/api — docstrings + Swagger (summary, description, response_description)
• [ ] apps/api — testes em tests/
• [ ] apps/web — página/campo, com data-testid em todo elemento interativo, responsivo (desktop e mobile) e com o PWA em mente
• [ ] apps/e2e — spec cobrindo o fluxo, e seed se necessário
• [ ] make test e make lint passando
• [ ] Validado no browser em desktop e mobile (e, se build/PWA, reabrindo a tela instalada para furar o cache)

15. Decisões em aberto¶

Perguntas que travam a implementação, com quem decide. Esvaziar antes de passar o status para APROVADA.

• [ ] …

16. Revisão do detalhamento¶

Preenchido pela revisão do design (Superpowers brainstorming), rubrica .claude/rubrics/detalhamento.md. Registrar todas as rodadas, inclusive as reprovadas.

Resultado: aprovada na rodada N.

Riscos aceitos: risco de acesso que a revisão apontou e se decidiu não fechar nesta spec, com quem decidiu e por quê. Vazio se não houver — e o esperado é que esteja vazio.

17. Revisão da implementação¶

Preenchido pelas revisões do Superpowers requesting-code-review, rubrica .claude/rubrics/implementacao.md. As revisões de fase (api, web, e2e) vão nas primeiras linhas; a da branch inteira, na última.

Resultado: aprovada na rodada N da revisão de branch.

Defeitos aceitos: o que a revisão apontou e se decidiu não corrigir nesta spec, com quem decidiu e por quê. Vazio se não houver.

18. Registro¶

Anotações durante a implementação: o que mudou em relação ao planejado e por quê. Preencher ao implementar.

Afirmações conferidas¶

Fatos sobre o repositório que uma rodada de portão já conferiu abrindo o arquivo. O recortar.py leva esta seção junto em qualquer parte, e o revisor da rodada seguinte pode tomá-los como dados em vez de reconferir tudo do zero.

Duas regras, e a segunda é a que faz a primeira valer:

1. Só entra o que um revisor conferiu — não o que você conferiu ao escrever. O ponto é aproveitar trabalho já pago por uma rodada, não abrir atalho para afirmar sem prova.
2. Mexeu na frase da spec, a linha sai da tabela. A afirmação volta a ser conferível. Sem isso a tabela vira o oposto do portão: uma afirmação carimbada como verdadeira porque um dia foi.

Feature sem afirmação sobre o repositório não precisa da seção — apague-a.