📚 Módulo 00: Introdução, Arquitetura e Visão Geral

Bem-vindo ao guia prático do projeto TecLoja! Este módulo apresenta os fundamentos conceituais, os objetivos de aprendizagem, a arquitetura de software e a estrutura física do ecossistema que será desenvolvido passo a passo.

✅ Pré-Requisitos deste Módulo

Antes de começar, confirme que o ambiente está pronto:

java -version    # deve retornar 17.x
node -v           # deve retornar 18.x ou superior
ng version        # Angular CLI instalado globalmente
git --version

Se algum desses comandos falhar ou retornar uma versão incompatível, consulte o Guia de Setup do Ambiente antes de prosseguir — ele cobre a instalação de Java 17, Node.js 18, Angular CLI e Git passo a passo.

---

🚀 Passo Zero: Gerando a base com Spring Initializr

Antes de entrarmos nos detalhes arquiteturais, você precisará gerar o projeto base (casca) do nosso servidor Java. Siga o passo a passo abaixo para criar a estrutura oficial que utilizaremos ao longo dos próximos módulos:

1. Acesse o site oficial do gerador: https://start.spring.io/
2. Preencha as configurações principais da seguinte forma:
   • Project: Maven
   • Language: Java
   • Spring Boot: 3.2.5 (ou versão mais recente equivalente)
3. Na seção Project Metadata, preencha os campos corporativos:
   • Group: br.com.tecloja
   • Artifact: api
   • Name: backend
   • Description: API REST para E-commerce TecLoja
   • Package name: br.com.tecloja.api
   • Packaging: Jar
   • Java: 17
4. Na seção lateral Dependencies, clique em ADD DEPENDENCIES e procure pelas seguintes bibliotecas:
   • Spring Web
   • Spring Data JPA
   • H2 Database
   • PostgreSQL Driver
   • Validation
   • Spring Security
5. Por fim, clique no botão GENERATE. O seu navegador fará o download de um arquivo .zip.
6. Descompacte este arquivo e renomeie a pasta resultante para backend. Mova esta pasta para o seu diretório de trabalho. Nós analisaremos essa estrutura de pastas mais adiante neste mesmo módulo.

🤔 Por que adicionar H2 Database e PostgreSQL Driver ao mesmo tempo?

Vamos usar dois bancos diferentes ao longo do curso, cada um com um papel: o H2 é um banco em memória, criado e destruído junto com a aplicação — perfeito para desenvolvimento local, pois você não precisa instalar nada e cada reinício começa com dados limpos. O PostgreSQL (via Neon, no Módulo 02) é o banco real de produção, persistente. Ter as duas dependências no pom.xml desde o início evita ter que voltar ao Spring Initializr depois; qual delas é usada em cada ambiente é decidido por profile do Spring (application.properties vs application-prod.properties), não pela dependência em si.

🔍 Checkpoint

Depois de gerar e mover a pasta backend, confirme que o projeto compila e sobe sozinho, mesmo sem nenhum código nosso ainda:

cd backend
./mvnw spring-boot:run

Resultado esperado: o banner do Spring Boot aparece no terminal, seguido por uma linha como Started TeclojaApiApplication in X.XXX seconds. Pressione Ctrl+C para parar antes de continuar.

⚠️ Erros Comuns

Sintoma	Causa	Solução
'mvnw' não é reconhecido como um comando (Windows)	Esqueceu de entrar na pasta backend antes de rodar	Confirme com cd backend e rode ./mvnw spring-boot:run (ou mvnw.cmd spring-boot:run no cmd.exe)
Permission denied ao rodar ./mvnw (Linux/macOS)	O arquivo mvnw perdeu a permissão de execução ao descompactar o zip	Rode chmod +x mvnw uma vez na pasta backend
Port 8080 was already in use	Outra aplicação (ou uma instância anterior do TecLoja) já está usando a porta	Pare o processo anterior, ou rode com ./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081
Build trava em “Downloading from central” por muito tempo	Primeira execução baixando todas as dependências do Maven	Normal na primeira vez (pode levar alguns minutos); execuções seguintes usam o cache local em ~/.m2

---

🎯 Apresentação do Estudo de Caso

A TecLoja é uma plataforma simplificada de comércio eletrônico de produtos de tecnologia. A escolha de um e-commerce como projeto de estudo deve-se à riqueza de suas regras de negócio e de sua modelagem de dados, representando um cenário perfeito para unir teoria e prática de Engenharia de Software e Banco de Dados.

O que construiremos?

1. API RESTful (Backend): Uma aplicação Spring Boot protegida por segurança stateless que processa transações de venda, gerencia estoque e realiza autenticação.
2. SPA (Frontend): Uma aplicação web rica com Angular que consome a API REST, possui área pública (catálogo e carrinho reativo) e área administrativa protegida para gestão de estoque.

