Documentação do Negócio

Documentação Técnica

Visão Geral

O banco de dados foi projetado para gerenciar assinaturas de datasets e data products, garantindo rastreabilidade de transações e faturamento. Ele segue um modelo relacional estruturado para garantir consistência e escalabilidade.\

Diagrama

Estrutura do Banco de Dados

🔧 ORM Utilizado: SQLAlchemy

Neste projeto, utilizamos o SQLAlchemy como ORM (Object Relational Mapper) para facilitar a interação entre a aplicação e o banco de dados relacional, permitindo manipular dados do banco como objetos Python, reduzindo o uso de SQL cru.

🔧 Estruturas das tabelas

O banco é composto pelas seguintes tabelas principais:

User

Descrição

Armazena as informações dos usuários do sistema. Cada usuário está associado a uma conta (account) e possui um papel definido (user_role), permitindo controle de permissões e escopo.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	Gerado via UUID	Identificador único do usuário.
account_id	String	Estrangeira	ForeignKey(account.id)	Referência à conta à qual o usuário pertence.
role_id	Integer	Estrangeira	ForeignKey(user_role.id), NOT NULL	Papel (role) do usuário dentro da conta.
name	String	—	NOT NULL	Nome completo do usuário.
email	String	—	UNIQUE, NOT NULL	Email do usuário, utilizado para login e contato.
externalToken	String	—	UNIQUE, NULLABLE	Token externo de autenticação, se aplicável.
is_active	Boolean	—	DEFAULT True	Indica se o usuário está ativo no sistema.
created_at	TIMESTAMP	—	NOT NULL	Data de criação do registro.
updated_at	TIMESTAMP	—	NOT NULL	Data da última atualização do registro.

Relacionamentos

• account: relacionamento com a tabela account, representando a conta do usuário.
• role_id: relacionamento com a tabela user_role, indicando o tipo de permissão do usuário.

UserDetails

Descrição

Contém informações adicionais de perfil associadas a um usuário. Essa tabela estende os dados da tabela user, armazenando informações complementares como a imagem de perfil.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	UUID	Primária	Gerado via uuid.uuid4	Identificador único do detalhe de usuário.
user_id	String	Estrangeira	ForeignKey(user.id)	Referência ao usuário ao qual os detalhes pertencem.
profile_pic	String	—	NOT NULL	URL ou caminho da imagem de perfil do usuário.

Relacionamentos

• user_id: relacionamento com a tabela user, definindo a quem pertencem os dados complementares.

---

UserRole

Descrição

Define os diferentes papéis (roles) que um usuário pode assumir dentro do sistema. Essa tabela é usada para controle de permissões e escopo de funcionalidades.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	Integer	Primária	INDEX	Identificador único do papel.
role_name	String	—	NOT NULL	Nome do papel atribuído ao usuário.

Valores Padrão (ENUM)

• ROLE_NORMAL: Representa o papel de um usuário comum.
• ROLE_ADMIN: Representa o papel de um usuário com permissões administrativas.

Relacionamentos

• Essa tabela é referenciada por user.role_id para associar cada usuário ao seu respectivo papel.

---

Account

Descrição

Armazena os dados das contas principais do sistema, que podem representar uma empresa, organização ou grupo ao qual os usuários estão vinculados. Cada conta possui um papel definido na tabela account_role e pode possuir múltiplas transações e assinaturas.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	Gerado via UUID	Identificador único da conta.
role_id	Integer	Estrangeira	ForeignKey(account_role.id), NOT NULL	Papel da conta, definido na tabela account_role.
slug	String(50)	—	UNIQUE, NOT NULL	Identificador textual único da conta (ex: nome simplificado).
is_active	Boolean	—	DEFAULT True	Indica se a conta está ativa no sistema.
created_at	TIMESTAMP	—	NOT NULL	Data de criação do registro da conta.
updated_at	TIMESTAMP	—	NOT NULL	Data da última atualização do registro.

Relacionamentos

• role_id: relacionamento com a tabela account_role, indicando o tipo da conta.
• subscriptions: relacionamento com a tabela subscription, listando as assinaturas associadas à conta.
• transactions: relacionamento com a tabela transaction, listando as transações realizadas pela conta.

