ViconSaga Java Backend

Documentação Técnica Completa

Versão: 1.0.0
Organização: Fiocruz / Fiotec
Repositório: github.com/drcalifornia/viconsaga_fiotec_java

---

Sumário

1. Visão Geral do Projeto
2. Arquitetura e Estrutura do Projeto
3. Configuração e Ambiente
4. Como Executar a Aplicação
5. Segurança e Autorização
6. Endpoints da API REST
7. Modelos de Dados
8. Serviços e Lógica de Negócio
9. Infraestrutura e DevOps
10. Testes e Cobertura
11. Sistema de Upload de Arquivos
12. Convenções e Padrões de Código
13. Apêndice

---

1. Visão Geral do Projeto

1.1 Descrição

O ViconSaga Java é um backend REST desenvolvido com Spring Boot para o sistema de gerenciamento de projetos, formulários e coleta de dados georreferenciados da Fiocruz. O sistema é a implementação Java do projeto ViconSaga (Vigilância Comunitária com Saúde e Geoprocessamento Ativo), integrado à infraestrutura da Fiotec.

1.2 Principais Funcionalidades

• Autenticação e autorização via Keycloak (OAuth2/JWT)
• Gerenciamento de projetos com controle de acesso por workgroups
• Criação e gestão de formulários dinâmicos com múltiplos tipos de campos
• Registro de dados georreferenciados (pontos, linhas, áreas)
• Upload e download de arquivos para registros e projetos
• Gestão de usuários integrada ao SSO Keycloak
• Documentação automática via Swagger/OpenAPI 3
• Migrações de banco de dados com Flyway
• Cobertura de testes unitários com JaCoCo (mínimo 80%)

1.3 Stack Tecnológica

Tecnologia	Versão	Finalidade
Java	21	Linguagem principal
Spring Boot	4.0.2	Framework web e IoC
Spring Security + OAuth2	4.0.x	Autenticação e autorização
Spring Data JPA	4.0.x	Persistência de dados
Keycloak	22.0.0	Identity Provider / SSO
MySQL	8.0	Banco de dados relacional
Flyway	10.x	Migração de banco de dados
MapStruct	1.6.3	Mapeamento de DTOs
Lombok	1.18.x	Redução de boilerplate
SpringDoc OpenAPI	2.8.4	Documentação Swagger
JaCoCo	0.8.14	Cobertura de testes
Docker / Docker Compose	—	Containerização
MailHog	latest	Mock SMTP para desenvolvimento

---

2. Arquitetura e Estrutura do Projeto

2.1 Visão Arquitetural

O sistema segue uma arquitetura em camadas baseada nos padrões do Spring Boot, com separação clara de responsabilidades entre Controllers, Services, Repositories e Models. O projeto está dividido em três domínios principais:

Domínio	Pacote	Responsabilidade
Autenticação	authentication	Login, refresh token, sincronização com Keycloak
Projeto	project	Projetos, formulários, registros, arquivos
Usuário	user	CRUD de usuários, roles Keycloak, recuperação de senha
Comum	common	Configurações, exceções, serviços compartilhados

2.2 Estrutura de Pacotes

br.fiocruz.viconsaga
├── ViconSagaApplication.java
├── authentication/
│   ├── config/         # KeycloakConfig
│   ├── controller/     # LoginController, AuthController
│   ├── dto/            # LoginRequestDTO, LoginResponseDTO, RefreshTokenDTO
│   └── service/        # LoginService
├── common/
│   ├── config/         # CorsConfig, JacksonConfig, OpenApiConfig, SecurityConfig
│   ├── constant/       # HttpStatusCode
│   ├── dto/            # ApiResponse, UploadProgressDTO
│   ├── exception/      # GlobalExceptionHandler, exceções customizadas
│   └── service/        # FileStorageService, SecurityService, TokenService,
│                       # UploadProgressTrackerService
├── project/
│   ├── adapter/        # Implementações dos repositórios
│   ├── controller/     # 7 controllers REST
│   ├── dto/            # ~25 DTOs
│   ├── mapper/         # MapStruct mappers
│   ├── model/          # 18 entidades JPA
│   ├── repository/     # Spring Data interfaces
│   ├── service/        # Lógica de negócio
│   │   ├── fieldhandler/    # Handlers por tipo de campo
│   │   └── validation/      # Validadores de registros
│   └── specification/  # JPA Specifications para filtros
└── user/
    ├── adapter/        # UserRepositoryAdapter
    ├── controller/     # UserController
    ├── dto/            # UserDTO, UserSummaryDTO, AssignRolesDTO
    ├── mapper/         # UserMapper
    ├── model/          # User
    ├── repository/     # UserRepository
    └── service/        # UserService, KeycloakUserService, PasswordRecoveryService