---

🏛️ A Escolha Arquitetural: Desacoplamento e Multirepo

Ao contrário de abordagens monolíticas ou monorepositórios, a TecLoja adota uma Arquitetura Multirepo com Desacoplamento Total. Isso significa que a API e a SPA residem em repositórios Git diferentes e são implantadas em servidores cloud distintos.

flowchart TD
    subgraph "Clientes (Interfaces do Usuário)"
        AngularSPA["Web SPA (Netlify)<br>http://tecloja.netlify.app"]
        IonicApp["App Mobile Híbrido (Ionic/Capacitor)<br>Dispositivo Android/iOS"]
    end

    subgraph "Servidores Nuvem (Cloud)"
        SpringAPI["Spring Boot API (Render)<br>https://backend.render.com"]
        NeonDB[("Neon PostgreSQL<br>(Postgres Cloud DB)")]
    end

    AngularSPA -- "1a. HTTPS / JSON" --> SpringAPI
    IonicApp -- "1b. HTTPS / JSON" --> SpringAPI
    SpringAPI -- "2. Conexão JDBC (JPA)" --> NeonDB

🧠 Vantagens Pedagógicas e Mercadológicas desta Divisão:

• Independência de Release: Alterações no frontend não afetam a disponibilidade do backend e vice-versa. Os deploys ocorrem de forma assíncrona.
• Segurança de Origem (CORS): O navegador impede nativamente que o frontend em um domínio (netlify.app) acesse a API em outro domínio (render.com) sem autorização expressa. Aprenderemos a configurar as regras de CORS no Spring Boot, um dos tópicos mais importantes em segurança web corporativa.
• Escalabilidade Diferenciada: O frontend estático necessita de pouca CPU (servido por CDN), enquanto o backend lida com processamento lógico pesado, permitindo escalá-los de forma proporcional.

---

📊 Modelagem Comportamental e Arquitetural

1. Diagrama de Casos de Uso (Mermaid)

Este diagrama mapeia o escopo funcional do sistema, identificando os atores (Cliente e Administrador) e suas respectivas interações permitidas.

flowchart LR
    Cliente((Cliente))
    Admin((Administrador))

    subgraph "Sistema TecLoja"
        UC1("Autenticar no Sistema")
        UC2("Visualizar Catálogo de Produtos")
        UC3("Gerenciar Carrinho de Compras")
        UC4("Finalizar Pedido (Checkout)")
        UC5("Gerenciar Catálogo (CRUD)")
        UC6("Monitorar Estoque dos Eletrônicos")
    end

    Cliente --> UC1
    Cliente --> UC2
    Cliente --> UC3
    Cliente --> UC4

    Admin --> UC1
    Admin --> UC5
    Admin --> UC6

2. Diagrama de Sequência de Autenticação JWT e CORS (Mermaid)

O diagrama abaixo ilustra o ciclo de vida de uma requisição autenticada do Frontend para o Backend, passando pela validação do protocolo CORS (Preflight Request) e o anexo do cabeçalho de Autorização Bearer Token.

sequenceDiagram
    autonumber
    actor Cliente as Usuário
    participant SPA as Angular SPA (Netlify)
    participant API as Spring Boot API (Render)
    participant DB as Banco de Dados (Neon)

    Cliente->>SPA: Preenche credenciais e clica em "Login"
    SPA->>API: POST /api/auth/login (Credenciais)
    API->>DB: Consulta Usuário e Senha
    DB-->>API: Dados do Usuário correspondentes
    API->>API: Valida credenciais e gera Token JWT
    API-->>SPA: Retorna Token JWT e dados básicos
    SPA->>SPA: Grava Token no LocalStorage / Signal

    Note over SPA, API: Próxima Requisição (Ex: Criar Pedido)
    SPA->>API: HTTP OPTIONS /api/pedidos (CORS Preflight)
    API-->>SPA: HTTP 200 OK (Permite a origem do Netlify)
    SPA->>API: POST /api/pedidos (JSON + Authorization: Bearer JWT)
    API->>API: Filtro valida assinatura do JWT
    API->>DB: Executa lógica e persiste pedido no banco
    DB-->>API: Confirmação de persistência
    API-->>SPA: HTTP 201 Created (Pedido salvo)
    SPA-->>Cliente: Exibe tela de sucesso

---

📁 Estrutura de Pastas e Arquivos dos Projetos

Os alunos gerenciarão dois projetos totalmente separados. Abaixo está o mapeamento detalhado da estrutura física que será construída no decorrer do guia.

🏢 1. Repositório Backend (backend)

