Aí 'Se Cream

Sistema web monolítico para gerenciamento de produção e distribuição de sorvetes de uma fábrica central para as lojas da rede.

A interface principal é server-side (Spring MVC + Thymeleaf), com autenticação JWT (cookie HTTP-only e POST /auth/login em JSON). O restante dos fluxos ocorre em páginas HTML autenticadas.

---

Descrição do Projeto

Uma rede de sorveterias possui uma fábrica central responsável pela produção dos sabores. Após a produção, os lotes precisam ser distribuídos entre as lojas da rede. O sistema permite registrar lotes de produção, distribuir quantidades para lojas cadastradas e manter rastreabilidade de todas as movimentações.

---

Escopo do Sistema

O sistema cobre o ciclo de produção → distribuição → controle de estoque das lojas por baixa manual.

O sistema não gerencia vendas, clientes, preços ou pagamentos. O controle de estoque das lojas é feito por baixa manual: o operador registra as quantidades consumidas pela loja, e o sistema calcula o saldo atual com base no total recebido via distribuição menos as baixas informadas.

---

Domínio do Problema

Atualmente a rede não possui controle estruturado para:

• Registrar as quantidades produzidas por lote e sabor
• Controlar a quantidade disponível em cada lote após distribuições parciais
• Registrar e auditar as distribuições realizadas
• Garantir que não sejam distribuídas quantidades superiores às disponíveis
• Acompanhar o estoque atual de cada loja
• Diferenciar permissões entre administradores e operadores de produção

---

Requisitos Funcionais

Legenda de status na implementação atual:

Status	Significado
✅	Atendido no código
⚠️	Atendido em parte
❌	Ainda não implementado

Sabores

ID	Descrição	Status
RF-01	Cadastrar sabores com nome, descrição e status ativo/inativo	✅
RF-02	Listar, editar e inativar sabores cadastrados	✅

Lotes de Produção

ID	Descrição	Status
RF-03	Registrar lote de produção informando sabor, quantidade e data	✅
RF-04	Exibir quantidade disponível de cada lote em tempo real	✅
RF-05	Listar lotes com filtros por sabor, status e período	✅

Lojas

ID	Descrição	Status
RF-06	Cadastrar lojas com nome, endereço e status ativo	✅ Endereço estruturado (CEP, UF, cidade, logradouro, número, complemento)
RF-07	Listar e editar lojas cadastradas	✅ Inativação incluída

Distribuição

ID	Descrição	Status
RF-08	Registrar distribuição associando lote, loja e quantidade	✅ ADMIN e OPERADOR
RF-09	Impedir distribuição quando a quantidade exceder o saldo do lote	✅
RF-10	Listar histórico de distribuições com filtros por loja, lote e período	✅
RF-11	Cancelar distribuição e estornar saldo ao lote de origem	✅ Apenas ADMIN

Estoque das Lojas

ID	Descrição	Status
RF-15	Registrar baixa manual de estoque informando loja, lote e quantidade consumida	✅
RF-16	Exibir saldo atual da loja por sabor (total recebido − total de baixas)	✅ Tela Estoque atual (/estoque) e fluxo de baixa
RF-17	Listar histórico de baixas por loja e período	✅

Pesquisa nas listagens

ID	Descrição	Status
RF-18	Campo de pesquisa em Sabores, Lojas, Lotes, Distribuições, Baixas e Operadores, filtrando por qualquer coluna visível da tabela em tempo real	✅ Fragmento fragments/table-search.html

Controle de Acesso

ID	Descrição	Status
RF-12	Autenticar usuários com e-mail e senha, retornando token JWT	✅
RF-13	Perfil ADMIN: acesso total ao sistema	✅
RF-14	Perfil OPERADOR: visualizar todos os módulos (exceto Operadores); criar distribuições e baixas	✅

---

Requisitos Não Funcionais

ID	Descrição	Categoria	Status
RNF-03	Senhas armazenadas com hash BCrypt (fator mínimo 10)	Segurança	✅
RNF-04	Tokens JWT com expiração configurável (padrão 8h)	Segurança	✅ jwt.expiration-ms
RNF-05	Endpoints protegidos por autorização baseada em roles (RBAC)	Segurança	✅
RNF-06	Operações de distribuição e baixa atômicas (transação única no banco)	Confiabilidade	✅ @Transactional nos services
RNF-07	Erros de validação com mensagens descritivas no corpo da resposta	Usabilidade	✅
RNF-08	Código organizado em camadas: Controller → Service → Repository	Manutenibilidade	✅
RNF-09	Migrações de banco gerenciadas por Flyway	Manutenibilidade	✅

---

Implementação atual (resumo)

