📚 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.

[!IMPORTANT] Antes de começar: Verifique se todas as ferramentas necessárias estão instaladas e funcionando. Consulte o Guia de Setup do Ambiente para instalar Java 17, Node.js 18, Angular CLI e Git corretamente antes de prosseguir.

🚀 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.

🎯 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:

📊 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

🏁 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