Representa um projeto Java robusto construído sob a ferramenta Maven.

backend/
├── .github/
│   └── workflows/
│       └── deploy-backend.yml      # CI/CD no GitHub Actions para a Render
├── src/
│   ├── main/
│   │   ├── java/br/com/tecloja/api/
│   │   │   ├── TeclojaApiApplication.java    # Classe de boot do Spring
│   │   │   ├── config/                       # Configuração CORS, Security e Swagger
│   │   │   ├── controller/                   # Endpoints REST (Controllers)
│   │   │   ├── dto/                          # Objetos de Transferência (Request/Response)
│   │   │   ├── exception/                    # Exceções customizadas e Handler Global
│   │   │   ├── mapper/                       # Conversores Entity <-> DTO
│   │   │   ├── model/                        # Entidades mapeadas com JPA
│   │   │   ├── repository/                   # Comunicação de dados (Spring Data JPA)
│   │   │   └── service/                      # Regras de Negócio e Serviços
│   │   └── resources/
│   │       ├── application.properties        # Configurações de dev (H2)
│   │       ├── application-prod.properties   # Configurações de prod (Neon PostgreSQL)
│   │       └── schema.sql                    # Estrutura DDL inicial do banco
│   └── test/                                 # Testes Unitários de Integração (JUnit/Mockito)
├── Dockerfile                                # Build da imagem multi-stage
├── mvnw & mvnw.cmd                           # Executáveis do Maven Wrapper
└── pom.xml                                   # Dependências do projeto Java

🎨 2. Repositório Frontend (web)

Representa um projeto moderno Angular 18 estruturado sobre componentes standalone reativos.

web/
├── .github/
│   └── workflows/
│       └── deploy-frontend.yml     # CI/CD no GitHub Actions para Netlify
├── src/
│   ├── app/
│   │   ├── components/               # Componentes Standalone (Navbar, CRUD, Carrinho)
│   │   ├── guards/                   # Proteção de rotas administrativas
│   │   ├── interceptors/             # Injeção automática do Token JWT em chamadas
│   │   ├── models/                   # Tipagens e interfaces TypeScript
│   │   ├── services/                 # Serviços HTTP de integração e estado (Signals)
│   │   ├── app.config.ts             # Configurações globais standalone do Angular
│   │   ├── app.routes.ts             # Roteador de navegação dinâmica
│   │   └── app.component.ts          # Componente raiz da SPA
│   ├── index.html                    # Página esqueleto da aplicação
│   └── styles.css                    # Estilização global moderna
├── angular.json                      # Configurações do ecossistema Angular
├── package.json                      # Dependências npm e scripts
└── tsconfig.json                     # Configuração do compilador TypeScript

📱 3. Repositório Mobile (mobile)

Representa o aplicativo híbrido focado em dispositivos móveis, construído com Ionic Framework e Angular, com acesso ao hardware via Capacitor.

mobile/
├── android/                          # Código Java/Kotlin gerado para o Android Studio
├── cypress/                          # (Módulo 13) Testes automatizados E2E do Frontend
│   └── e2e/
│       └── jornada-compras.cy.ts     # Script do robô de testes Cypress
├── src/
│   ├── app/
│   │   ├── interceptors/             # auth.interceptor.ts (Injeta Token nas requisições)
│   │   ├── services/                 # auth.service.ts (Lê Token do Hardware via Capacitor)
│   │   ├── tab1/                     # (Módulo 10) Catálogo visual responsivo com ion-card
│   │   ├── tab2/                     # (Módulo 11) Formulário de Login adaptado para celular
│   │   └── tab3/                     # (Módulo 12) Tela com botão para acionar Câmera Nativa
│   └── index.html                    # Ponto de entrada do DOM Mobile
├── capacitor.config.ts               # Mapeamento e permissões de hardware
├── ionic.config.json                 # Configuração do compilador do Ionic
└── package.json                      # Dependências de UI e Plugins Nativos

---

📋 Resumo de Comandos

# Dentro da pasta backend/, gerada pelo Spring Initializr
cd backend

# (Linux/macOS apenas) garantir que o wrapper do Maven é executável
chmod +x mvnw

# Checkpoint: sobe a aplicação sem nenhum código nosso ainda
./mvnw spring-boot:run

---

🏁 Conclusão e Próximos Passos

Com a compreensão da arquitetura do ecossistema da TecLoja e de suas responsabilidades, estamos prontos para projetar a persistência de dados.

No Módulo 01, abordaremos a fundo o Banco de Dados: projetando o diagrama ER, escrevendo o script DDL relacional e mapeando as entidades em classes Java com o suporte da especificação JPA (Hibernate).

---

Voltar para o Sumário

⬅️ Anterior Próximo ➡️