Visão Geral do Banco de Dados (KeepUnB)¶

Este documento descreve a arquitetura, o modelo de dados físico e as diretrizes de governança para o banco de dados relacional (PostgreSQL 16+) do sistema KeepUnB, mapeado através do ORM SQLAlchemy 2.x e gerenciado via Alembic.

1. Diagrama Entidade-Relacionamento (ERD)¶

Abaixo está a representação visual da modelagem física inicial do banco de dados, mostrando as relações e chaves estrangeiras entre a tabela de usuários (users) e a tabela de chamados/solicitações de manutenção (tickets).

erDiagram
    users {
        VARCHAR(9) matricula PK "Matrícula do usuário (UnB)"
        VARCHAR(100) nome "Nome completo"
        VARCHAR(150) email UK "E-mail acadêmico/institucional"
        VARCHAR(255) senha_hash "Senha criptografada (bcrypt)"
        userrole role "Perfil de acesso (ENUM)"
        BOOLEAN ativo "Indicador de conta ativa"
        TIMESTAMP created_at "Data de criação do registro"
        TIMESTAMP updated_at "Data da última atualização"
    }

    tickets {
        INTEGER id PK "ID sequencial autoincrementado"
        VARCHAR(200) local "Local da manutenção (ex: FCTE, Lab)"
        VARCHAR(100) tipo_manutencao "Categoria de serviço (ex: Elétrica)"
        TEXT descricao "Descrição detalhada do problema"
        ticketstatus status "Estado do chamado (ENUM)"
        VARCHAR(9) solicitante_id FK "FK apontando para users.matricula"
        VARCHAR(9) tecnico_id FK "FK apontando para users.matricula (Nullable)"
        TIMESTAMP created_at "Data de abertura do chamado"
        TIMESTAMP updated_at "Data da última alteração"
    }

    users ||--o{ tickets : "solicita (solicitante_id)"
    users ||--o{ tickets : "executa (tecnico_id)"

2. Dicionário de Dados¶

2.1 Tabela `users`¶

Armazena as credenciais, perfis de acesso e dados cadastrais dos quatro tipos de usuários atendidos pela plataforma KeepUnB.

Nome da Coluna	Tipo de Dado	Restrições	Padrão (Default)	Descrição
`matricula`	`VARCHAR(9)`	`PRIMARY KEY`, `CHECK`	Nenhum	Matrícula acadêmica do usuário (estudante/servidor). Deve possuir exatamente 9 dígitos numéricos.
`nome`	`VARCHAR(100)`	`NOT NULL`	Nenhum	Nome completo do usuário.
`email`	`VARCHAR(150)`	`UNIQUE`, `NOT NULL`, `INDEX`	Nenhum	Endereço de e-mail institucional/pessoal (chave de login alternativa).
`senha_hash`	`VARCHAR(255)`	`NOT NULL`	Nenhum	Hash seguro da senha gerado utilizando o algoritmo bcrypt.
`role`	`userrole` (ENUM)	`NOT NULL`	`'SOLICITANTE'`	Perfil de permissão e privilégios de acesso do usuário no sistema.
`ativo`	`BOOLEAN`	`NOT NULL`	`true`	Define se a conta está ativa e com permissão para realizar login.
`created_at`	`TIMESTAMP WITH TIME ZONE`	`NOT NULL`	`now()`	Registro de data/hora em que a conta do usuário foi cadastrada.
`updated_at`	`TIMESTAMP WITH TIME ZONE`	`NOT NULL`	`now()`	Registro de data/hora da última alteração no cadastro do usuário.

[!NOTE] A constraint de validação ck_users_matricula_9_digitos assegura via banco que o valor inserido na coluna matricula satisfaz a expressão regular ^[0-9]{9}$.

2.2 Tabela `tickets`¶

Centraliza as solicitações de manutenção de infraestrutura abertas pela comunidade acadêmica e monitoradas pelos técnicos e gerentes.

Nome da Coluna	Tipo de Dado	Restrições	Padrão (Default)	Descrição
`id`	`INTEGER`	`PRIMARY KEY`, `INDEX`, `AUTOINCREMENT`	Nenhum	ID autoincrementado gerado sequencialmente pelo PostgreSQL para identificação única do ticket.
`local`	`VARCHAR(200)`	`NOT NULL`	Nenhum	Espaço físico ou sala onde a manutenção é necessária (ex: "FCTE - Bloco A - Sala A1-12").
`tipo_manutencao`	`VARCHAR(100)`	`NOT NULL`	Nenhum	Categoria ou especialidade do reparo solicitado (ex: "Elétrica", "Hidráulica", "Ar condicionado").
`descricao`	`TEXT`	`NOT NULL`	Nenhum	Texto detalhado enviado pelo solicitante relatando a anomalia ou problema.
`status`	`ticketstatus` (ENUM)	`NOT NULL`	`'ABERTO'`	Status do ciclo de vida em que o chamado se encontra.
`solicitante_id`	`VARCHAR(9)`	`FOREIGN KEY` (`users.matricula`), `NOT NULL`	Nenhum	Matrícula do usuário solicitante (autor da abertura do ticket).
`tecnico_id`	`VARCHAR(9)`	`FOREIGN KEY` (`users.matricula`), `NULLABLE`	`NULL`	Matrícula do técnico encarregado de executar a manutenção (atribuído pelo gerente ou capturado pela fila).
`created_at`	`TIMESTAMP WITH TIME ZONE`	`NOT NULL`	`now()`	Registro de data/hora em que o chamado de manutenção foi formalizado.
`updated_at`	`TIMESTAMP WITH TIME ZONE`	`NOT NULL`	`now()`	Registro de data/hora da última alteração no ciclo de vida ou detalhes do chamado.

[!IMPORTANT] As chaves estrangeiras (FK) nesta tabela seguem rigidamente a convenção do projeto de serem explicitamente nomeadas no banco de dados como: - fk_tickets_solicitante_users apontando para users.matricula. - fk_tickets_tecnico_users apontando para users.matricula.

3. Tipos Customizados (ENUMs)¶

Para garantir consistência e integridade referencial nas regras de negócios, o PostgreSQL gerencia dois tipo estruturados de ENUMs:

3.1 `userrole`¶

Especifica o nível de autorização e o escopo de atuação do usuário dentro do ecossistema: - SOLICITANTE: Alunos, professores ou servidores. Podem abrir chamados, acompanhar suas próprias solicitações e avaliá-las após a conclusão. - TECNICO: Profissionais da manutenção encarregados de realizar o serviço de reparo, movimentar o status dos chamados atribuídos e listar a fila pendente. - GERENTE: Administradores operacionais com poder de visualização global, delegação/atribuição de chamados para técnicos e emissão de relatórios de SLA. - ADMIN: Administradores técnicos focados no gerenciamento de contas, perfis de segurança e parâmetros transversais do sistema.

3.2 `ticketstatus`¶

Define as etapas sequenciais do fluxo de trabalho e atendimento das demandas de infraestrutura: - ABERTO: Chamado recém-criado pelo solicitante, aguardando triagem ou atribuição de responsável. - ATRIBUIDO: Técnico associado pelo gerente ou auto-atribuído, aguardando início da execução prática. - EM_ANDAMENTO: O técnico iniciou ativamente as tarefas de reparação física no local indicado. - CONCLUIDO: Manutenção executada e finalizada com sucesso. O chamado é movido para etapa de avaliação. - CANCELADO: Chamado arquivado por duplicidade, erro de dados ou solicitação do autor antes da execução. - NAO_INICIADO: Estado neutro/histórico para chamados que aguardam agendamento prévio ou liberação de insumos.

4. Políticas e Diretrizes de Governança¶

Conforme especificado no manual do projeto (PROJECT_GUIDELINES.md), o time de desenvolvimento deve seguir as regras de governança abaixo ao evoluir o banco de dados:

Vedada Edição de Migrações Antigas: Migrações que já foram integradas à branch de produção (main/developer) nunca devem ser reeditadas. Havendo necessidade de alterações, crie uma nova migration incremental.
Migrations Estritamente Manuais: Evite o uso indiscriminado do parâmetro --autogenerate do Alembic. As migrações devem ser refinadas manualmente para garantir scripts limpos, legíveis e com rollback (downgrade) funcional completo.
Ambiente Isolado no Docker: Toda execução de migração (alembic upgrade head) ou manipulação do banco deve ser feita de dentro do container Docker para evitar disparidades de ambiente no host local.
Convenções de Chaves:
Nomear tabelas no plural e em snake_case.
Chaves primárias (PK) simples devem chamar-se id (ou matricula se for chave natural de negócio).
Chaves estrangeiras (FK) devem ser nomeadas com a máscara fk_<tabela_origem>_<tabela_destino>.

5. Guia de Migrações (Alembic)¶

Para manter a consistência do banco de dados no ecossistema de desenvolvimento, siga este guia de referência rápida para executar as tarefas do Alembic.

5.1 Regras de Ouro¶

Convenção de Nomes de Arquivos: Sempre renomeie o arquivo gerado para seguir o formato {YYYY_MM_DD}_{descricao_snake_case}.py (ex: 2026_05_28_criar_tabelas_iniciais.py), removendo o hash aleatório gerado pelo Alembic na frente do arquivo físico.
Resiliência do Up/Down: O script de migração deve ser capaz de aplicar e reverter perfeitamente. Certifique-se de que os tipos PostgreSQL personalizados (como ENUM) sejam criados explicitamente usando postgresql.ENUM(..., create_type=False) e removidos no downgrade com postgresql.ENUM(name='...').drop(op.get_bind(), checkfirst=True).
Testar Rollback Localmente: Antes de submeter qualquer Pull Request, sempre execute alembic downgrade -1 localmente e verifique se o banco de dados retorna ao estado íntegro anterior sem dar erros.

5.2 Comandos Padrão (Executados via Docker)¶

Sempre rode os comandos do Alembic utilizando o ambiente encapsulado do Docker Compose para assegurar que as dependências Python, drivers de rede assíncronos e dialetos de banco sejam consistentes com o banco de produção:

# 1. Criar nova migration (Manual - sem autogenerate)
docker compose run --rm backend alembic revision -m "2026_05_22_criar_tabela_solicitacoes"

# 2. Aplicar migrations pendentes
docker compose run --rm backend alembic upgrade head

# 3. Reverter a última migração aplicada (Teste de Rollback)
docker compose run --rm backend alembic downgrade -1

# 4. Reverter todas as migrações aplicadas (Retornar ao baseline limpo)
docker compose run --rm backend alembic downgrade base

# 5. Listar histórico de migrações
docker compose run --rm backend alembic history

[!WARNING] Após criar uma nova migração a partir do Docker no Linux, o arquivo criado no host local pertencerá ao usuário root. Lembre-se de rodar o comando abaixo na raiz do projeto para restabelecer as permissões de edição para o seu usuário do sistema: docker compose run --rm backend chown -R 1000:1000 /app/migrations