Skip to content

Documento de Modelagem de Dados

jota edited this page Aug 25, 2026 · 1 revision

Documento de Modelagem de Dados

⬅ Voltar para Documentação de Arquitetura


Entidades Principais

User (Usuário/Produtor)

Atributos:

  • id: number (PK, auto-increment)
  • associationId: number | null (FK → Association)
  • name: string (nome completo)
  • email: string (unique, formato email válido)
  • password: string (hash bcrypt)
  • userType: UserType | null (Pecuarista | Cooperativa | Associacao | Outro)
  • userCategory: UserCategory (Fisica | Juridica)
  • document: string | null (CPF ou CNPJ, unique)
  • city: string (cidade)
  • state: string (estado)
  • status: string (padrão: "Active")
  • resetToken: string | null (token único de reset, expira em 15min)
  • resetTokenExpiry: DateTime | null
  • createdAt: DateTime
  • updatedAt: DateTime

Relacionamentos:

  • 1-N com Animal (Usuário possui múltiplos animais)
  • 1-N com DailyCollection (Usuário registra múltiplas coletas)
  • N-1 com Association (Usuário vinculado a 1 associação)
  • 1-N com Invite (Usuário recebe múltiplos convites)

Regras de Negócio:

  • Email e document devem ser únicos no sistema
  • Senha deve ter mínimo 8 caracteres, 1 maiúscula, 1 número
  • Token de reset expira em 15 minutos
  • Associação é opcional (usuário pode ou não estar vinculado)

Exemplo de Código (Prisma Schema):

model User {
  id                    Int              @id @default(autoincrement())
  associationId         Int?
  association           Association?     @relation(fields: [associationId], references: [id])
  name                  String
  email                 String           @unique
  password              String
  userType              UserType?
  userCategory          UserCategory
  document              String?          @unique // CPF ou CNPJ
  city                  String
  state                 String
  status                String           @default("Active")
  resetToken            String?
  resetTokenExpiry      DateTime?
  createdAt             DateTime         @default(now())
  updatedAt             DateTime         @updatedAt
  animals               Animal[]
  dailyCollections      DailyCollection[]
  invites               Invite[]
}

enum UserType {
  Pecuarista
  Cooperativa
  Associacao
  Outro
}

enum UserCategory {
  Fisica
  Juridica
}

Animal

Atributos:

  • id: number (PK, auto-increment)
  • name: string | null (nome do animal)
  • animalType: AnimalType (Vaca | Cabra | Ovelha | Bufala | Outro)
  • breed: string (raça)
  • age: number (idade em anos)
  • userId: number (FK → User, obrigatório)
  • status: string (padrão: "Active")
  • createdAt: DateTime
  • updatedAt: DateTime

Relacionamentos:

  • N-1 com User (Animal pertence a 1 usuário)

Regras de Negócio:

  • Usuário pode cadastrar múltiplos animais
  • Animal com status inativo não participa de coletas
  • Nome opcional

Exemplo de Código (Prisma Schema):

model Animal {
  id              Int              @id @default(autoincrement())
  name            String?
  animalType      AnimalType
  breed           String
  age             Int
  userId          Int
  status          String           @default("Active")
  user            User             @relation(fields: [userId], references: [id])
  createdAt       DateTime         @default(now())
  updatedAt       DateTime         @updatedAt
}

enum AnimalType {
  Vaca
  Cabra
  Ovelha
  Bufala
  Outro
}

DailyCollection (Coleta Diária)

Atributos:

  • id: number (PK, auto-increment)
  • quantity: float (litros coletados, > 0)
  • collectionDate: DateTime (data e hora da coleta)
  • userId: number (FK → User)
  • numAnimals: number (número de animais ordenados)
  • numOrdens: number (número de ordenhas realizadas)
  • rationProvided: boolean (ração foi fornecida)
  • numLactation: number (número de lactações)
  • milkingPlace: MilkingPlace (Aberto | Curral | Ambos)
  • technicalAssistance: boolean (recebeu assistência técnica)
  • createdAt: DateTime
  • updatedAt: DateTime

Relacionamentos:

  • N-1 com User (Coleta pertence a 1 usuário)

Regras de Negócio:

  • Quantidade deve ser > 0L
  • Usuário pode registrar coletas com ou sem vínculo a uma associação

Exemplo de Código (Prisma Schema):