2.3 Padrão de Resposta da API

Todas as respostas da API seguem o padrão envelope ApiResponse<T>:

{
  "success": true,
  "data": { ... },
  "message": "Operação realizada com sucesso"
}

2.4 Design Pattern: Field Handler

Para o processamento de campos de formulário com múltiplos tipos de dados, foi implementado o padrão Strategy com a interface FieldValueHandler e um Registry. Cada tipo de campo (Text, Numeric, Date, Time, TimeSerie, Unichoice, Multichoice) possui seu próprio Handler e Validator registrados no FieldValueHandlerRegistry.

---

3. Configuração e Ambiente

3.1 Pré-requisitos

Requisito	Versão Mínima	Link
Java JDK	21	oracle.com/java/technologies/downloads
Maven	3.8+	maven.apache.org
Docker	20+	docs.docker.com/get-docker
Docker Compose	2.0+	docs.docker.com/compose/install

3.2 Variáveis de Ambiente

O projeto usa arquivos .env para centralizar configurações por ambiente:

Variável	Padrão (local-dev)	Descrição
DB_HOST	localhost	Host do banco de dados
DB_PORT	3309	Porta do MySQL
DB_NAME	viconsaga	Nome do banco de dados
DB_USER	viconsaga	Usuário do banco
DB_PASSWORD	secret	Senha do banco
KEYCLOAK_URL	http://localhost:8088	URL do Keycloak
KEYCLOAK_REALM	fiocruz	Realm do Keycloak
KEYCLOAK_CLIENT_ID	viconsaga-backend	Client ID
KEYCLOAK_CLIENT_SECRET	***	Client Secret
KEYCLOAK_ADMIN_USERNAME	admin	Admin do Keycloak
KEYCLOAK_ADMIN_PASSWORD	admin	Senha do admin Keycloak
ALLOWED_ORIGINS	http://localhost:4200	CORS origins permitidas
FLYWAY_ENABLED	true	Habilitar migrações automáticas
LOGGING_LEVEL	INFO	Nível de log
FILE_UPLOAD_DIR	uploads	Diretório de upload
IMAGE_VERSION	local-dev	Versão da imagem Docker
SPRINGDOC_SERVERS_URL	http://localhost:8889	URL base para o Swagger

3.3 Configuração por Ambiente

Para selecionar o ambiente, copie o arquivo correspondente:

# Desenvolvimento local
cp .env.local-dev .env

# Produção (saudeterritorial.com.br)
cp .env.saudeterritorial .env

---

4. Como Executar a Aplicação

4.1 Via Docker Compose (Recomendado)

Sobe todos os serviços (API, MySQL, Keycloak, MySQL do Keycloak, MailHog):

docker compose up -d

A aplicação estará disponível em:

Serviço	URL
API	http://localhost:8880
Swagger UI	http://localhost:8880/swagger-ui/index.html
Keycloak	http://localhost:8088 (admin / admin)
MailHog Web UI	http://localhost:8025
MySQL	localhost:3309 (viconsaga / secret)

4.2 Via IDE (IntelliJ / VS Code)

Com o Docker Compose rodando apenas os serviços de infraestrutura:

# Suba apenas os serviços de suporte
docker compose up -d viconsaga-mysql keycloak keycloak-mysql mailhog

# Execute a aplicação Spring Boot
mvn spring-boot:run

Neste caso, o Swagger estará em: http://localhost:8889/swagger-ui/index.html

4.3 Configuração Inicial do Keycloak

Após subir o Keycloak, é necessário criar um usuário no realm fiocruz:

