🧭 ACTA Mongo API

API REST do ACTA para apoiar o ciclo PDCA (Plan, Do, Check, Act): organiza dados documentais de formulários, respostas, análises de causa, lições aprendidas e registros complementares do aprendizado contínuo.

📌 Visão geral

A API é a camada de persistência documental do ecossistema ACTA. Gerencia formulários, respostas de formulários, diagramas de Ishikawa, 5 Porquês e lições aprendidas em MongoDB. O repositório também contém modelos e contratos de relatório, ainda sem rotas HTTP.

Clientes autenticam no Firebase e enviam o Firebase ID Token para consumir as rotas protegidas. A validação do usuário autenticado é delegada para a acta-pg-api, que concentra identidade, usuários, empresas e ciclos PDCA.

🧩 Padrão de projeto: Template Method

A API utiliza uma base comum de operações CRUD na classe BaseService. Ela implementa operações de busca, listagem, inserção e exclusão dos documentos MongoDB, usando BaseRepository e BaseMapper. A atualização parcial é definida como contrato abstrato e implementada por cada serviço.

O método abstrato protegido getEntity funciona como ponto de especialização desse fluxo. Serviços como FormularioService, IshikawaService, CincoPorquesService, RespostaFormularioService e LicaoAprendidaService implementam essa etapa para localizar o documento correto, tratar ausência de registro e aplicar validações específicas.

Esse padrão foi adotado para evitar duplicação de código, manter uniforme o processo de persistência documental e permitir que cada serviço especialize somente as etapas necessárias, sem reimplementar todo o fluxo CRUD.

🧠 Padrão de projeto: Strategy

A API também utiliza Strategy para validar e preparar respostas de formulários antes da persistência. A interface ValidacaoRespostaStrategy define esse contrato, enquanto estratégias de texto, e-mail, CPF, seleção e demais formatos implementam as regras de cada TipoResposta. Para perguntas de CEP, a entrada é uma string de oito dígitos sem máscara e o endereço é preenchido pelo ViaCEP.

O componente RespostaFormularioValidator recebe as estratégias pelo Spring, organiza um mapa por tipo de resposta e delega cada validação para a estratégia correspondente. Esse padrão foi adotado para evitar condicionais extensas, isolar regras de validação por tipo de pergunta e facilitar a inclusão de novos formatos de resposta.

✨ Funcionalidades

• Gestão de formulários por ciclo PDCA.
• Respostas de formulários e validação conforme o tipo de pergunta.
• Diagramas de Ishikawa vinculados a ciclos.
• Registros de 5 Porquês vinculados a Ishikawas.
• Lições aprendidas por ciclo.
• Health check da API e do banco em GET /api/v1/health.

🛠️ Tecnologias

Tecnologia	Uso
Java 19	Linguagem e versão de compilação
Spring Boot 4.1.1	Aplicação REST e configuração
MongoDB e Spring Data MongoDB	Persistência documental
Spring Security	Autenticação e autorização
Springdoc OpenAPI 3.0.0	Documentação dos contratos HTTP
MapStruct 1.6.3	Mapeamento entre DTOs e documentos
Docker	Build e execução em contêiner

Também utiliza Maven Wrapper, Lombok, Bean Validation, Caelum Stella e RestClient.

✅ Pré-requisitos e configuração

• JDK 19 e MongoDB acessível.
• acta-pg-api acessível para validar o usuário autenticado e consultar dados relacionais como empresa, ciclo e usuário.
• Projeto Firebase configurado no ecossistema ACTA, com clientes enviando Firebase ID Token.
• Docker, caso a execução seja por imagem.

Defina as variáveis abaixo no ambiente ou em um .env local. Nunca versione senhas, tokens ou arquivos de credencial.

PORT=8081
MONGODB_URI=mongodb://localhost:27017/acta_db
ACTA_PG_API_BASE_URL=http://localhost:8080/api/v1/
ACTA_PG_API_CONNECT_TIMEOUT=3s
ACTA_PG_API_READ_TIMEOUT=5s

Variável	Uso
PORT	Porta HTTP da aplicação
MONGODB_URI	Conexão MongoDB
ACTA_PG_API_BASE_URL	URL base da API PostgreSQL usada para autenticação delegada e validações relacionais
ACTA_PG_API_CONNECT_TIMEOUT	Timeout opcional de conexão com a API PostgreSQL
ACTA_PG_API_READ_TIMEOUT	Timeout opcional de leitura da API PostgreSQL
ACTA_VIACEP_BASE_URL	Integração usada por perguntas de CEP; padrão https://viacep.com.br/ws/
ACTA_VIACEP_CONNECT_TIMEOUT, ACTA_VIACEP_READ_TIMEOUT	Timeouts opcionais do ViaCEP; padrões 3s e 5s
CORS_ALLOWED_ORIGINS	Origens permitidas, separadas por vírgula; padrão http://localhost:5173,http://localhost:3000

O .env.example é somente uma referência; Spring Boot não carrega .env automaticamente sem configuração externa.

Para execução pelo Maven, exporte as variáveis no terminal. A URL da API PostgreSQL deve incluir o prefixo das rotas e a barra final, como /api/v1/. Os padrões estão em application.properties; a consulta de perguntas de CEP exige acesso ao ViaCEP.

🚀 Execução local

.\mvnw.cmd spring-boot:run

./mvnw spring-boot:run

A API usa a porta 8081 por padrão. Com MongoDB configurado, consulte http://localhost:8081/api/v1/health.

