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.

---

Dataset

Representa um dataset disponível para assinatura, contendo metadados como origem, preço e categoria.

DataSource

Define a fonte de onde os datasets são obtidos, associando-os a provedores de dados.

DataProvider

Representa uma entidade que fornece datasets para a plataforma.

DataProduct

Define um conjunto de datasets agrupados em um produto de dados que pode ser adquirido como uma unidade.

DataProductItem

Relaciona datasets individuais a um data product, permitindo composição flexível de pacotes de dados.

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.