Skip to content

api-contracts.md

Latest commit

 

History

History
199 lines (161 loc) · 7.87 KB

api-contracts.md

File metadata and controls

199 lines (161 loc) · 7.87 KB
Raw

Contratos da API REST e Schemas JSON — BacklogForge

Este documento detalha os contratos dos endpoints REST disponibilizados pelo backend do BacklogForge, bem como a especificação completa do schema JSON retornado pela inteligência artificial e os formatos de exportação.

Base URL: http://localhost:8080/api/v1/backlog
Swagger UI (Documentação Interativa): http://localhost:8080/swagger-ui.html
Especificação OpenAPI 3.0 JSON: http://localhost:8080/v3/api-docs

📡 Endpoints REST

1. POST /api/v1/backlog/generate

Gera um Product Backlog estruturado a partir de parâmetros determinísticos em JSON e texto complementar (sem anexar arquivos PDF).

  • Content-Type: application/json
  • Body da Requisição (GenerateBacklogRequest):
{
  "projectName": "Portal do Aluno FATEC",
  "sprintCount": 3,
  "sprintDurationWeeks": 3,
  "teamSize": 7,
  "technologies": ["Java 21", "Spring Boot", "React", "PostgreSQL"],
  "suggestTechnologies": false,
  "additionalText": "Sistema para acompanhamento de notas, frequências e rematrícula online dos alunos."
}

  • Validações do Contrato:

    • projectName: Obrigatório (@NotBlank), máximo de 100 caracteres.
    • sprintCount: Obrigatório (@NotNull), mínimo 1, máximo 20.
    • sprintDurationWeeks: Obrigatório (@NotNull), mínimo 1, máximo 8.
    • teamSize: Obrigatório (@NotNull), mínimo 1, máximo 50.
    • technologies: Opcional (Lista de strings).
    • suggestTechnologies: Opcional (boolean, padrão false).
    • additionalText: Opcional (máximo de 10.000 caracteres).

  • Resposta de Sucesso (HTTP 200 OK): Objeto ProductBacklog (ver schema abaixo).

2. POST /api/v1/backlog/generate-with-pdf

Gera um Product Backlog combinando os parâmetros determinísticos com o texto extraído de um ou mais arquivos PDF anexados (suportando texto vetorial e OCR multimodal para PDFs escaneados).

  • Content-Type: multipart/form-data

  • Partes da Requisição:

    • request (application/json): Objeto GenerateBacklogRequest serializado em JSON.
    • files (application/pdf, opcional): Um ou múltiplos arquivos PDF enviados no upload.

  • Resposta de Sucesso (HTTP 200 OK): Objeto ProductBacklog.

3. POST /api/v1/backlog/export-markdown

Recebe um objeto ProductBacklog e gera o conteúdo formatado em arquivo Markdown (.md) para download.

  • Content-Type: application/json
  • Body da Requisição: Objeto ProductBacklog.
  • Headers da Resposta:
    • Content-Type: text/markdown; charset=UTF-8
    • Content-Disposition: attachment; filename="Nome_Do_Projeto.md"; filename*=UTF-8''... (RFC 6266)
  • Resposta de Sucesso (HTTP 200 OK): Fluxo de bytes do arquivo Markdown.

4. POST /api/v1/backlog/export-pdf

Recebe um objeto ProductBacklog e gera o documento PDF (.pdf) com diagramação profissional, identidade visual Slate/Indigo e paginação automática.

  • Content-Type: application/json
  • Body da Requisição: Objeto ProductBacklog.
  • Headers da Resposta:
    • Content-Type: application/pdf
    • Content-Disposition: attachment; filename="Nome_Do_Projeto.pdf"; filename*=UTF-8''... (RFC 6266)
  • Resposta de Sucesso (HTTP 200 OK): Fluxo de bytes do arquivo PDF.

5. POST /api/v1/backlog/export-csv

