Banco-de-Dados.md

@@ -11,201 +11,296 @@
 
 ![diagramabdages2](uploads/de9e741fdfa789ad6818b82dd9e586bb/diagramabdages2.png)
 
-# Visão geral
+# Visão Geral
 
-Este esquema organiza operações (missões) do MPRS e toda a informação ligada a alvos (targets): endereço, mandados, materiais apreendidos, prisões/medidas (compliance), recuperações de bens, registros do MBA Digital, reuniões e kits operacionais, além de agentes e equipes. O Target é o hub central que ancora as evidências e atos a uma Operation.
+O esquema do banco de dados organiza todas as informações envolvidas nas operações do GAECO/MPRS. Ele representa desde a operação em si, passando pelos alvos, equipes, agentes, locais, evidências, formulários e registros específicos dos módulos MBA Digital, Compliance e Recupera.
 
-# Entidades e atributos
+O **Target** é o eixo central da modelagem, conectando formulários, evidências, reuniões, equipes e demais informações necessárias para a execução das operações.
 
-# Operation
+---
 
-Função: Representa a missão/ação oficial.
-Campos-chave:
+# Entidades e Atributos
 
-id_operation (PK), name, scheduled_date, description, status (Planning|In_Progress|Completed|Cancelled).
+---
 
-Metadados jurídico-institucionais: responsible_prosecutor_office, responsible_prosecutor, pic_number, judicial_process, judicial_body, judicial_authority.
+## Operation
 
-Auditoria: created_at, updated_at.
-Índices: status, pic_number, judicial_process (aceleram consultas típicas por situação e processos).
+**Função:** Representa a operação oficial conduzida pelo GAECO.
 
-# Target
+**Campos-chave:**  
+- `id` (PK), `name`, `description`, `status`  
+- `responsible_prosecutor_office`, `responsible_prosecutor`  
+- `pic_number`, `judicial_process`, `judicial_body`, `judicial_authority`  
+- `created_at`, `updated_at`
 
-Função: Nó central: local/pessoa/objeto de interesse dentro de uma Operation.
-Campos-chave:
+---
 
-id_target (PK), id_operation (FK → Operation), id_address (FK → Address).
+## Target
 
-Identificação: name, type (MBA_Digital|Compliance|Recovery), cpf (quando pessoa).
+**Função:** Entidade central que representa o alvo da operação.
 
-Risco/ambiente: danger_level (Low|Medium|High|Critical), geolocation, environment_description, flags (has_animals, has_cameras, has_weapons).
+**Campos-chave:**  
+- `id` (PK), `id_operation` (FK), `id_location` (FK), `id_hospital` (FK)  
+- `target_number`, `scheduled_date`  
+- `name`, `cpf`, `rg`  
+- `parents`, `briefing_location`, `environment_description`  
+- `relationships`, `observations`, `warrant_url`  
+- `targeted_materials`, `mba_number`, `ended_at`  
+- `created_at`, `updated_at`
 
-Observações e auditoria: observations, created_at, updated_at.
-Índices: type, id_operation, danger_level (facilitam consultas operacionais).
+---
 
-# Address
+## Location
 
-Função: Endereço principal do Target.
-Campos-chave:
+**Função:** Endereço vinculado ao Target.
 
-id_address (PK), postal_code, number, complement, created_at, updated_at.
-Índices: postal_code (buscas por CEP).
+**Campos:**  
+- `id` (PK), `owner`, `latitude`, `longitude`  
+- `image_url`, `address`, `postal_code`, `number`, `complement`  
+- `created_at`, `updated_at`
 
-# Warrant
+---
 
-Função: Mandados vinculados ao Target.
-Campos-chave:
+## Hospital
 
-id_warrant (PK), id_target (FK → Target).
+**Função:** Instituição de saúde vinculada ao Target.
 
-type (SearchAndSeizure|Arrest|AssetRecovery), issuance_date, issuing_judge, file_pdf, created_at, updated_at.
-Índices: type (filtragem por natureza do mandado).
+**Campos:**  
+- `id` (PK), `latitude`, `longitude`, `address`  
+- `postal_code`, `number`, `complement`  
+- `created_at`, `updated_at`
 
-# SeizedMaterial
+---
 