Docker

Para criar e executar a imagem:

docker build -t acta-mongo-api .
docker run --rm -p 8081:8081 --env-file .env acta-mongo-api

Antes de executar em contêiner, crie o .env com as variáveis de configuração e use endereços do MongoDB e da acta-pg-api acessíveis a partir dele: localhost dentro do contêiner se refere ao próprio contêiner. O mapeamento 8081:8081 considera PORT=8081; ajuste-o caso configure outra porta.

📚 Documentação e autenticação

• Swagger UI: http://localhost:8081/swagger-ui/index.html
• OpenAPI: http://localhost:8081/v3/api-docs
• Público: GET /api/v1/health, Swagger UI e OpenAPI.
• Demais rotas: Authorization: Bearer <FIREBASE_ID_TOKEN>.

Após o login Firebase, envie o Firebase ID Token no cabeçalho Authorization. A API repassa esse token para GET /api/v1/me da acta-pg-api e usa o contexto retornado para autenticar a requisição.

Custom token, refresh token e senha não são Firebase ID Tokens e não devem ser usados no cabeçalho Authorization.

🔌 Endpoints principais

Todas as rotas abaixo exigem Firebase ID Token, exceto GET /api/v1/health.

Domínio	Rotas
Formulários	GET/POST /api/v1/ciclos/{idCiclo}/formularios, GET/PATCH/DELETE /api/v1/formularios/{idFormulario}
Respostas de formulário	GET/POST /api/v1/formularios/{idFormulario}/respostas, GET/PATCH/DELETE /api/v1/respostas-formulario/{idRespostaFormulario}
Ishikawa	GET/POST /api/v1/ciclos/{idCiclo}/ishikawas, GET/PATCH/DELETE /api/v1/ishikawas/{idIshikawa}
5 Porquês	GET/POST /api/v1/ishikawas/{idIshikawa}/cinco-porques, GET/PATCH/DELETE /api/v1/cinco-porques/{idCincoPorques}
Lições aprendidas	GET/POST /api/v1/ciclos/{idCiclo}/licoes-aprendidas, GET/PATCH/DELETE /api/v1/licoes-aprendidas/{idLicaoAprendida}

Cada usuário autenticado pode enviar uma única resposta por formulário. O formulário precisa estar publicado (ATIVO). Se idsUsuariosDestinatarios estiver preenchido, somente usuários listados podem responder; uma lista vazia permite resposta a todos os usuários da empresa. Na criação do formulário, essa lista é obrigatória. O usuário responsável é sempre obtido da autenticação e o corpo contém somente as respostas às perguntas. Uma tentativa duplicada retorna HTTP 409.

O Swagger contém métodos, parâmetros, enumerações, esquemas e todas as rotas derivadas dos controllers.

💻 Exemplos

curl http://localhost:8081/api/v1/health

curl -X POST http://localhost:8081/api/v1/ciclos/1/formularios \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Verificação do plano de ação",
    "descricao": "Formulário para acompanhar execução do ciclo.",
    "tipo": "CHECKLIST",
    "perguntas": [
      {
        "titulo": "O plano foi executado?",
        "tipo": "SIM_NAO",
        "obrigatoria": true,
        "opcoes": []
      }
    ],
    "idIshikawa": null,
    "idsUsuariosDestinatarios": []
  }'

Resposta de saúde, com dados fictícios:

{
  "status": "UP",
  "banco": "UP",
  "mensagem": "O CATO verificou: a API e o banco estão funcionando!",
  "verificadoEm": "2026-09-17T10:30:00-03:00"
}

⚠️ Erros

O formato confirmado é:

{
  "mensagens": ["campo: mensagem de validação"],
  "httpStatus": 400,
  "timestamp": "2026-09-17T10:35:00"
}

Código	Uso
400	Requisição, parâmetros ou validação inválidos
401 / 403	Token inválido/ausente ou acesso negado
404 / 405	Recurso ou método inexistente
409	Resposta duplicada ou conflito de dados
415	Tipo de conteúdo não suportado
502	Falha na integração com a API PostgreSQL ou o ViaCEP
500 / 503	Erro interno ou health check/autenticação delegada indisponível

🏗️ Arquitetura

• controller/: rotas HTTP e DTOs.
• service/: regras, validações e autenticação delegada; service/base/BaseService.java concentra CRUD comum.
• repository/: acesso MongoDB.
• document/: documentos, embeddeds e enums.
• dto/ e dto/mapper/: contratos e mapeamento MapStruct.
• common/: segurança, validação, Strategy de respostas, patch, clients de integração e erros.

A API é stateless. common/config/security/SecurityConfig.java registra ActaPgApiAuthFilter, enquanto PgApiClient consulta a acta-pg-api para validar o token recebido e obter o usuário autenticado. AuthService e @PreAuthorize nos serviços aplicam a exigência de autenticação nas operações protegidas. RespostaFormularioValidator aplica Strategy para selecionar a validação correta conforme o tipo de resposta.

📁 Estrutura

src/main/java/br/com/acta/
├── common/       # segurança, erros e configurações
├── controller/   # endpoints
├── document/     # documentos e enums
├── dto/          # contratos e mapeadores
├── repository/   # dados
└── service/      # domínio

🤝 Links e autoria

• Repositório · Licença MIT · acta.institutojef@gmail.com
• Contribuições: use issues e pull requests; há um PULL_REQUEST_TEMPLATE.md.
• Autoria: Equipe ACTA.