Repository navigation
Contexto e Escopo
⬅ Voltar para Documentação de Arquitetura
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?"
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.

| 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 |
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)
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)
O contexto técnico detalha as tecnologias e protocolos utilizados na comunicação entre o sistema e suas dependências externas.

| 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) |
5432postgresql://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) |
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
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"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.comFormato 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).