-Função: Materiais/evidências apreendidos no contexto do Target.
-Campos-chave:
+# Formulários e Fluxos Específicos
 
-id_material (PK), id_target (FK → Target).
+---
 
-Classificação e cadeia de custódia: description, type (Electronic|Weapon|Drug|Document|Money|Other), found_location, seal_number, has_damage, access_password, evidence_image.
+## Form
 
-Auditoria: created_at, updated_at.
-Índices: type.
+**Função:** Registro base utilizado em diferentes fluxos.
 
-# Recovery
+**Campos:**  
+- `id` (PK), `id_target` (FK)  
+- `start_time`, `end_time`  
+- `entry_type`  
+- `created_at`, `updated_at`
 
-Função: Recuperação/apreensão de bens patrimoniais ligados ao Target.
-Campos-chave:
+---
 
-id_recovery (PK), id_target (FK → Target, unique).
+## MBA Form (`mba_form`)
 
-asset_type (Vehicle|RealEstate|Values|Documents), asset_description, estimated_value, asset_location, originating_process, created_at, updated_at.
-Observação: id_target com unique implica relação 1:1 (um Target tem, no máximo, um registro de Recovery).
+**Função:** Registro do módulo MBA Digital.
 
-# Compliance
+**Campos:**  
+- `id` (PK), `id_target` (FK — unique)  
+- `objective`, `additional_info`  
+- `created_at`, `updated_at`
 
-Função: Prisões/medidas cautelares relacionadas ao Target.
-Campos-chave:
+---
 
-id_compliance (PK), id_target (FK → Target, unique).
+## Compliance Form (`compliance_form`)
 
-arrest_type (Preventive|Temporary|Execution), arrest_warrant, issuance_date, issuing_judge, arrest_observations, created_at, updated_at.
-Observação: id_target unique ⇒ relação 1:1.
+**Função:** Informações de cumprimento de mandado ou medida cautelar.
 
-# MbaDigital
+**Campos:**  
+- `id` (PK), `id_target` (FK — unique)  
+- `issuance_date`, `issuing_judge`  
+- `arrest_observations`  
+- `created_at`, `updated_at`
 
-Função: Registro específico do núcleo MBA Digital referente ao Target.
-Campos-chave:
+---
 
-id_mba (PK), id_target (FK → Target, unique).
+## Recovery Form (`recovery_form`)
 
-objective, seizure_materials, additional_info, created_at, updated_at.
-Observação: id_target unique ⇒ relação 1:1.
+**Função:** Registro do módulo Recupera.
 
-# Meeting
+**Campos:**  
+- `id` (PK), `id_target` (FK — unique)  
+- `asset_type`, `asset_description`  
+- `estimated_value`, `asset_location`  
+- `originating_process`  
+- `created_at`, `updated_at`
 
-Função: Reuniões/briefings de campo associados ao Target.
-Campos-chave:
+---
 
-id_meeting (PK), id_target (FK → Target), location, date, time, created_at, updated_at.
-Cardinalidade: 1:N (muitos Meetings por Target).
+# Materiais e Apreensões
 
-# OperationalKit
+---
 
-Função: Kit/itens operacionais destinados a um Target e sob responsabilidade de um Agente.
-Campos-chave:
+## Seized Material (`seized_material`)
 
-id_kit (PK), id_target (FK → Target), responsible_agent_id (FK → Agent), materials, created_at, updated_at.
-Cardinalidade: N:1 para Target (vários kits por Target) e N:1 para Agent (um agente pode responder por vários kits).
+**Função:** Materiais apreendidos durante a operação.
 
-# Agent
+**Campos:**  
+- `id` (PK), `id_target` (FK)  
+- `description`, `type`, `found_location`  
+- `seal_number`, `image_url`  
+- `created_at`, `updated_at`
 
-Função: Usuários operacionais (polícia, MP, técnico, suporte).
-Campos-chave:
+---
 
-id_agent (PK), name, email (unique), password_hash, role, institution, unit, id_number (RG), id_type (CPF|RG|ID_POLICIAL), cpf (unique), phone, access_level (Administrator|Operator|Viewer), created_at, updated_at.
-Índices: cpf, email.
-Segurança: senha armazenada em password_hash (boa prática para autenticação).
+## Seized Drug (`seized_drug`)
 