model DailyCollection {
  id                    Int              @id @default(autoincrement())
  quantity              Float
  collectionDate        DateTime         @default(now())
  userId                Int
  user                  User             @relation(fields: [userId], references: [id])
  numAnimals            Int
  numOrdens             Int
  rationProvided        Boolean
  numLactation          Int
  milkingPlace          MilkingPlace
  technicalAssistance   Boolean
  createdAt             DateTime         @default(now())
  updatedAt             DateTime         @updatedAt
}

enum MilkingPlace {
  Aberto
  Curral
  Ambos
}

Invite (Convite)

Atributos:

  • id: number (PK, auto-increment)
  • associationId: number (FK → Association)
  • userId: number (FK → User, convidado)
  • token: string (unique, UUID gerado automaticamente)
  • status: InviteStatus (PENDING | ACCEPTED | DECLINED | EXPIRED | CANCELED)
  • message: string | null
  • customMessage: string | null (mensagem personalizada)
  • sentAt: DateTime (quando foi enviado)
  • expiresAt: DateTime (data de expiração)
  • respondedAt: DateTime | null (quando foi respondido)
  • createdAt: DateTime
  • updatedAt: DateTime

Relacionamentos:

  • N-1 com User (Convite destinado a 1 usuário)
  • N-1 com Association (Convite enviado por 1 associação)

Regras de Negócio:

  • Token UUID gerado automaticamente
  • Expira em 7 dias após criação
  • Ao aceitar convite, User.associationId é atualizado
  • CRON job diário (02:00) marca convites expirados como EXPIRED

Exemplo de Código (Prisma Schema):

model Invite {
  id                    Int              @id @default(autoincrement())
  associationId         Int
  association           Association      @relation(fields: [associationId], references: [id])
  userId                Int
  user                  User             @relation(fields: [userId], references: [id])
  token                 String           @unique @default(uuid())
  status                InviteStatus     @default(PENDING)
  message               String?
  customMessage         String?
  sentAt                DateTime         @default(now())
  expiresAt             DateTime
  respondedAt           DateTime?
  createdAt             DateTime         @default(now())
  updatedAt             DateTime         @updatedAt

  @@index([associationId])
  @@index([userId])
  @@index([status])
  @@index([token])
  @@index([expiresAt])
}

enum InviteStatus {
  PENDING
  ACCEPTED
  DECLINED
  EXPIRED
  CANCELED
}

Association (Associação)

Atributos principais:

  • id: number (PK, auto-increment)
  • name: string (razão social)
  • tradeName: string | null (nome fantasia)
  • cnpj: string (unique)
  • stateRegistration: string | null (inscrição estadual)
  • email: string (unique)
  • password: string (hash bcrypt)
  • landlinePhone: string (telefone fixo)
  • mobilePhone: string | null (celular)
  • website: string | null
  • zipCode: string (CEP)
  • state: string (UF)
  • city: string (município)
  • street: string (logradouro)
  • number: string (número)
  • complement: string | null
  • neighborhood: string (bairro)
  • foundationDate: DateTime | null
  • numberOfMembers: number | null (número de associados)
  • coverageArea: CoverageArea (Municipal | Regional | Estadual)
  • presidentName: string (nome do presidente)
  • presidentCpf: string (CPF do presidente)
  • presidentEmail: string (email do presidente)
  • presidentPhone: string (telefone do presidente)
  • status: string (padrão: "Active")
  • createdAt: DateTime
  • updatedAt: DateTime

Relacionamentos:

  • 1-N com User (Associação gerencia múltiplos usuários)
  • 1-N com Invite (Associação envia múltiplos convites)

Regras de Negócio:

  • CNPJ e email devem ser únicos
  • Associação pode visualizar dados agregados de seus usuários
  • Pode convidar novos usuários

Exemplo de Código (Prisma Schema - simplificado):

model Association {
  id                    Int              @id @default(autoincrement())
  name                  String
  tradeName             String?
  cnpj                  String           @unique
  stateRegistration     String?
  email                 String           @unique
  password              String
  landlinePhone         String
  mobilePhone           String?
  website               String?
  zipCode               String
  state                 String
  city                  String
  street                String
  number                String
  complement            String?
  neighborhood          String
  foundationDate        DateTime?
  numberOfMembers       Int?
  coverageArea          CoverageArea
  presidentName         String
  presidentCpf          String
  presidentEmail        String
  presidentPhone        String
  status                String           @default("Active")
  users                 User[]
  invites               Invite[]
  createdAt             DateTime         @default(now())
  updatedAt             DateTime         @updatedAt
  @@index([city, state])
  @@index([status])
  @@index([cnpj])
}

