Skip to content

Contexto e Escopo

jota edited this page Aug 25, 2026 · 1 revision

Contexto e Escopo

⬅ Voltar para Documentação de Arquitetura


Contexto e Escopo

Esta seção delimita as fronteiras do sistema QuaLeiDer, mostrando como ele interage com o mundo externo (usuários, sistemas, infraestrutura). O objetivo é responder: "O que está dentro e o que está fora do sistema?"


Contexto de Negócio {#_contexto_negocial}

O contexto de negócio mostra os atores humanos e sistemas de negócio externos que interagem com o QuaLeiDer do ponto de vista do usuário final. Infraestrutura técnica (banco de dados, servidores SMTP, CI/CD) não aparecem aqui — eles são transparentes para os usuários e pertencem ao Contexto Técnico.

Diagrama de Contexto

Contexto do Sistema

Atores e Sistemas Externos

Entidade Externa Tipo Responsabilidades Interface de Comunicação
Produtor de Leite Pessoa (Usuário Final) - Registrar coletas diárias de leite
- Gerenciar cadastro de animais
- Aceitar/recusar convites de associações
- Consultar histórico de coletas
REST API (JSON via HTTPS)
Autenticação: JWT Bearer Token
Associação Pessoa (Gestor) - Convidar novos produtores
- Visualizar dados agregados de produção
- Gerenciar lista de produtores vinculados
- Acessar relatórios analíticos
REST API (JSON via HTTPS)
Autenticação: JWT Bearer Token

Interfaces de Domínio Externo

1. Interface Produtor ↔ QuaLeiDer

Fluxos de Entrada (Produtor → Sistema):

  • POST /auth/login: Autenticação com email/senha → Retorna JWT
  • POST /daily-collections: Registra nova coleta diária → Retorna ID da coleta
  • POST /animals: Cadastra novo animal → Retorna dados do animal
  • PUT /invites/:token/accept: Aceita convite de associação → Vincula produtor

Fluxos de Saída (Sistema → Produtor):

  • Email de Boas-vindas: Enviado após aceitar convite (via SMTP)
  • Email de Reset de Senha: Link com token de 15 minutos de validade

Formato de Dados: JSON (application/json)
Autenticação: JWT Bearer Token (após login)


2. Interface Associação ↔ QuaLeiDer

Fluxos de Entrada (Associação → Sistema):

  • POST /invites: Cria convite para produtor → Retorna token único
  • GET /daily-collections/reports: Consulta relatórios agregados → Retorna estatísticas
  • GET /users?associationId=X: Lista produtores vinculados → Retorna array de usuários

Fluxos de Saída (Sistema → Associação):

  • Email de Notificação: Quando produtor aceita/recusa convite (via SMTP)

Formato de Dados: JSON (application/json)
Autenticação: JWT Bearer Token (após login)


Contexto Técnico {#_contexto_t_cnico}

O contexto técnico detalha as tecnologias e protocolos utilizados na comunicação entre o sistema e suas dependências externas.

Diagrama de Contexto Técnico

Contexto Técnico

Mapeamento de Interfaces Técnicas

Canal de Comunicação Protocolo/Tecnologia Formato de Dados Autenticação/Segurança Porta/Endpoint
Cliente ↔ Nginx (Proxy) HTTP/1.1 (REST/Static) JSON / HTML - 8080 (Dev)
80/443 (Prod)
Nginx ↔ API Backend HTTP/1.1 (REST) JSON (application/json) JWT HS256 (Bearer Token) 3000
/api/*
Nginx ↔ Frontend HTTP/1.1 HTML / JS - 3000
Backend ↔ PostgreSQL PostgreSQL Wire Protocol
TCP/IP
Prisma Query Language → SQL Usuario/Senha (env vars)
Conexão criptografada (SSL)
5432
postgresql://user:pass@host:5432/db
Backend ↔ SMTP Server SMTP over TLS (STARTTLS) MIME (Multipart/HTML) SMTP AUTH (user/password)
TLS 1.2+
587 (TLS)
465 (SSL)
smtp.ethereal.email
GitHub Actions ↔ Backend HTTPS GitHub Workflow YAML GitHub Token (secrets) N/A (CI/CD webhook)

Detalhamento das Interfaces Técnicas

1. Interface HTTP REST (Cliente ↔ Backend)

Tecnologia: Express.js (via NestJS)
Formato: JSON (Content-Type: application/json)
Versionamento: Prefixo /api/v1/ em todas as rotas

Exemplo de Requisição:

POST /api/v1/daily-collections HTTP/1.1
Host: localhost:3000
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "userId": 1,
  "date": "2025-11-17",
  "quantity": 45.5,
  "milkingCount": 2,
  "animalIds": [1, 2, 3]
}

Exemplo de Resposta:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 42,
  "userId": 1,
  "date": "2025-11-17",
  "quantity": 45.5,
  "animals": [
    {"id": 1, "name": "Mimosa"},
    {"id": 2, "name": "Estrela"}
  ]
}

Códigos HTTP Utilizados:

  • 200 OK: Operação bem-sucedida (GET, PUT)
  • 201 Created: Recurso criado (POST)
  • 204 No Content: Exclusão bem-sucedida (DELETE)
  • 400 Bad Request: Validação de DTO falhou
  • 401 Unauthorized: Token JWT inválido/expirado
  • 403 Forbidden: Usuário sem permissão
  • 404 Not Found: Recurso inexistente
  • 409 Conflit: Conflito
  • 429 Too Many Requests: Limite de rate limiting excedido
  • 500 Internal Server Error: Erro não tratado

2. Interface Prisma ↔ PostgreSQL

Tecnologia: Prisma Client 6.3.1 (ORM Type-safe)
Protocolo: PostgreSQL Wire Protocol (TCP/IP)
Connection Pooling: Configurado automaticamente pelo Prisma

Exemplo de Query (Prisma):

// TypeScript (Prisma Client)

  async create(data: Omit<DailyCollectionEntity, 'id' | 'createdAt' | 'updatedAt'>): Promise<DailyCollectionEntity> {
    try {
      const created = await this.prisma.dailyCollection.create({
        data: {
          userId: data.userId,
          quantity: data.quantity,
          collectionDate: data.collectionDate,
          numAnimals: data.numAnimals,
          numOrdens: data.numOrdens,
          rationProvided: data.rationProvided,
          numLactation: data.numLactation,
          milkingPlace: data.milkingPlace as unknown as MilkingPlace,
          technicalAssistance: data.technicalAssistance,
        },
      });
      return DailyCollectionMapper.toDomain(created);
    } catch (error) {
      handlePrismaError(error, {
        [PrismaErrorCode.FOREIGN_KEY_CONSTRAINT_FAILED]: 'Produtor (User) inválido ou não encontrado.',
      });
    }
  }

SQL Gerado (PostgreSQL):

BEGIN;
INSERT INTO "DailyCollection" ("userId", "quantity", ...) VALUES (data.userId, data.quantity, ...);
COMMIT;

Configuração de Conexão (.env):

DATABASE_URL="postgresql://postgres:password@localhost:5432/qualeider_db"

3. Interface Nodemailer ↔ SMTP

Tecnologia: Nodemailer 6.10.0
Protocolo: SMTP over TLS (STARTTLS)
Templates: Handlebars (.hbs) para HTML dinâmico

Exemplo de Envio de Email:

// TypeScript (MailService)
await this.mailerService.sendMail({
  to: "produtor@example.com",
  subject: "Convite para associação",
  template: "./invite-email",
  context: {
    associationName: "Cooperativa ABC",
    token: "abc123...",
    expiresIn: "7 dias",
  },
});

Configuração SMTP (.env):

# Desenvolvimento: Ethereal Email
MAIL_HOST=smtp.ethereal.email
MAIL_PORT=587                  # TLS
MAIL_USER=user@ethereal.email  # Gerado em https://ethereal.email
MAIL_PASSWORD=secret           # Gerado em https://ethereal.email
MAIL_FROM=noreply@qualeider.com

Formato MIME (Enviado):

From: noreply@qualeider.com
To: produtor@example.com
Subject: Convite para associação
Content-Type: multipart/alternative; boundary="----Boundary"

------Boundary
Content-Type: text/plain; charset=UTF-8

Olá! Você foi convidado para a Cooperativa ABC...

------Boundary
Content-Type: text/html; charset=UTF-8

<html>
  <body>
    <h1>Convite para Associação</h1>
    <p>Token: abc123...</p>
  </body>
</html>

O sistema depende de variáveis de ambiente para configurar interfaces externas:

# Banco de Dados
DATABASE_URL="postgresql://user:pass@host:5432/qualeider"

# Autenticação
JWT_SECRET="strong-random-secret-key-here"
JWT_EXPIRATION="24h"

# Email (SMTP) - Desenvolvimento: Ethereal
MAIL_HOST="smtp.ethereal.email"
MAIL_PORT=587
MAIL_USER="user@ethereal.email"
MAIL_PASSWORD="password"
MAIL_FROM="noreply@qualeider.com"

# Aplicação
PORT=3000
NODE_ENV="production"

Segurança: Nenhuma dessas variáveis pode estar hardcoded. Devem ser configuradas via .env (local) ou secrets do provedor de cloud (produção).


Clone this wiki locally