Recebe um objeto ProductBacklog e gera um arquivo CSV (.csv) universal, estruturado e com BOM UTF-8 (\uFEFF), formatado especialmente para importação direta em ferramentas de gestão de projetos como Jira, Trello e Azure DevOps.

  • Content-Type: application/json
  • Body da Requisição: Objeto ProductBacklog.
  • Headers da Resposta:
    • Content-Type: text/csv; charset=UTF-8
    • Content-Disposition: attachment; filename="Nome_Do_Projeto_Jira.csv"; filename*=UTF-8''... (RFC 6266)
  • Estrutura das Colunas Geradas:
    • Issue Type: Tipo de item (Epic, Story ou Sub-task).
    • Issue Id: Identificador único (EPIC-001, US-001, TASK-001).
    • Parent Id: Identificador do item pai (Stories referenciam Épicos; Sub-tasks referenciam Stories).
    • Summary: Título do item.
    • Description: Descrição detalhada e critérios de aceitação.
    • Priority: Prioridade mapeada (Highest, High, Medium, Low).
    • Story Points: Pontuação Fibonacci atribuída à User Story.
    • Sprint: Nome da Sprint à qual o item está alocado (ex: Sprint 1).
    • Epic Name: Nome do Épico para visualizações em boards do Jira/Trello.
  • Resposta de Sucesso (HTTP 200 OK): Fluxo de bytes do arquivo CSV formatado.

🧩 Schema JSON do ProductBacklog

A Inteligência Artificial (Gemini) é orientada por um prompt estruturado a retornar estritamente a seguinte estrutura JSON:

{
  "projectName": "Portal do Aluno FATEC",
  "summary": "Sistema completo para gestão acadêmica e acompanhamento do histórico escolar.",
  "suggestedTechnologies": [
    "Java 21",
    "Spring Boot",
    "React",
    "PostgreSQL"
  ],
  "epics": [
    {
      "id": "EPIC-001",
      "title": "Gestão de Autenticação e Perfis",
      "description": "Épico responsável pelo controle de acesso de alunos, professores e coordenação.",
      "userStories": [
        {
          "id": "US-001",
          "title": "Autenticar Aluno",
          "description": "Como aluno, quero efetuar login com RA e senha para acessar meu boletim.",
          "priority": "CRITICAL",
          "storyPoints": 5,
          "acceptanceCriteria": [
            "Deve validar o RA e senha no banco de dados.",
            "Deve retornar um token JWT com expiração de 8 horas."
          ],
          "tasks": [
            {
              "id": "TASK-001",
              "title": "Criar endpoint de Login REST",
              "description": "Desenvolver a camada Controller e Service de autenticação.",
              "priority": "CRITICAL"
            },
            {
              "id": "TASK-002",
              "title": "Configurar Spring Security e JWT",
              "description": "Implementar filtro de validação de tokens JWT.",
              "priority": "HIGH"
            }
          ]
        }
      ]
    }
  ],
  "sprints": [
    {
      "id": "SPRINT-01",
      "name": "Sprint 1",
      "goal": "Estabelecer a fundação do sistema e a camada de autenticação dos alunos.",
      "userStoryIds": [
        "US-001"
      ]
    }
  ]
}

Regras de Domínio do Schema:

  1. Prioridades Válidas: LOW, MEDIUM, HIGH, CRITICAL.
  2. Story Points: Valores da sequência Fibonacci (1, 2, 3, 5, 8, 13).
  3. Sprints por Referência: O campo userStoryIds da Sprint armazena apenas os identificadores (ex: ["US-001", "US-002"]), evitando duplicar os dados das User Stories.
  4. Sem Atribuição de Pessoas: O objeto Task não possui campo de responsável individual.

⚠️ Schema de Respostas de Erro

Quando ocorre uma exceção tratada pelo GlobalExceptionHandler, o backend retorna a seguinte estrutura JSON:

{
  "timestamp": "2026-08-14T13:30:00.123456",
  "status": 400,
  "error": "Erro de Validação",
  "errors": {
    "projectName": "O nome do projeto é obrigatório.",
    "sprintCount": "O projeto deve ter no mínimo 1 Sprint."
  }
}

Tabela de Status HTTP da API:

Status Code Tipo de Erro Descrição
400 Bad Request Erro de Validação Parâmetros DTO inválidos ou arquivo PDF corrompido/sem extensão válida.
422 Unprocessable Entity Backlog Inválido A IA produziu um backlog que viola validações estruturais.
502 Bad Gateway Erro no Provedor de IA Erro de comunicação, limite de quota esgotado em todas as chaves ou credencial inválida no Gemini.
500 Internal Server Error Erro Inesperado Erro genérico de execução no servidor backend.