---

AccountRole

Descrição

Define os diferentes papéis que uma conta pode ter no sistema. Esses papéis são utilizados para controlar permissões, funcionalidades disponíveis e o nível de acesso de cada conta (ex: contas comuns ou administrativas).

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	Integer	Primária	INDEX	Identificador único do papel de conta.
role_name	String	—	NOT NULL	Nome descritivo do papel atribuído à conta.

Valores Padrão (Constantes Definidas no Código)

• ROLE_NORMAL: Representa uma conta comum, com permissões básicas.
• ROLE_ADMIN: Representa uma conta com permissões administrativas ampliadas.

Relacionamentos

• Essa tabela é referenciada por account.role_id para definir o papel da conta no sistema.

---

Subscription

Descrição

Registra as assinaturas de produtos de dados feitas por contas do sistema. Cada assinatura está vinculada a uma conta e a um produto específico, com informações de data de início, término e status de atividade.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	Gerado via UUID	Identificador único da assinatura.
account_id	String	Estrangeira	ForeignKey(account.id), NOT NULL	Referência à conta que realizou a assinatura.
data_product_id	String	Estrangeira	ForeignKey(data_product.id), NOT NULL	Produto de dados assinado pela conta.
start_date	DateTime	—	NOT NULL	Data de início da assinatura.
end_date	DateTime	—	NULLABLE	Data de término da assinatura (quando aplicável).
is_active	Boolean	—	DEFAULT True	Indica se a assinatura está ativa.
created_at	DateTime	—	DEFAULT func.now(), NOT NULL	Timestamp da criação da assinatura.
updated_at	DateTime	—	DEFAULT func.now(), atualizado com onupdate	Timestamp da última modificação.

Relacionamentos

• account: relacionamento com a tabela account, indicando qual conta realizou a assinatura.
• data_product: relacionamento com a tabela data_product, indicando qual produto foi assinado.

---

Transaction

Descrição

Armazena os detalhes de cada transação realizada por uma conta, vinculando produtos de dados adquiridos ou acessados e, opcionalmente, a assinatura usada no processo. Essa tabela detalha o que foi efetivamente movimentado em uma transação.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	Integer	Primária	INDEX	Identificador único do detalhe da transação.
transaction_id	String	Estrangeira	ForeignKey(transaction.id), NOT NULL	Referência à transação principal.
data_product_id	String	Estrangeira	ForeignKey(data_product.id), NOT NULL	Produto de dados relacionado ao detalhe da transação.
sub_id	String	Estrangeira	ForeignKey(subscription.id), NULLABLE	Referência à assinatura utilizada na transação (se houver).
created_at	DateTime	—	DEFAULT func.now(), NOT NULL	Data e hora da criação do registro.
updated_at	DateTime	—	DEFAULT func.now(), atualizado com onupdate	Data e hora da última atualização do registro.

Relacionamentos

• transaction: relacionamento com a tabela transaction, à qual o detalhe pertence.
• data_product: relacionamento com a tabela data_product, especificando qual produto está relacionado ao detalhe.
• subscription: relacionamento com a tabela subscription, referenciando a assinatura utilizada (se aplicável).

---

TransactionDetail

Descrição

Armazena os detalhes de cada transação realizada por uma conta, vinculando produtos de dados adquiridos ou acessados e, opcionalmente, a assinatura usada no processo. Essa tabela detalha o que foi efetivamente movimentado em uma transação.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	Integer	Primária	INDEX	Identificador único do detalhe da transação.
transaction_id	String	Estrangeira	ForeignKey(transaction.id), NOT NULL	Referência à transação principal.
data_product_id	String	Estrangeira	ForeignKey(data_product.id), NOT NULL	Produto de dados relacionado ao detalhe da transação.
sub_id	String	Estrangeira	ForeignKey(subscription.id), NULLABLE	Referência à assinatura utilizada na transação (se houver).
created_at	DateTime	—	DEFAULT func.now(), NOT NULL	Data e hora da criação do registro.
updated_at	DateTime	—	DEFAULT func.now(), atualizado com onupdate	Data e hora da última atualização do registro.

Relacionamentos