1. Acesse http://localhost:8088 e faça login com admin / admin
2. Selecione o realm fiocruz
3. Crie um usuário com email e senha (marque Temporary: off em Credentials)
4. Atribua as Client Roles do client viconsaga-backend conforme necessário

Roles disponíveis: SystemAdministrator, ProjectAdministrator, Manager, Editor, Visitor

4.4 Obtendo um Token de Acesso

curl -X POST http://localhost:8088/realms/fiocruz/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=viconsaga-backend" \
  -d "client_secret=SEU_SECRET" \
  -d "username=seu@email.com" \
  -d "password=sua_senha" \
  -d "grant_type=password"

---

5. Segurança e Autorização

5.1 Modelo de Autenticação

A aplicação utiliza OAuth2 Resource Server com tokens JWT emitidos pelo Keycloak. Cada requisição autenticada deve incluir o header:

Authorization: Bearer <token_jwt>

5.2 Perfis de Acesso (Roles)

Role	Descrição	Nível de Acesso
SystemAdministrator	Administrador do sistema	Acesso total a todos os recursos
ProjectAdministrator	Administrador de projetos	Gerencia projetos e usuários do projeto
Manager	Gerente	Acesso de gerenciamento parcial
Editor	Editor	Pode criar/editar registros e formulários
Visitor	Visitante	Acesso somente leitura

5.3 Controle de Permissão por Endpoint