enum CoverageArea {
  Municipal
  Regional
  Estadual
}

Notification (Notificação)

Atributos:

  • id: number (PK, auto-increment)
  • associationId: number (ID da associação)
  • subject: string (assunto)
  • message: string (mensagem)
  • metadata: string | null (JSON com dados adicionais)
  • createdAt: DateTime

Relacionamentos:

  • Associado a uma Association via associationId (não éFK formal)

Regras de Negócio:

  • Sistema de notificações para associações
  • Metadata armazena informações adicionais em formato JSON

Exemplo de Código (Prisma Schema):

model Notification {
  id                    Int              @id @default(autoincrement())
  associationId         Int
  subject               String
  message               String
  metadata              String?          // JSON string
  createdAt             DateTime         @default(now())

  @@index([associationId])
  @@index([createdAt])
}

Diagrama de Relacionamentos (ER)

Diagrama de Entidade Relacionamento


Regras de Negócio

Esta seção centraliza as regras de negócio do sistema para facilitar a rastreabilidade entre requisitos, implementação e testes.

ID Regra Descrição Técnica Local de Implementação
BR-001 Unicidade de Email O sistema não pode ter dois usuários (Produtor ou Associação) com mesmo email. PrismaExceptionFilter (Erro P2002)
BR-002 Expiração de Convite Convites vencem em 7 dias corridos. O job de limpeza roda diariamente às 02:00 AM. InvitesCleanupService
BR-003 Validação de Senha Mínimo 8 caracteres, 1 maiúscula, 1 número, 1 caractere especial. CreateUserDto (Regex)
BR-004 Rate Limiting Login Máximo de 3 tentativas falhas por minuto por IP para prevenir brute-force. AuthController (@Throttle)
BR-005 Rate Limiting Geral Endpoints protegidos têm limite de 100 requisições por minuto por IP. ThrottlerModule (Global)
BR-006 Associação Opcional Produtores podem ou não estar vinculados a uma associação. Campo associationId é nullable. User (Prisma Schema)
BR-007 Sanitização de Logs Dados sensíveis (senha, tokens, CPF) devem ser removidos/ofuscados dos logs para conformidade LGPD. logger.config.ts
BR-008 Alerta de Medicação Repetida Sistema deve alertar quando mesmo tipo de medicação é aplicado 3x em 30 dias (funcionalidade futura). Módulo de Análise (Planejado)
BR-009 Quantidade Positiva de Leite Registro de coleta diária deve ter quantidade > 0 litros. DailyCollection (Validação DTO)

Regras de Negócio Compartilhadas

1. Ciclo de Vida do Convite

// Estado inicial
Invite { status: PENDING, expiresAt: now() + 7 days }

// Fluxos possíveis:
PENDING → ACCEPTED (produtor aceita via token)
PENDING → REJECTED (produtor rejeita via token)
PENDING → EXPIRED (CRON job diário marca expirados)

// Regras:
- ACCEPTED: User.associationId = Invite.associationId
- REJECTED/EXPIRED: Convite arquivado (não deletado)

2. Vínculo Produtor-Associação (Opcional)

// Vínculo é opcional - usuário pode ou não estar vinculado a uma associação
// O campo associationId pode ser null

// Ao aceitar um convite, o usuário é vinculado à associação
if (invite.status === InviteStatus.ACCEPTED) {
  await this.usersService.update(userId, {
    associationId: invite.associationId
  });
}

// Usuário pode registrar coletas independentemente de estar vinculado
// NÃO há validação de associationId obrigatória
@Injectable()
export class DailyCollectionsService {
  async create(userId: number, dto: CreateDailyCollectionDto) {
    // Usuários com ou sem associação podem registrar coletas
    return this.prisma.dailyCollection.create({
      data: { userId, ...dto }
    });
  }
}

3. Expiração de Tokens

// Reset de Senha: 15 minutos
const resetTokenExpiration = new Date();
resetTokenExpiration.setMinutes(resetTokenExpiration.getMinutes() + 15);

// Convite: 7 dias
const inviteExpiration = new Date();
inviteExpiration.setDate(inviteExpiration.getDate() + 7);

// Validação
if (now > expiresAt) {
  throw new UnauthorizedException("Token expirado");
}

Clone this wiki locally