Documentação do Negócio

Documentação Técnica

Visão Geral

Este projeto utiliza um banco de dados relacional PostgreSQL, estruturado com foco em controle de contas, usuários, assinaturas, produtos de dados e transações. Toda a camada de persistência é gerenciada por meio de ORM (Object Relational Mapping) com SQLAlchemy, facilitando a manipulação dos dados de forma orientada a objetos e garantindo a integridade referencial entre as tabelas.

Diagrama

Infraestrutura

• O banco de dados é hospedado na AWS utilizando o serviço Aurora PostgreSQL.
• A estrutura foi pensada para alta disponibilidade, escalabilidade e segurança de dados.

Estrutura do Banco de Dados

Tecnologias Utilizadas

Tecnologia	Descrição
PostgreSQL	Sistema gerenciador de banco de dados relacional utilizado para armazenar os dados.
SQLAlchemy	ORM (Object-Relational Mapping) usado para mapear objetos Python às tabelas do banco de dados.
Python	Linguagem base da aplicação, usada junto com SQLAlchemy para acesso ao banco.

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

Foreign Keys

• 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

Foreign Keys

• 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 pela tabela user, utilizando o atributo 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

Foreign Keys

• role_id: relacionamento com a tabela account_role, indicando o tipo da conta.

SQLAlchemy Relationships

• subscriptions: relacionamento unidirecional com a tabela subscription, listando as assinaturas associadas à conta.
• transactions: relacionamento unidirecional 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

Foreign Keys

• account_id: relacionamento com "account", utilizando o atributo account.id para associar uma subscription a uma conta.

SQLAlchemy Relationships

• account: relacionamento unidirecional com a tabela account, retornando qual conta realizou a assinatura.
• data_product: relacionamento unidirecional com a tabela data_product, retornando 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

Foreign Keys

• account_id: relacionamento com a tabela account, utilizando o atributo account.id para associar uma transação á uma conta.

SQLAlchemy Relationships

• transaction: relacionamento unidirecional com a tabela transaction, à qual o detalhe pertence.
• invoices: relacionamento unidirecional com a tabela invoice, retornando qual transação está relacionada á transação.
• details: relacionamento unidirecional com a tabela transaction_detail, retornando os detalhes da transação.

---

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

Foreign Keys

• transaction_id: relacionamento com a tabela transaction, utilizando o atributo transaction.id para associar uma transaction com transaction_detail.
• data_product_id: relacionamento com a tabela data_product, utilizando o atributo data_product.id para associar um data_product a tabela transaction_detail.

SQLAlchemy Relationships

• transaction: relacionamento bidirecional com a tabela transaction, à qual o detalhe pertence.
• data_product: relacionamento unidirecional com a tabela data_product, especificando qual produto está relacionado ao detalhe.
• subscription: relacionamento unidirecional 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

Foreign Keys

• transaction_id: relacionamento com a tabela transaction, utilizando o atributo transaction.id para associar uma transaction a tabela invoice.

SQLAlchemy Relationships

• transaction: relacionamento bidirecional com a tabela transaction, retornando 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
updated_at	String	—	NOT NULL	Data da última atualização do registro

---

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

Foreign Keys

• data_provider_id: relacionamento com a tabela data_provider, utilizando o atributo data_provider.id para associar um dataset a tabela data_provider.

SQLAlchemy Relationships

• data_product: relacionamento bidirecional de cardinalidade um para um com a tabela data_product, vinculando o dataset ao produto publicado.

---

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.

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.

---

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
updated_at	String	—	NOT NULL	Data da última atualização do registro

---

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

Foreign Keys

• dataset_id: relacionamento com a tabela dataset, utilizando o atributo dataset.id para associar um data_product a tabela dataset.

SQLAlchemy Relationships

• subscriptions: relacionamento unidirecional que lista as assinaturas atreladas ao produto de dados.
• dataset: relacionamento bidirecional de cardinalidade um para muitos com o dataset que deu origem a este produto.

---

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.

Relacionamentos

Foreign Keys

• dataset_product_id: relacionamento com a tabela dataset_product, utilizando o atributo data_set_product.id para associar um data_product_item a tabela data_set_product.
• dataset_id: relacionamento com a tabela dataset, utilizando o atributo dataset.id para associar um data_product_item a tabela dataset.

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.