• transaction: relacionamento com a tabela transaction, à qual o detalhe pertence.
• data_product: relacionamento com a tabela data_product, especificando qual produto está relacionado ao detalhe.
• subscription: relacionamento com a tabela subscription, referenciando a assinatura utilizada (se aplicável).

---

Invoice

Descrição

Armazena as faturas geradas para cada transação. Cada fatura está vinculada a uma transação específica e contém o valor total cobrado, além dos timestamps de criação e atualização.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	Integer	Primária	INDEX	Identificador único da fatura.
transaction_id	String	Estrangeira	ForeignKey(transaction.id)	Referência à transação relacionada à fatura.
total	Numeric	—	NOT NULL	Valor total da fatura.
created_at	DateTime	—	NOT NULL	Data e hora de criação da fatura.
updated_at	DateTime	—	NOT NULL	Data e hora da última atualização da fatura.

Relacionamentos

• transaction: relacionamento com a tabela transaction, indicando a qual transação a fatura pertence.

---

Dataclient

Descrição

Armazena os dados dos clientes consumidores de produtos ou serviços de dados. Cada cliente está vinculado a uma conta no sistema e possui um código identificador único utilizado em processos de autenticação ou auditoria.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	UUID, INDEX, NOT NULL	Identificador único do cliente.
name	String	—	NOT NULL	Nome do cliente.
account_id	String	Estrangeira	ForeignKey(account.id), NOT NULL	Conta associada ao cliente.
identifying_code	String	—	NOT NULL	Código identificador único do cliente (ex: token ou hash).
created_at	String	—	NOT NULL	Data de criação do registro (⚠️ armazenado como string).
updated_at	String	—	NOT NULL	Data da última atualização do registro (⚠️ armazenado como string).

Observações

• Os campos created_at e updated_at estão como String. Idealmente, deveriam usar tipos como DateTime ou TIMESTAMP para facilitar ordenações e operações temporais.
• Essa tabela pode ser usada para rastrear quem consome os produtos de dados, inclusive para fins de auditoria, cobrança ou controle de acesso.

---

Dataset

Descrição

Armazena os conjuntos de dados fornecidos por diferentes provedores. Cada dataset pertence a um provedor de dados e está vinculado diretamente a um único produto de dados publicado no sistema.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	Gerado via UUID, NOT NULL	Identificador único do dataset.
data_provider_id	String	Estrangeira	ForeignKey(data_provider.id)	Identifica o provedor de dados responsável.
category	String	—	NOT NULL	Categoria do dataset (ex: saúde, educação, clima, etc).
is_active	Boolean	—	DEFAULT True	Indica se o dataset está ativo no sistema.
created_at	TIMESTAMP	—	NOT NULL	Data de criação do registro.
updated_at	TIMESTAMP	—	NOT NULL	Data da última atualização do registro.

Relacionamentos

• data_product: relacionamento com a tabela data_product, vinculando o dataset ao produto publicado. O uso de uselist=False indica uma relação de um para um.

---

DataSource

Descrição

Representa as fontes físicas ou virtuais de onde os dados são originados por um provedor de dados. Cada fonte contém informações de localização geográfica e está vinculada a um provedor.

⚠️ Nota: A tabela define tanto id quanto data_provider_id como chaves primárias, o que cria uma chave primária composta. Verifique se essa é realmente a intenção, pois normalmente apenas id é suficiente como chave primária única.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	Gerado via UUID, NOT NULL	Identificador único da fonte de dados.
data_provider_id	String	Primária/Estrangeira	UUID, NOT NULL	Identificador do provedor de dados (relacionamento pendente).
created_at	TIMESTAMP	—	NOT NULL	Data de criação do registro.
updated_at	TIMESTAMP	—	NOT NULL	Data da última atualização do registro.
is_active	Boolean	—	DEFAULT True	Indica se a fonte está ativa.
location	String	—	NOT NULL	Descrição do local da fonte (ex: cidade, servidor, etc.).
latitude	String	—	NOT NULL	Latitude geográfica.
longitude	String	—	NOT NULL	Longitude geográfica.

Relacionamentos

• A coluna data_provider_id deveria referenciar a tabela data_provider. O relacionamento está comentado no código, mas pode ser reativado se necessário:

  data_provider = relationship("DataProvider", back_populates="data_sources")
  
  

