Definir contratos HTTP necessários ao frontend e estratégia de integração

[viviangiulia]

Contexto

O frontend React não deve conhecer diretamente as classes Python, entidades de domínio ou modelos ORM. A fronteira entre frontend e backend será estabelecida por contratos HTTP/JSON explícitos, implementados por schemas Pydantic.

A interface construída inicialmente com mocks revela necessidades concretas de dados que devem orientar esses contratos.

Os contratos devem representar os casos de uso da aplicação e não simplesmente expor a estrutura interna das entidades de domínio ou das tabelas do banco de dados.

Objetivo

Definir os contratos necessários para conectar os fluxos reais da interface aos casos de uso expostos pela API.

Escopo

Mapear contratos HTTP para, conforme o escopo final do MVP:

• criar orçamento;
• listar orçamentos;
• consultar orçamento;
• salvar alterações;
• gerar orçamento a partir de elementos quantificáveis;
• consultar composições;
• consultar detalhes de uma composição;
• consultar componentes;
• obter fontes, competências e UFs disponíveis;
• obter resultado consolidado;
• solicitar exportação.

Para cada operação relevante:

• definir request;
• definir response;
• definir identificadores;
• definir códigos de status;
• definir formato de erros;
• documentar o mapeamento entre DTO HTTP e domínio.

Fora de escopo

• Expor diretamente objetos SQLAlchemy.
• Serializar indiscriminadamente entidades de domínio.
• Replicar toda a estrutura interna do backend na API.
• Definir endpoints que não atendam casos de uso concretos.
• Fazer o frontend conhecer classes Python.

Critérios de aceite

• Cada fluxo obrigatório do MVP possui um contrato HTTP definido.
• Requests e responses são independentes dos modelos ORM.
• O frontend não precisa conhecer classes Python.
• Os formatos de erro estão definidos.
• Os contratos contemplam os dados realmente necessários às telas.
• Existe correspondência explícita entre contratos HTTP e casos de uso.
• Os schemas Pydantic não expõem detalhes internos desnecessários do domínio ou da persistência.

Dependências

• M3 — Fundação da API.
• Editor interativo de orçamento com categorias e composições.
• Experiência de entrada para elementos quantificáveis.
• Experiência de resultados.
• Base de Preços, caso sua integração faça parte do MVP.