-# Team
+**Função:** Registro de substâncias apreendidas.
 
-Função: Grupos formais de atuação.
-Campos-chave:
+**Campos:**  
+- `id` (PK), `id_target` (FK)  
+- `drug_type`, `amount`
 
-id_team (PK), name, type (Prosecutor|Police|Technical|Support), leader_id (FK → Agent), member_id (FK → Agent), created_at, updated_at.
-Índices: type.
-Observação de modelagem: o par leader_id/member_id permite apenas um membro por registro. Para múltiplos membros por equipe, o recomendado é normalizar com uma tabela de associação TeamMember (id_team, id_agent, role_na_equipe).
+---
 
-# Relacionamentos (cardinalidades e chaves)
+## Seized Money (`seized_money`)
 
-Operation (1) — (N) Target
-Target.id_operation → Operation.id_operation.
+**Função:** Valores apreendidos.
 
-Address (1) — (N) Target
-Target.id_address → Address.id_address.
+**Campos:**  
+- `id` (PK), `id_target` (FK)  
+- `currency`, `amount`
 
-Target (1) — (N) Warrant, SeizedMaterial, Meeting, OperationalKit
-Cada uma possui id_target como FK para Target.id_target.
+---
 
-Target (1) — (1) MbaDigital, Compliance, Recovery
-id_target unique em cada uma ⇒ 1:1 (no máximo um registro por Target em cada domínio).
+# Agentes e Equipes
 
-Agent (1) — (N) OperationalKit
-OperationalKit.responsible_agent_id → Agent.id_agent.
+---
 
-Agent (1) — (N) Team (líder e/ou membro)
-Team.leader_id → Agent.id_agent; Team.member_id → Agent.id_agent.
-(Para multi-membros por equipe, usar tabela de associação.)
+## Agent
 
-# Documentação Complementar da Arquitetura de Dados
+**Função:** Representa usuários operacionais.
+
+**Campos:**  
+- `id` (PK), `name`, `occupation`, `role`  
+- `institution`, `unit`  
+- `rg`, `cpf`, `phone`, `password`  
+- `created_at`, `updated_at`
+
+---
+
+## Team
+
+**Função:** Equipe associada a um Target.
 
-# Escolha do PostgreSQL
+**Campos:**  
+- `id` (PK), `id_target` (FK), `leader_id` (FK → Agent)  
+- `created_at`, `updated_at`
 
-O PostgreSQL foi adotado como SGBD por ser uma solução open source, madura e estável, amplamente utilizada em ambientes corporativos e de missão crítica. Os principais fatores para a escolha foram:
+---
 
-Confiabilidade e integridade transacional (ACID), fundamentais para preservar a cadeia de custódia dos dados judiciais e operacionais.
+## Team Agent (`team_agent`)
 
-Tipos de dados avançados (JSONB, arrays, enums) que se encaixam bem em atributos como descrições de materiais, metadados e ambientes de risco.
+**Função:** Tabela associativa que relaciona Agentes com Equipes.
 
-Escalabilidade e extensões (como PostGIS, pgcrypto, unaccent) que permitem expandir a solução conforme novas necessidades (geolocalização, criptografia, buscas).
+**Campos:**  
+- `id` (PK), `id_team` (FK), `id_agent` (FK)
 
-Compatibilidade nativa com ferramentas ORM (Hibernate/JPA) e com ecossistema de containers (Docker/Kubernetes).
+---
 
-# Escolha do DBeaver
+# Reuniões
 
-O DBeaver foi selecionado como ferramenta de cliente/gerenciamento de banco por ser multiplataforma, livre e compatível com PostgreSQL. Ele atende tanto desenvolvedores quanto analistas funcionais:
+---
 
-Interface gráfica intuitiva para navegação, consultas SQL e modelagem de diagramas ER.
+## Meeting
 
-Recursos de produtividade como geração de diagramas, importação/exportação de dados em diversos formatos, visualização de índices e constraints.
+**Função:** Reuniões e briefings operacionais.
 
-Segurança: suporte a conexões com SSL/TLS e criptografia local de credenciais.
+**Campos:**  
+- `id` (PK), `id_target` (FK)  
+- `location`, `scheduled_date`  
+- `created_at`, `updated_at`
 