Módulo	Roles Autorizadas	Observação
POST /auth/login	Público	Autenticação inicial
POST /auth/refresh-token	Público	Renovação de token
GET /auth/all-roles	SA, PA	Lista roles disponíveis
GET /projects/	SA	Listagem geral de projetos
GET /projects/{id}	SA, PA	Valida permissão de workgroup
POST /projects	SA, PA	Cria projeto
PUT /projects/{id}	SA, PA	Atualiza projeto
DELETE /projects/{id}	SA, PA	Soft delete do projeto
GET/POST/PUT/DELETE /forms	SA, PA, ED	Gestão de formulários
GET/POST/PUT/DELETE /forms/{id}/fields	SA, PA	Gestão de campos
GET/POST/DELETE /records	SA, PA, ED	Registros de formulário
GET /users/	SA	Lista todos usuários
GET/POST /users/*	SA, PA	Gestão de usuários

Legenda: SA = SystemAdministrator | PA = ProjectAdministrator | ED = Editor

5.4 Configuração de CORS

As origens permitidas são configuráveis via variável ALLOWED_ORIGINS. No ambiente local, o padrão é:

http://localhost:4200, http://localhost:4201

---

6. Endpoints da API REST

6.1 Autenticação — /auth

Método	Endpoint	Descrição	Auth
POST	/auth/login	Autenticar usuário via Keycloak e sincronizar com DB local	Público
POST	/auth/refresh-token	Renovar token de acesso com refresh token	Público
GET	/auth/all-roles	Listar todos os roles disponíveis no sistema	SA, PA

6.2 Projetos — /projects

Método	Endpoint	Descrição	Auth
GET	/projects/	Listar projetos com paginação e filtros	SA
GET	/projects/{idProject}	Buscar projeto por ID	SA, PA
POST	/projects	Criar novo projeto	SA, PA
PUT	/projects/{idProject}	Atualizar projeto existente	SA, PA
DELETE	/projects/{idProject}	Soft delete de projeto	SA, PA

Parâmetros de filtro aceitos no GET /projects/:

Parâmetro	Tipo	Descrição
page	Integer	Página (padrão: 0)
pageSize	Integer	Itens por página (padrão: 10)
sortBy	String	Campo de ordenação
sortDirection	String	ASC ou DESC (padrão: ASC)
strName	String	Filtro por nome do projeto
strAlias	String	Filtro por alias
txtDescription	String	Filtro por descrição
idUserCreator	Integer	Filtro por criador
idCountry	Integer	Filtro por país
blnActive	Boolean	Filtro por status ativo
userIds	Integer[]	Filtro por IDs de usuários associados

6.3 Formulários — /forms

Método	Endpoint	Descrição	Auth
GET	/forms	Listar formulários com paginação e filtros	SA, PA, ED
GET	/forms/{idForm}	Buscar formulário por ID	SA, PA, ED
POST	/forms	Criar novo formulário	SA, PA, ED
PUT	/forms/{idForm}	Atualizar formulário	SA, PA, ED
DELETE	/forms/{idForm}	Remover formulário	SA, PA, ED

6.4 Campos de Formulário — /forms/{id}/fields

Método	Endpoint	Descrição	Auth
GET	/forms/{idForm}/fields	Listar campos do formulário	SA, PA
POST	/forms/{idForm}/fields	Adicionar campo ao formulário	SA, PA
PUT	/forms/fields/{idFormField}	Atualizar campo	SA, PA
DELETE	/forms/fields/{idFormField}	Remover campo	SA, PA
GET	/forms/fields/{idFormField}/alternatives	Listar alternativas de um campo	SA, PA
POST	/forms/fields/{idFormField}/alternatives	Criar alternativa	SA, PA, ED
PUT	/forms/fields/alternatives/{id}	Atualizar alternativa	SA, PA
DELETE	/forms/fields/alternatives/{id}	Remover alternativa	SA, PA

6.5 Registros — /records

Método	Endpoint	Descrição	Auth
GET	/records	Listar registros com paginação e filtros	SA, PA, ED
GET	/records/{idFormRecord}	Buscar registro por ID (UUID)	SA, PA, ED
POST	/records/save	Salvar registro com todos os valores de campos	SA, PA, ED
DELETE	/records/{idFormRecord}	Soft delete de registro	SA, PA, ED

Parâmetros de filtro do GET /records: idProject, idUser, idForm, idDevice, page, size

6.6 Arquivos de Registros — /records/{id}/files

Método	Endpoint	Descrição	Auth
POST	/records/{idFormRecord}/files/upload	Upload de arquivo (max 10MB)	SA, PA, ED
POST	/records/{idFormRecord}/files/url	Anexar URL de arquivo externo	SA, PA, ED
GET	/records/{idFormRecord}/files	Listar arquivos do registro	Todos
GET	/records/{idFormRecord}/files/{id}/download	Download de arquivo	Todos
PATCH	/records/{idFormRecord}/files/{id}/description	Atualizar descrição	SA, PA, ED
DELETE	/records/{idFormRecord}/files/{id}	Remover arquivo	SA, PA, ED
GET	/records/files/upload-progress/{uploadId}	Verificar progresso do upload	Todos

6.7 Arquivos de Projetos — /projects/{id}/files

Método	Endpoint	Descrição	Auth
POST	/projects/{idProject}/files/upload	Upload de arquivo para projeto (max 10MB)	SA, PA
GET	/projects/{idProject}/files	Listar arquivos do projeto	SA, PA
GET	/projects/{idProject}/files/{id}/download	Download de arquivo do projeto	SA, PA, ED
DELETE	/projects/{idProject}/files/{id}	Remover arquivo do projeto	SA, PA
PATCH	/projects/{idProject}/files/{id}/description	Atualizar descrição	SA, PA

6.8 Usuários de Projetos — /api/project-users

Método	Endpoint	Descrição	Auth
GET	/api/project-users/project/{idProject}	Listar usuários do projeto (paginado)	SA, PA
POST	/api/project-users/project/{idProject}/add/{idUser}	Adicionar usuário ao projeto	SA, PA
DELETE	/api/project-users/project/{idProject}/remove/{idUser}	Remover usuário do projeto	SA, PA
GET	/api/project-users/project/{idProject}/not-in-project	Listar usuários NÃO no projeto	SA, PA

6.9 Usuários — /users

Método	Endpoint	Descrição	Auth
GET	/users/	Listar todos os usuários ativos	SA
GET	/users/{idUser}	Buscar usuário por ID	SA, PA
GET	/users/email/{email}	Buscar usuário por email	SA, PA
GET	/users/projects/	Projetos do usuário autenticado (paginado)	SA, PA, ED
GET	/users/{idUser}/roles	Roles do usuário no SSO	SA, PA
POST	/users/{idUser}/assign-roles	Atribuir roles ao usuário	SA, PA
POST	/users/import-from-sso	Importar usuário do Keycloak por email	SA, PA
POST	/users/recover-password	Enviar email de recuperação de senha	Público
DELETE	/users/{idUser}	Soft delete de usuário	SA
PATCH	/users/{idUser}/active	Ativar/desativar usuário	SA

---

7. Modelos de Dados

7.1 Entidades Principais

Entidade	Tabela	Descrição
Project	project	Projeto de coleta de dados georreferenciados
User	user	Usuário do sistema, vinculado ao Keycloak
ProjectWorkgroup	projectworkgroup	Grupo de trabalho de um projeto
UserProjectWorkgroup	userprojectworkgroup	Associação usuário-workgroup-projeto
Form	form	Formulário de coleta dentro de um projeto
FormField	formfield	Campo de um formulário (texto, numérico, etc.)
FormFieldType	formfieldtype	Tipo de campo (7 tipos suportados)
FormFieldAlternative	formfieldalternative	Alternativas para campos de escolha
FormRecord	formrecord	Registro/coleta de dados (UUID como PK)
FormRecordField	formrecordfield	Valor de um campo em um registro
FormRecordFieldText	formrecordfieldtext	Valor textual de um campo
FormRecordFieldNumeric	formrecordfieldnumeric	Valor numérico de um campo
FormRecordFieldDate	formrecordfielddate	Valor de data de um campo
FormRecordFieldTime	formrecordfieldtime	Valor de hora de um campo
FormRecordFieldTimeSerie	formrecordfieldtimeserie	Série temporal de um campo
FormRecordFieldAlternative	formrecordfieldalternative	Escolha selecionada em um campo
FormRecordVertex	formrecordvertex	Vértices geográficos de um registro
FormRecordFile	formrecordfile	Arquivo anexado a um registro
ProjectFile	projectfile	Arquivo anexado a um projeto
ShapeType	shapetype	Tipo de geometria (Point, Line, Area)

7.2 Tipos de Campo de Formulário

ID	Tipo	Tabela de Valor	Descrição
1	Text	formrecordfieldtext	Campo de texto livre
2	Numeric	formrecordfieldnumeric	Campo numérico (double)
3	Unichoice	formrecordfieldalternative	Escolha única entre alternativas
4	Multichoice	formrecordfieldalternative	Múltipla escolha entre alternativas
5	Date	formrecordfielddate	Campo de data
6	Time	formrecordfieldtime	Campo de hora
7	TimeSerie	formrecordfieldtimeserie	Série temporal com data-hora e valor

7.3 Migrações Flyway

Versão	Arquivo	Descrição
V1	V1__base_structure.sql	Estrutura base completa com dados iniciais
V2	V2__inserts.sql	Dados iniciais adicionais
V3	V3__remove_idProject_from_user.sql	Remove relação direta projeto-usuário
V4	V4__insert_form_samples_inserts.sql	Dados de exemplo de formulários
V5	V5__add_blnRequired_to_formfield.sql	Adiciona campo obrigatório ao FormField
V6	V6__add_blnCanAddChoice_to_formfield.sql	Permite adicionar escolhas dinamicamente
V7	V7__add_externalUrl_to_project.sql	URL externa para projetos
V8	V8__add_lngFileSize_to_projectfile.sql	Tamanho de arquivo em ProjectFile
V9	V9__add_projectfile_columns_if_missing.sql	Colunas opcionais em ProjectFile
V10	V10__add_dtLastUpdate_to_project.sql	Data de última atualização do projeto
V11	V11__create_job_queue.sql	Fila de jobs assíncronos
V12	V12__add_retry_columns_to_jobqueue.sql	Colunas de retry na fila
V13	V13__add_fail_reason_to_jobqueue.sql	Razão de falha na fila
V14	V14__add_dtDeleted_to_project.sql	Soft delete de projetos

---

8. Serviços e Lógica de Negócio

8.1 Serviços do Domínio Project

Serviço	Responsabilidade Principal
ProjectService	CRUD de projetos, paginação, filtros, soft delete, projetos do usuário
FormService	CRUD de formulários, listagem paginada por projeto
FormFieldService	Gerenciamento de campos e alternativas de formulários
FormRecordService	Salvar registros com todos os tipos de campo, paginação, soft delete
FormRecordFileService	Upload/download/delete de arquivos vinculados a registros
ProjectFileService	Upload/download/delete de arquivos vinculados a projetos

8.2 Serviços do Domínio User

Serviço	Responsabilidade Principal
UserService	CRUD de usuários, importação do Keycloak, atribuição de roles, soft delete
KeycloakUserService	Integração com API Admin do Keycloak para gerenciar usuários e roles
PasswordRecoveryService	Dispara fluxo de recuperação de senha via Keycloak

8.3 Serviços Comuns

Serviço	Responsabilidade Principal
LoginService	Autenticação via Keycloak, sincronização do usuário com banco local
SecurityService	Extração de informações do token JWT, validação de permissões
TokenService	Extração de claims do token JWT (userId, roles)
FileStorageService	Armazenamento físico de arquivos no sistema de arquivos
UploadProgressTrackerService	Rastreamento em memória do progresso de uploads

8.4 Sistema de Validação de Registros

Antes de salvar um FormRecord, o FormRecordRequestValidator executa as seguintes validações:

• Verifica se os campos obrigatórios estão preenchidos
• Delega a validação do valor para o FieldValueValidator correspondente ao tipo
• Valida URLs externas anexadas via FormRecordFileUrlValidator
• Lança FormRecordRequestValidationException com detalhes dos erros encontrados

---

9. Infraestrutura e DevOps

9.1 Serviços Docker Compose

Serviço	Imagem	Porta	Descrição
viconsaga-api	Build local	8880:8889	Backend Spring Boot
viconsaga-mysql	mysql:8.0	3309:3306	Banco de dados da aplicação
keycloak	Build local	8088:8080	Identity Provider
keycloak-mysql	mysql:8.0	3310:3306	Banco de dados do Keycloak
mailhog	mailhog/mailhog	1025/8025	Mock SMTP + Web UI

9.2 Dockerfile da Aplicação

A imagem é baseada em eclipse-temurin:21 e realiza o build Maven durante a construção:

FROM eclipse-temurin:21
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn clean package -DskipTests
EXPOSE 8889
CMD ["java", "-jar", "target/vigiante.jar"]

9.3 Keycloak Customizado

O Keycloak utiliza um Dockerfile customizado que inclui:

• Importação automática do realm fiocruz (fiocruz-realm-export.json)
• Tema personalizado vigiante para emails e tela de boas-vindas
• Templates de email customizados em FreeMarker (.ftl)

9.4 Volumes Persistentes

• java_db_data — Dados do MySQL da aplicação
• java_keycloak_data — Dados do MySQL do Keycloak
• ./uploads — Arquivos enviados pelos usuários (mapeado no container)

---

10. Testes e Cobertura

10.1 Estrutura de Testes

Módulo	Classes de Teste
authentication.controller	AuthControllerTest, LoginControllerTest
authentication.service	LoginServiceTest
common.service	FileStorageServiceTest, SecurityServiceTest, TokenServiceTest, UploadProgressTrackerServiceTest
project.controller	FormControllerTest, FormFieldControllerTest, FormRecordControllerTest, FormRecordFileControllerTest, ProjectControllerTest, ProjectFileControllerTest, ProjectUserControllerTest
project.service	FormFieldServiceTest, FormRecordFileServiceTest, FormRecordServiceTest, FormServiceTest, ProjectFileServiceTest, ProjectServiceTest
project.service.fieldhandler	DateFieldHandlerTest, MultichoiceFieldHandlerTest, NumericFieldHandlerTest, TextFieldHandlerTest, TimeFieldHandlerTest, TimeSerieFieldHandlerTest, UnichoiceFieldHandlerTest
project.service.validation	FormRecordFileUrlValidatorTest, FormRecordRequestValidatorTest
project.service.validation.fieldvalidators	8 validators testados
project.specification	FormRecordSpecificationTest, FormSpecificationTest, ProjectSpecificationTest
user.controller	UserControllerTest
user.service	KeycloakUserServiceTest, UserServiceTest

10.2 Executando os Testes

# Executar todos os testes
mvn clean test

# Executar com relatório de cobertura (perfil coverage)
mvn clean test -Pcoverage

O relatório HTML é gerado em:

target/site/jacoco/index.html

10.3 Configuração de Cobertura

Parâmetro	Valor
Cobertura mínima de linhas	80%
Cobertura mínima de branches	80%
Ferramenta	JaCoCo 0.8.14
Escopo	Por classe

Classes excluídas da verificação: exception/**, config/**, dto/**, adapter/**, model/**, mapper/**, constant/**, fieldhandler/**, specification/**, util/**, ViconSagaApplication

---

11. Sistema de Upload de Arquivos

11.1 Configuração de Arquivos

Configuração	Valor Padrão
Diretório de upload	uploads/
Tamanho máximo por arquivo	10MB
Tamanho máximo da requisição	10MB
Threshold para disco	2KB
Extensões permitidas	jpg, jpeg, png, gif, pdf, doc, docx, xls, xlsx, txt, csv, mp4, avi, mov

11.2 Fluxo de Upload

1. Cliente envia POST /records/{id}/files/upload com multipart/form-data
2. API cria um uploadId e retorna junto com a resposta
3. FileStorageService salva o arquivo com nome único (UUID) no diretório configurado
4. Cliente pode consultar o progresso via GET /records/files/upload-progress/{uploadId}
5. Registro do arquivo é salvo na tabela formrecordfile com nome original e tamanho

11.3 URLs Externas

Além do upload local, é possível anexar URLs externas a registros. URLs de certos domínios são bloqueadas por configuração (ex: youtube.com). A URL é armazenada no campo strFileOriginalName da tabela formrecordfile.

---

12. Convenções e Padrões de Código

12.1 Nomenclatura

Contexto	Convenção	Exemplo
Colunas de banco (booleanos)	Prefixo bln	blnActive, blnDeleted
Colunas de banco (strings)	Prefixo str	strName, strEmail
Colunas de banco (texto longo)	Prefixo txt	txtDescription
Colunas de banco (inteiros)	Prefixo int/lng	intOrder, lngFileSize
Colunas de banco (decimais)	Prefixo dbl	dblLatitude, dblLongitude
Colunas de banco (datas)	Prefixo dt	dtCreation, dtLastUpdate
PKs de entidades	id + NomeDaEntidade	idProject, idFormRecord
Classes de serviço	NomeDomínio + Service	ProjectService, LoginService
Classes de controller	NomeDomínio + Controller	ProjectController
DTOs	Finalidade + DTO	LoginRequestDTO, FormRecordDTO
Mappers	NomeDomínio + Mapper	ProjectMapper, FormFieldMapper

12.2 Tratamento de Erros

O GlobalExceptionHandler centraliza o tratamento de exceções e retorna respostas padronizadas:

Exceção	HTTP Status
AuthenticationException	401 Unauthorized
ResourceNotFoundException	404 Not Found
FileStorageException	400 Bad Request ou 404
FormRecordRequestValidationException	400 com detalhes de validação
Exception genérica	500 Internal Server Error

12.3 Soft Delete

Projetos e registros de formulário utilizam soft delete: ao invés de remover fisicamente, um campo de data de exclusão (dtDeleted) é preenchido. Consultas filtram automaticamente registros com dtDeleted != null.

12.4 Paginação

Todas as listagens que podem retornar muitos resultados utilizam paginação com parâmetros padronizados: page (0-indexado), pageSize/size, sortBy e sortDirection.

---

13. Apêndice

13.1 Links Úteis

Recurso	URL (ambiente local)
Swagger UI (Docker Compose)	http://localhost:8880/swagger-ui/index.html
Swagger UI (IDE)	http://localhost:8889/swagger-ui/index.html
OpenAPI JSON	http://localhost:8889/v3/api-docs
Keycloak Admin	http://localhost:8088
MailHog Web UI	http://localhost:8025
Relatório JaCoCo	target/site/jacoco/index.html (após rodar testes)

13.2 Variáveis de Build

Variável	Descrição
IMAGE_VERSION	Versão da imagem Docker (passada como ARG no Dockerfile)
JAVA_OPTS	Opções JVM (ex: -Xmx512m)

13.3 Comandos Úteis

# Subir todos os serviços
docker compose up -d

# Acompanhar logs da API
docker logs -f viconsaga-api

# Executar testes
mvn clean test

# Executar testes com cobertura
mvn clean test -Pcoverage

# Build sem testes
mvn clean package -DskipTests

# Verificar banco de dados
mysql -h localhost -P 3309 -u viconsaga -psecret viconsaga