Modelo do Banco de Dados - LucasXRosas/utfprarena GitHub Wiki

Esta página documenta a estrutura de dados necessária para suportar o gerenciamento de usuários, faturas e o controle de bloqueio automatizado da arena de beach tennis.

Vídeo de Apresentação

https://www.youtube.com/watch?v=ThzJdg1sogE

Diagrama Entidade-Relacionamento (Conceitual)

1. Estrutura das Tabelas (Dicionário de Dados)

1. Tabela: `users`

Armazena todos os atores do sistema (gestores, professores e alunos). O campo status é alterado pelas rotinas do sistema para controle automático de bloqueio e liberação de acesso.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único do usuário.
`full_name`	VARCHAR(255)	NOT NULL	Nome completo do usuário.
`cpf`	VARCHAR(11)	NOT NULL, UNIQUE	CPF para validação e emissão de cobranças.
`email`	VARCHAR(255)	NOT NULL, UNIQUE	E-mail utilizado para autenticação e envio de notificações.
`password`	VARCHAR(255)	NOT NULL	Senha criptografada (Hash BCrypt).
`phone`	VARCHAR(20)	NOT NULL	Telefone / WhatsApp para disparo de alertas de cobrança.
`role`	VARCHAR(20)	NOT NULL	Papel no sistema: `'student'`, `'teacher'` ou `'manager'`.
`status`	VARCHAR(20)	NOT NULL, DEFAULT `'active'`	Estado atual: `'active'`, `'blocked'` ou `'inactive'`.
`created_at`	TIMESTAMP	NOT NULL	Data e hora de criação do registro.
`updated_at`	TIMESTAMP	NOT NULL	Data e hora da última atualização.

2. Tabela: `plans`

Registra os planos e pacotes oferecidos pela arena para estruturar as assinaturas dos alunos.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único do plano.
`name`	VARCHAR(255)	NOT NULL	Nome comercial do plano. ( "Mensal Arena Pass" )
`price`	DECIMAL(10,2)	NOT NULL	Valor mensal cobrado pelo plano.
`description`	TEXT	NULLABLE	Descrição detalhada dos benefícios do plano.
`created_at`	TIMESTAMP	NOT NULL	Data de cadastramento do plano.
`updated_at`	TIMESTAMP	NOT NULL	Data da última alteração das condições do plano.

3. Tabela: `student_teacher` (Tabela Pivot)

Mapeia a relação N x N entre Alunos e Professores do sistema, garantindo a regra de negócio do cadastro obrigatório de vínculo para usuários do tipo aluno.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único da vinculação.
`student_id`	BIGINT	FK (`users.id`), NOT NULL	Identificador do usuário com papel de aluno.
`teacher_id`	BIGINT	FK (`users.id`), NOT NULL	Identificador do usuário com papel de professor responsável.
`created_at`	TIMESTAMP	NOT NULL	Data e hora em que o vínculo foi estabelecido.

4. Tabela: `subscriptions`

Gerencia a vigência dos contratos dos alunos vinculados a um determinado plano.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único da assinatura.
`user_id`	BIGINT	FK (`users.id`), NOT NULL	Aluno titular do contrato.
`plan_id`	BIGINT	FK (`plans.id`), NOT NULL	Plano contratado.
`starts_at`	DATE	NOT NULL	Data de início da vigência da assinatura.
`expires_at`	DATE	NOT NULL	Data limite de acesso validado.
`is_active`	BOOLEAN	DEFAULT TRUE	Indicador de contrato ativo/vigente.
`created_at`	TIMESTAMP	NOT NULL	Data de criação da assinatura.
`updated_at`	TIMESTAMP	NOT NULL	Data de atualização do status/expiração da assinatura.

5. Tabela: `invoices`