-Integração fluida com versionamento: permite executar scripts controlados pelo time diretamente do repositório.
+---
 
-# Dockerização do Banco
+# Controle de Permissões
 
-O banco foi containerizado via Docker Compose, garantindo reprodutibilidade do ambiente e simplificação do ciclo de vida (subida, atualização, destruição). Os principais pontos de configuração são:
+---
 
-Persistência de dados via volumes Docker, para manter o estado entre execuções.
+## Role
 
-Inicialização automatizada: scripts SQL/SH no diretório docker-entrypoint-initdb.d podem criar extensões, usuários e dados iniciais.
+**Função:** Papel do usuário.
 
-Isolamento e rede interna: comunicação segura entre containers de aplicação e banco sem expor portas desnecessárias.
+**Campos:**  
+- `id` (PK), `title`, `description`
 
-Portabilidade: qualquer desenvolvedor pode subir o ambiente localmente ou em um servidor de teste com o mesmo arquivo Compose.
+---
 
-# Integração com Hibernate (ORM)
+## Permission
 
-O Hibernate/JPA foi escolhido como camada ORM para reduzir o atrito entre o modelo relacional e a camada de objetos da aplicação Java:
+**Função:** Ação autorizável no sistema.
 
-Mapeamento natural: o esquema reflete diretamente nas entidades do domínio (Operation, Target, Warrant, etc.), com relacionamentos 1:1 e 1:N respeitando as constraints (UNIQUE, FK).
+**Campos:**  
+- `id` (PK), `title`, `description`
 
-Portabilidade e abstração: queries podem ser escritas em JPQL ou Criteria API, mantendo o código desacoplado de SQL específico.
+---
+
+## Role Permissions (`role_permissions`)
+
+**Função:** Tabela associativa entre papéis e permissões.
+
+**Campos:**  
+- `id_role` (FK), `id_permission` (FK)
+
+---
+
+# Relacionamentos
+
+* Operation (1) — (N) Target
+* Location (1) — (N) Target
+* Hospital (1) — (N) Target
+
+* Target (1) — (N) seized_material
+* Target (1) — (N) seized_drug
+* Target (1) — (N) seized_money
+* Target (1) — (N) meeting
+
+* Target (1) — (1) mba_form
+* Target (1) — (1) compliance_form
+* Target (1) — (1) recovery_form
+
+* Team (1) — (N) team_agent
+* Agent (1) — (N) team_agent
+
+# Documentação Complementar da Arquitetura de Dados
+
+---
+
+## Escolha do PostgreSQL
+
+O PostgreSQL foi adotado devido à sua confiabilidade, suporte ACID e robustez em cenários de missão crítica. Entre os benefícios:
+
+- integridade transacional  
+- tipos avançados: JSONB, enums, arrays  
+- extensões úteis: PostGIS, pgcrypto  
+- compatibilidade com Hibernate e Docker  
+
+---
+
+## Escolha do DBeaver
+
+Ferramenta de gerenciamento utilizada durante o desenvolvimento:
+
+- interface intuitiva  
+- geração de diagramas ER  
+- execução de scripts SQL  
+- importação/exportação de dados  
+- suporte a SSL e armazenamento seguro de credenciais  
+
+---
+
+## Dockerização do Banco
+
+- volumes garantem persistência  
+- containers isolam comunicação  
+- scripts de inicialização automatizam setup  
+- permite reprodutibilidade entre máquinas  
+
+---
 
-Validação do schema: em produção, a aplicação é configurada para validar (ddl-auto=validate) a consistência entre modelo e banco.
+## Integração com Hibernate (ORM)
 
-Escalabilidade: Hibernate permite configurações de lazy loading, cache de segundo nível e batching para lidar com grandes volumes de dados operacionais.
+Benefícios da adoção do Hibernate/JPA:
 
-Migrações controladas: uso de ferramentas como Flyway ou Liquibase integra com Hibernate, garantindo versionamento e controle de mudanças estruturais.
+- mapeamento direto das entidades  
\ No newline at end of file
+- queries com JPQL e Criteria API  
+- validação do schema  
+- suporte a lazy loading e batching  
+- integração com ferramentas de migração (Flyway/Liquibase)