Arquitetura

← Índice da documentação da API

Escopo: o que está comprovado no código dos dois projetos — frontend storage-app (Expo / React Native Web) e backend Storage_Wester (Spring Boot).

1. Visão geral

 ┌──────────────────────────────┐          HTTPS / JSON (JWT)          ┌───────────────────────────────┐
 │ Frontend  storage-app        │ ───────────────────────────────────► │ Backend  Storage_Wester       │
 │ Expo 54 + React Native 0.81  │ ◄─────────────────────────────────── │ Spring Boot 3.5 · Java 21     │
 │ (publicado como site estático │        STOMP / WebSocket (/ws)       │ Spring Security · JPA · Flyway│
 │  no Render)                  │ ◄─────────────────────────────────── │ springdoc (opcional)          │
 └──────────────────────────────┘                                      └──────────────┬────────────────┘
                                                                                      │ JDBC
 ┌──────────────────────────────┐   HTTP + cabeçalho X-Edge-Key        ┌──────────────▼────────────────┐
 │ Coletor industrial ("Edge")  │ ───────────────────────────────────► │ PostgreSQL                    │
 │ lê sinais das injetoras      │   /api/mes/edge/**                   │ (H2 apenas em dependência de  │
 └──────────────────────────────┘                                      │  teste/local)                 │
                                                                       └───────────────────────────────┘

Camada	Tecnologia (comprovada em pom.xml / package.json)
Frontend	Expo ^54, React 19.1, React Native 0.81, React Navigation (Drawer), React Native Paper, Axios, @stomp/stompjs, Three.js + @react-three/fiber (visão 3D), @dnd-kit (arrastar e soltar)
Backend	Spring Boot 3.5.0, Java 21, Spring Web, Spring Security (JWT com jjwt), Spring Data JPA, Bean Validation, Spring WebSocket (STOMP), Actuator, springdoc-openapi, Apache PDFBox 3.0.3
Banco	PostgreSQL (driver e dialeto PostgreSQLDialect), migrações Flyway em src/main/resources/db/migration
Implantação	Frontend: render.yaml (site estático, npm run build:web, reescreve /* para /index.html); backend: Dockerfile e Dockerfile.hardened, docker-compose.yml

2. Backend: camadas e módulos

O backend segue o padrão controller → service → repository → entidade, com DTOs de entrada/saída em dto/:

Pacote	Conteúdo
controller	21 controllers REST + exception/GlobalExceptionHandler
mes	módulo de produção (MES/PCP): MesController, MesEdgeController, MesService, MesRules, regras de acesso, leitura de PDF (MesOrderPdfParser, MesOrderPdfOcr)
service	24 classes de serviço e apoio com as regras de negócio
repository	repositórios JPA (alguns com consultas customizadas)
model	17 entidades JPA e 3 enums (MaterialType, TipoAcessoPerfil, TipoEstruturaArea)
config	segurança, JWT, CORS, limite de taxa, OpenAPI
realtime	WebSocket/STOMP, publicação de eventos após commit

2.1 Módulos funcionais da API

A API foi agrupada em 16 módulos (ver endpoints.md):

1. Acesso, usuários e perfis
2. Produtos
3. Categorias de produtos
4. Setores e tipos de material
5. Corredores, blocos e níveis (estrutura física)
6. Itens e transferências de estoque
7. Moldes
8. Materiais fixos e slots legados
9. Listas de materiais ("encerto")
10. Consultas de estoque e mapa
11. Histórico e auditoria
12. Movimentações operacionais
13. Alertas de estoque
14. Relatórios de estoque
15. PCP e produção (MES)
16. Integração industrial Edge

3. Modelo de dados e relacionamentos

Os campos de cada DTO estão em modelos.md. A relação entre as entidades persistidas é:

AreaEstoque (setor) ─1──N─ Fileira (corredor/estante) ─1──N─ Grade (bloco) ─1──N─ Nivel (gaiola/ordem/posição)
      │                                                                              │
      │ 1──N                                                                         ├─1──N─ ItemEstoque ─N──1─ Produto ─N──0..1─ CategoriaProduto
      ▼                                                                              │
 AreaMaterialTag (tipos de material aceitos no setor: MOLDE | PRODUTO | FERRAMENTA)   ├─1──N─ NivelMaterial (material alocado: materialType + materialId)
                                                                                     └─1──N─ SlotNivel ─1──N─ MoldeAlocado ─N──1─ Molde  (legado)
 AreaEstoque ─1──N─ TabelaEncerto ─1──N─ TabelaEncertoItem ─N──1─ Produto           (listas de materiais)

 HistoricoMovimentacao ── referência opcional a Usuario, Produto, ItemEstoque, Nivel (atual/origem/destino)
                          e ids avulsos (área, corredor, bloco, slot, molde, entidade)
 Usuario ──(texto `perfil` = `Perfil.codigo`, sem chave estrangeira)── Perfil

 Módulo MES (tabelas criadas em V10): máquina · ordem de serviço · execução · evento · ciclo · resultado de ciclo ·
 apontamento de qualidade · parada

Observações confirmadas no código:

• Dois tipos de setor (TipoEstruturaArea): DINAMICO (níveis podem ser criados, movidos e resequenciados) e FIXO (posições criadas na configuração e editadas pontualmente). O frontend mostra uma tela diferente para cada um (Warehouse2DView para dinâmico, WarehouseFixedView para fixo) e uma visão 3D para os dois.
• Rótulos configuráveis por setor: labelEstruturaPrimaria, labelEstruturaSecundaria, labelNivel e labelSlot — por padrão o frontend usa "Corredor", "Bloco" e "Ordem/Gaiola"; nos setores fixos podem aparecer "Estante", "Posição" etc.
• Controle de concorrência otimista (@Version) em Fileira, Grade, Nivel e ItemEstoque.
• Perfil do usuário não é chave estrangeira: o usuário guarda o código do perfil como texto; se o perfil for inativado ou apagado, o usuário fica sem permissões (ver autenticacao.md).
• Auditoria: o HistoricoMovimentacao é gravado na mesma transação da alteração de negócio (exigido por Propagation.MANDATORY em registrarEventoGenericoNaTransacaoAtual): se a auditoria falhar, a mudança é desfeita.
• Migrações Flyway: 19 arquivos V*__*.sql (V1–V16, V21–V23; não existem V17–V20 no repositório). ddl-auto é update no perfil padrão e validate no perfil prod.

4. Tempo real

WebSocketConfig publica STOMP em /ws (SockJS) e /ws-native, com corretor simples em /topic e prefixo de aplicação /app. EntityChangeListener publica um RealtimeEvent depois do commit para as entidades que alteram estoque, estrutura, histórico, cadastro etc. Tópicos: /topic/estoque, /topic/area/{areaId} e /topic/entidade/{entidade} (detalhes em integracoes.md). O frontend usa isso para atualizar listas e mapa sem recarregar a página.

5. Frontend: organização

Pasta (src/)	Função
navigation/	menu lateral (Drawer), rotas e deep links (linking.ts)
auth/	contexto de autenticação (AuthContext), proteção de rotas (RequireAuth), retorno pós-login
security/permissions.tsx	mapeia o perfil para telas e ações; mostra "Sem permissão" quando não liberado
screens/	telas: login/cadastro, Dashboard, Armazém, Setores, Produtos, Moldes, Perfis, Histórico, Usuários, PCP (mes/) e as telas desativadas Alertas, Movimentações, Relatórios
components/, components/warehouse2d/	componentes do armazém 2D, setor fixo, mapa V4, modais
twin/	"Wester Twin" — visão 3D do armazém
services/	clientes HTTP por módulo; services/http/ trata erros
realtime/, services/realtime/	assinatura dos tópicos STOMP
axios.ts, config/apiConfig.ts	cliente HTTP, anexo do token e URL da API

• URL da API: EXPO_PUBLIC_API_BASE_URL (ou VITE_API_BASE_URL); se ausente, http://localhost:8080/127.0.0.1 quando a página roda em localhost, senão a URL de produção definida em apiConfig.ts. Barras finais e um sufixo /api são normalizados.
• Sessão: token e dados do usuário ficam em AsyncStorage (no navegador, armazenamento local). Um 401 com token anexado limpa a sessão e leva ao Login.
• Temas: Light, Dark e Console (seletor no cabeçalho de toda tela).
• 3D: disponível apenas no navegador (WebGL); a opção não é oferecida em build nativo.

6. Pontos de extensão e restrições conhecidas

• A API tem aliases duplicados em português e inglês (/api/areas = /api/setores, /api/produtos = /api/products...). Eles contam como rotas, mas são a mesma operação (211 combinações método+rota para 145 operações).
• Alertas, Movimentações e Relatórios têm backend e código de tela prontos, mas estão desativados no menu atual (comentário em DrawerNavigator.tsx). Ver documento interno de lacunas.
• Swagger/OpenAPI da aplicação só liga com SWAGGER_ENABLED=true; o openapi.yaml deste diretório é uma análise estática independente, com exemplos sintéticos.