Modelo de Dados

Introdução ao documento

Este documento registra entidades, relacionamentos e regras de integridade do modelo de dados do activity-delivery-api.

Versionamento

• Versão do documento: 1.0.0
• Última atualização: 2026-03-04
• Responsável: Time Dhedalos

Referencial teórico

• Mermaid ER Diagram
• DBML

Escopo e fontes

• Fonte principal: migrations em database/migrations/, models em app/Models/.
• Banco de dados: MySQL 8.0 (dev) / PostgreSQL (produção).

Entidades principais

Entidade	Fonte	Objetivo
users	database/migrations/*_create_users_table.php, app/Models/User.php	Usuários do sistema (admin, facilitadores)
deliverable_submissions	database/migrations/*_create_deliverable_submissions_table.php, app/Models/DeliverableSubmission.php	Submissões de atividades entregáveis
submission_files	database/migrations/*_create_submission_files_table.php, app/Models/SubmissionFile.php	Arquivos anexos das submissões
activity_template_files	database/migrations/*_create_activity_template_files_table.php, app/Models/ActivityTemplateFile.php	Arquivos modelo para atividades
api_keys	database/migrations/*_create_api_keys_table.php, app/Models/ApiKey.php	Chaves de acesso à API
novu_keys	database/migrations/*_create_novu_keys_table.php, app/Models/NovuKey.php	Chaves de workflow do Novu (notificações)
roles	Spatie Permission migration, app/Models/Role.php	Papéis de usuário (admin, user)
permissions	Spatie Permission migration, app/Models/Permission.php	Permissões granulares

Relacionamentos

1. users → roles (N:M via model_has_roles) — Spatie Permission
   • Evidência: app/Models/User.php:19 (trait HasRoles)
2. users → permissions (N:M via model_has_permissions) — Spatie Permission
   • Evidência: app/Models/User.php:19 (trait HasRoles)
3. roles → permissions (N:M via role_has_permissions) — Spatie Permission
   • Evidência: Spatie Permission migration
4. deliverable_submissions → submission_files (1:N)
   • Evidência: app/Models/DeliverableSubmission.php:35 — files() hasMany
5. submission_files → deliverable_submissions (N:1)
   • Evidência: app/Models/SubmissionFile.php:27 — submission() belongsTo

Campos relevantes

users

• id: PK auto-increment
• name: string, required
• email: string, unique
• email_verified_at: timestamp, nullable
• password: string, hashed (cast)
• remember_token: string, nullable
• two_factor_secret, two_factor_recovery_codes, two_factor_confirmed_at: Fortify 2FA
• Evidência: database/migrations/0001_01_01_000000_create_users_table.php:15

deliverable_submissions

• id: PK auto-increment
• participant_id: bigint, required — ID externo do participante
• participant_email: string, nullable
• participant_name: string, nullable
• activity_id: bigint, required — ID externo da atividade
• title: string, required
• class_id: bigint, required — ID externo da turma
• class_name: string, nullable
• course_id: bigint, required — ID externo do curso
• course_name: string, nullable
• cycle_id: bigint, required — ID externo do ciclo
• facilitator_id: bigint, required — ID externo do facilitador
• facilitator_name: string, nullable
• facilitator_email: string, nullable
• status: enum (pending, submitted, submitted_external, evaluated), default pending
• score: tinyint unsigned, default 0
• facilitator_comment: text, nullable
• evaluated_at: timestamp, nullable
• deleted_at: soft delete
• Unique constraint: (participant_id, class_id, activity_id, cycle_id, deleted_at) — unique_submission
• Evidência: database/migrations/2025_05_27_161012_create_deliverable_submissions_table.php:15, database/migrations/2025_07_28_132021_add_unique_submission_constraint_to_deliverable_submissions.php:16

submission_files

• id: PK auto-increment
• deliverable_submission_id: FK → deliverable_submissions.id (cascade delete)
• file_path: string, required — caminho no storage (S3/local)
• original_name: string, nullable — nome original do arquivo
• file_type: string, nullable — MIME type
• Evidência: database/migrations/2025_05_27_161012_create_submission_files_table.php:15

activity_template_files

• id: PK auto-increment
• course_id: integer, required
• activity_id: integer, required
• cycle_id: integer, required
• class_id: integer, required
• file_path: string, required
• original_name: string, required
• file_type: string, nullable
• description: string, nullable
• deleted_at: soft delete
• Indexes: (course_id, activity_id), (cycle_id, class_id)
• Unique constraint: (course_id, activity_id, cycle_id, class_id, original_name) — activity_template_unique
• Evidência: database/migrations/2025_12_15_201931_create_activity_template_files.php:11

api_keys

• id: PK auto-increment
• key: string, unique — chave de acesso à API (64 caracteres aleatórios)
• description: string, nullable
• Evidência: database/migrations/2025_06_02_204124_create_api_keys_table.php:15

novu_keys

• id: PK auto-increment
• description: string, required
• novu_key: string, required — chave do workflow Novu
• app_key: string, unique — identificador do workflow na aplicação
• Evidência: database/migrations/2025_07_28_190146_create_novu_keys_table.php:15

Regras de integridade

• Unicidade de submissão: A combinação (participant_id, class_id, activity_id, cycle_id) é única (soft delete considerado), garantindo uma submissão por participante/atividade/turma/ciclo.
  • Evidência: database/migrations/2025_07_28_132021_add_unique_submission_constraint_to_deliverable_submissions.php:16
• Cascade delete: Ao deletar uma deliverable_submission, todos os submission_files associados são removidos automaticamente (cascade).
  • Evidência: database/migrations/2025_05_27_161012_create_submission_files_table.php:23
• Status enum: Validado por enum no banco: pending, submitted, submitted_external, evaluated.
  • Evidência: database/migrations/2025_06_10_000000_update_status_enum_in_deliverable_submissions_table.php:12
• MIME types permitidos: Validação de upload via MimeTypes::allowed() — imagens, vídeos, áudios, documentos.
  • Evidência: app/Helpers/MimeTypes.php:7

ERD (Mermaid)

Pendências

• ⚠️ PENDÊNCIA: Os campos participant_id, activity_id, class_id, course_id, cycle_id, facilitator_id na tabela deliverable_submissions são IDs externos (não são FKs no banco local). Documentar a origem desses IDs (provavelmente dhedalos-app-backend-wordpress ou sistema LMS externo).
• ⚠️ PENDÊNCIA: Verificar se existe necessidade de índices adicionais para queries de filtro frequentes em deliverable_submissions.