DataProvider

Descrição

Armazena os provedores de dados responsáveis por publicar e manter datasets na plataforma. Cada provedor está vinculado a uma conta do sistema e pode ter múltiplas fontes de dados (data sources) e datasets associados.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	UUID, INDEX, NOT NULL	Identificador único do provedor de dados.
name	String	—	NOT NULL	Nome do provedor de dados.
account_id	String	Estrangeira	ForeignKey(account.id), NOT NULL	Conta responsável pelo provedor.
created_at	String	—	NOT NULL	Data de criação do registro (⚠️ Armazenado como string).
updated_at	String	—	NOT NULL	Data da última atualização do registro (⚠️ Armazenado como string).

Observações

• Os campos created_at e updated_at estão definidos como String, mas é comum que campos de data utilizem DateTime ou TIMESTAMP. Verifique se essa decisão é proposital ou se houve um equívoco.

Relacionamentos Sugeridos

• Pode conter relacionamento com:
  • Account: a conta dona do provedor.
  • Dataset: datasets publicados por este provedor.
  • DataSource: fontes associadas ao provedor.

---

DataProduct

Descrição

Armazena os produtos de dados disponíveis na plataforma, os quais são baseados em datasets fornecidos por provedores. Cada produto contém informações detalhadas como localização, descrição, preço e está vinculado a um dataset.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	UUID, NOT NULL, DEFAULT uuid4()	Identificador único do produto de dados.
dataset_id	String	Estrangeira	ForeignKey(dataset.id), NOT NULL	Referência ao dataset que originou o produto.
location_x	Numeric	—	NOT NULL	Coordenada X da localização associada ao produto.
location_y	Numeric	—	NOT NULL	Coordenada Y da localização associada ao produto.
name	String	—	NOT NULL	Nome do produto de dados.
description	String	—	NOT NULL	Descrição detalhada do conteúdo do produto.
price	Numeric	—	NOT NULL	Preço do produto, usado nas transações.
created_at	TIMESTAMP	—	NOT NULL	Data de criação do registro.
updated_at	TIMESTAMP	—	NOT NULL	Data da última atualização do registro.

Relacionamentos

• subscriptions: lista de assinaturas atreladas ao produto de dados.
• dataset: vínculo com o dataset que deu origem a este produto (relacionamento de muitos para um).

---

DataProductItem

Descrição

Relaciona um produto de dados a múltiplos datasets, permitindo que um único data_product seja composto por diversos datasets. Serve como uma tabela de associação (join table) entre data_product e dataset.

Estrutura da Tabela

Coluna	Tipo	Chave	Restrições	Descrição
id	String	Primária	UUID, NOT NULL	Identificador único da associação entre o produto e o dataset.
data_product_id	String	Estrangeira	ForeignKey(data_product.id), NOT NULL	Produto de dados relacionado.
dataset_id	String	Estrangeira	ForeignKey(dataset.id), NOT NULL	Dataset que faz parte do produto de dados.
created_at	TIMESTAMP	—	NOT NULL	Data de criação do registro.
updated_at	TIMESTAMP	—	NOT NULL	Data da última atualização do registro.

Observações

• Esta tabela implementa uma relação muitos-para-muitos entre data_product e dataset, permitindo reuso de datasets em diferentes produtos.
• Pode ser estendida com metadados adicionais no futuro, caso necessário (por exemplo, ordem de inclusão ou tags específicas por item).

---

Regras de Integridade e Constraints

• Todas as chaves primárias são UUIDs para garantir unicidade.
• As relações entre tabelas são definidas por chaves estrangeiras (FK) para garantir a integridade referencial.
• O campo is_active é utilizado para marcar registros ativos e inativos, evitando exclusão física de dados.
• O faturamento é baseado em transações e invoices, garantindo rastreabilidade e conformidade com práticas contábeis.

Considerações Finais

O banco de dados foi estruturado para garantir flexibilidade e escalabilidade. Alteracoes futuras podem incluir:

• Auditoria de logs para rastrear ações de usuários.
• Indexação para otimização de buscas.
• Expansão do modelo de faturamento para planos diferenciados.