Módulo	Rota	ADMIN	OPERADOR
Estoque atual	/, /estoque	Visualizar; atalho para novo lote	Visualizar
Sabores	/sabores	CRUD e inativar	Visualizar
Lotes	/lotes	Criar e listar	Visualizar
Lojas	/lojas	CRUD e inativar	Visualizar
Distribuições	/distribuicoes	Criar, listar e cancelar	Criar e listar
Baixas	/baixas	Criar e listar	Criar e listar
Operadores	/usuarios	CRUD	Sem acesso
Login	/login, /auth/login	JWT em cookie	JWT em cookie

Todas as telas de listagem (exceto Estoque atual) possuem campo Pesquisar, com filtro instantâneo por qualquer coluna da tabela. Baixas mantém filtro adicional por loja via query string (?lojaId=).

Usuário seed (dev): admin@aisecream.com / admin123

---

Tecnologias

Java 21

Versão LTS. Runtime e linguagem do projeto.

Spring Boot 4.0.3

Framework principal: servidor Tomcat embutido, Spring Data JPA, Spring Security, Bean Validation e Thymeleaf para a interface web.

MariaDB

Banco relacional (aisecream), transações ACID, compatível com o ecossistema MySQL/MariaDB.

Spring Data JPA (Hibernate)

Persistência via JpaRepository, @Transactional nas operações de escrita (distribuição, baixa, etc.).

Spring Security + JWT

Autenticação com JWT (jjwt), filtro JwtAuthFilter, roles ADMIN e OPERADOR, senhas com BCrypt.

Flyway

Versionamento do schema em src/main/resources/db/migration (V1 a V4).

Maven Wrapper (mvnw)

Build e execução sem instalar Maven globalmente: .\mvnw.cmd (Windows) ou ./mvnw (Linux/macOS).

Bean Validation (Jakarta Validation)

Validação em entidades, DTOs e formulários com @Valid.

---

Arquitetura

Monolito em camadas:

Browser (Thymeleaf + login AJAX)
    ↓
Controller (@Controller / @RestController)
    ↓
Service (regras de negócio + @Transactional)
    ↓
Repository (Spring Data JPA)
    ↓
MariaDB (Flyway)

A segurança intercepta requisições via JwtAuthFilter e regras em SecurityConfig:

Rota / ação	ADMIN	OPERADOR
/usuarios/**	✅	❌
/lojas/novo, /editar/**, /inativar/**	✅	❌
/lotes/novo	✅	❌
/sabores/novo, /editar/**, /inativar/**	✅	❌
/distribuicoes/cancelar/**	✅	❌
/distribuicoes/novo (GET/POST)	✅	✅
/baixas/**	✅	✅
Demais rotas autenticadas (listagens, estoque)	✅	✅

Diagramas C4 em src/architecture/ (c4-nivel2-containers.puml, c4-nivel3-components.puml).

---

Banco de dados (Flyway)

Versão	Conteúdo
V1	Tabelas base do domínio
V2	Usuário administrador inicial
V3	Registro histórico de saldo do CD em distribuicao
V4	Endereço estruturado em loja

spring.jpa.hibernate.ddl-auto=validate — alterações de schema apenas via Flyway.

---

Como rodar o projeto

Pré-requisitos

• Java 21
• MariaDB em execução (ex.: localhost:3306)
• IntelliJ IDEA ou outra IDE (opcional)

Passos

1. Clone o repositório

2. Configure o banco em src/main/resources/application.properties:

   spring.datasource.url=jdbc:mariadb://localhost:3306/aisecream
   spring.datasource.username=root
   spring.datasource.password=

3. Baixe dependências (se necessário):

   .\mvnw.cmd dependency:resolve -U

4. Execute a aplicação:

   .\mvnw.cmd spring-boot:run

5. Acesse http://localhost:8080 (redireciona para o estoque atual após login).

Flyway

Se uma migração falhar no histórico:

.\mvnw.cmd flyway:repair

Porta em uso

Se Port 8080 was already in use, encerre o processo anterior ou use server.port=8081 em application.properties.

---

Estrutura do código

src/main/java/com/aisecream/
├── config/          # SecurityConfig
├── controller/      # MVC + AuthController
├── dto/
├── exception/       # ApiExceptionHandler (REST)
├── model/
├── repository/
├── security/
└── service/

src/main/resources/
├── application.properties
├── db/migration/
└── templates/
    ├── fragments/   # nav, table-search
    ├── estoque/
    ├── sabor/
    ├── lote/
    ├── loja/
    ├── distribuicao/
    ├── baixa/
    └── usuario/

Documentação funcional complementar: relatorio.md. Diagramas C4: src/architecture/.

Testes automatizados: AisecreanApplicationTests (carga de contexto).