Controla o histórico financeiro e os ciclos de faturamento. O status 'pending' combinado com o cálculo da due_date ativa o motor de notificações preventivas e o bloqueio automático de inadimplentes.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único da fatura.
`subscription_id`	BIGINT	FK (`subscriptions.id`), NOT NULL	Contrato de assinatura atrelado à cobrança.
`amount`	DECIMAL(10,2)	NOT NULL	Valor da cobrança (copiado do plano no momento da geração).
`status`	VARCHAR(20)	NOT NULL, DEFAULT `'pending'`	Situação da cobrança: `'pending'`, `'paid'`, `'overdue'` ou `'cancelled'`.
`due_date`	DATE	NOT NULL	Data de vencimento da mensalidade.
`created_at`	TIMESTAMP	NOT NULL	Data de geração da fatura no sistema.
`updated_at`	TIMESTAMP	NOT NULL	Data da última alteração de estado da fatura.

6. Tabela: `payments`

Armazena a confirmação das liquidações financeiras recebidas via callback do Webhook do gateway de pagamento ou baixa manual.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único do registro de pagamento.
`invoice_id`	BIGINT	FK (`invoices.id`), NOT NULL	Fatura quitada por este pagamento.
`method`	VARCHAR(20)	NOT NULL	Meio de pagamento utilizado: `'pix'`, `'credit_card'` ou `'debit_card'`.
`transaction_code`	VARCHAR(255)	NOT NULL, UNIQUE	Identificador/Hash da transação gerado pelo gateway.
`paid_at`	TIMESTAMP	NOT NULL	Data e hora exata da confirmação do pagamento.
`created_at`	TIMESTAMP	NOT NULL	Registro de inserção da transação no banco.

7. Tabela: `access_logs`

Registra as tentativas de acesso às instalações (catracas/reserva de quadras) via endpoint CheckAccess para fins de segurança e validação das regras de bloqueio.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único do log de acesso.
`user_id`	BIGINT	FK (`users.id`), NOT NULL	Usuário solicitando a liberação de acesso.
`granted`	BOOLEAN	NOT NULL	Resultado da verificação: `true` (liberado) ou `false` (negado).
`denial_reason`	VARCHAR(255)	NULLABLE	Motivo de impedimento (ex: `'BLOQUEADO - Inadimplência'`).
`accessed_at`	TIMESTAMP	NOT NULL	Registro exato do momento da tentativa de acesso.

8. Tabela: `user_photos`

Tabela que atende ao requisito de Galeria de Imagens (Relação 1xN), permitindo o armazenamento de múltiplos comprovantes de pagamento ou imagens do perfil do usuário.

Campo	Tipo	Restrições	Descrição
`id`	BIGINT	PK, AUTO_INCREMENT	Identificador único do arquivo/imagem.
`user_id`	BIGINT	FK (`users.id`), NOT NULL	Usuário proprietário do arquivo.
`image_path`	VARCHAR(255)	NOT NULL	Caminho ou URL de armazenamento da imagem.
`created_at`	TIMESTAMP	NOT NULL	Data e hora de upload da imagem.

2. Tipos de Campos - Utilização em Tabelas e Colunas

Campos de entrada: text, email, password, date, file

users.full_name (text / VARCHAR)
users.email (email / VARCHAR)
users.password (password / VARCHAR)
invoices.due_date (date / DATE)
subscriptions.starts_at (date / DATE)
user_photos.image_path (file / VARCHAR)

Campos de seleção: select

student_teacher.teacher_id (Seleção do professor responsável no formulário de cadastro de aluno)
payments.invoice_id (Seleção da fatura a ser quitada)

Opções múltiplas: checkbox

Preferências de notificação ou permissões do usuário (armazenadas via array/JSON no campo users.preferences ou tabela auxiliar de configurações).

Escolha única: radio

users.role (manager, teacher, student)
payments.method (pix, credit_card, debit_card)

3. Uso de Inteligência Artificial

Ferramentas Utilizadas: Gemini.
Finalidade: Auxílio na estruturação das tabelas relacionais, validação dos tipos de dados de acordo com os estados dos diagramas UML e garantia de conformidade com os padrões de nomenclatura estipulados no projeto.
Exemplos de Prompts e Resultados:
- Prompt: "Como modelar a estrutura da tabela pivot de vinculação entre alunos e professores mantendo a conformidade com as regras de nomenclatura N-N e integridade referencial?"
- Resultado: A IA sugeriu a criação da tabela student_teacher com as FKs student_id e teacher_id apontando para users.id, utilizando uma constraint de unicidade composta para evitar duplicidade de vínculos.