Pular para o conteúdo principal

Modelo de dados do MVP de e-mails

Este documento descreve a fundação de banco de dados criada para o MVP de e-mails da Secretária Virtual.

O objetivo desta camada é sustentar o fluxo futuro:

Ler e-mails
  ↓
Classificar
  ↓
Resumir
  ↓
Sugerir ação
  ↓
Sugerir resposta
  ↓
Gestor aprova
  ↓
Somente depois envia

Princípios obrigatórios​

  • A IA nunca envia e-mail sozinha.
  • O envio só poderá ocorrer em issue futura, depois de aprovação do gestor.
  • Credenciais IMAP/SMTP não podem ser gravadas em texto puro.
  • A coleta precisa evitar duplicidade de mensagens.
  • Deve existir trilha mínima de auditoria.
  • Esta etapa entrega somente banco, models, casts, índices, relacionamentos, documentação e testes mínimos.

Tabelas criadas​

email_accounts​

Armazena as contas de e-mail que futuramente serão monitoradas.

Campos principais:

id
name
email_address
provider
imap_host
imap_port
imap_encryption
imap_username
imap_password
smtp_host
smtp_port
smtp_encryption
smtp_username
smtp_password
from_name
active
last_sync_at
settings
created_at
updated_at

Regras técnicas:

  • email_address indexado.
  • active indexado.
  • imap_password e smtp_password usam cast encrypted no model.
  • imap_password e smtp_password ficam em hidden, para não aparecerem em serialização do Eloquent.
  • settings usa cast array.

email_folders​

Armazena as pastas de cada conta de e-mail.

Campos principais:

id
email_account_id
name
display_name
sync_enabled
last_uid
uid_validity
last_sync_at
created_at
updated_at

Regras técnicas:

  • email_account_id referencia email_accounts com cascadeOnDelete.
  • sync_enabled usa cast booleano.
  • last_sync_at usa cast datetime.
  • Índice único: unique(email_account_id, name).

email_messages​

Armazena os e-mails coletados futuramente pela integração IMAP.

Campos principais:

id
email_account_id
email_folder_id
folder
message_uid
message_id_header
thread_id_header
in_reply_to
references_header
from_email
from_name
to
cc
bcc
subject
body_text
body_html
snippet
has_attachments
attachments_meta
received_at
raw_headers
status
created_at
updated_at

Status iniciais:

collected
classified
pending_review
no_action
archived

Regras técnicas:

  • email_account_id referencia email_accounts com cascadeOnDelete.
  • email_folder_id referencia email_folders com nullOnDelete, pois a mensagem pode ser preservada mesmo se a pasta local for removida.
  • Índice único: unique(email_account_id, folder, message_uid).
  • Esse índice é a principal barreira contra duplicidade de e-mails coletados.
  • Campos to, cc, bcc, attachments_meta e raw_headers usam cast array.
  • has_attachments usa cast booleano.
  • received_at usa cast datetime.

email_classifications​

Armazena a classificação gerada futuramente pela IA.

Campos principais:

id
email_message_id
priority
category
requires_action
requires_reply
suggested_owner
suggested_due_label
summary
risk
confidence
model
prompt_version
raw_response
classified_at
created_at
updated_at

Regras técnicas:

  • email_message_id referencia email_messages com cascadeOnDelete.
  • Para o MVP, foi adotado relacionamento hasOne entre mensagem e classificação atual.
  • Por isso, email_message_id possui índice único em email_classifications.
  • requires_action e requires_reply usam cast booleano.
  • confidence usa cast decimal:2.
  • raw_response usa cast array.
  • classified_at usa cast datetime.

email_suggested_actions​

Armazena ações sugeridas pela IA para revisão futura do gestor.

Campos principais:

id
email_message_id
email_classification_id
action_type
title
description
suggested_owner
due_at
status
created_at
updated_at

Status iniciais:

pending
approved
rejected
done

Regras técnicas:

  • email_message_id referencia email_messages com cascadeOnDelete.
  • email_classification_id referencia email_classifications com nullOnDelete.
  • due_at usa cast datetime.
  • Esta tabela não executa ação automaticamente; ela apenas registra sugestões.

email_suggested_replies​

Armazena respostas sugeridas, editadas e aprovadas futuramente.

Campos principais:

id
email_message_id
email_classification_id
body
edited_body
status
approved_at
approved_by
sent_at
smtp_message_id
error_message
created_at
updated_at

Status iniciais:

draft
pending_review
approved
rejected
sent
send_failed

Regras técnicas:

  • email_message_id referencia email_messages com cascadeOnDelete.
  • email_classification_id referencia email_classifications com nullOnDelete.
  • approved_at e sent_at usam cast datetime.
  • sent_at, smtp_message_id e error_message são somente preparação para a Issue #17.
  • Nenhuma migration ou model envia e-mail.

assistant_audit_logs​

Armazena trilha mínima de auditoria para eventos importantes da Secretária Virtual.

Campos principais:

id
auditable_type
auditable_id
event
actor_type
actor_id
metadata
ip_address
user_agent
created_at

Regras técnicas:

  • auditable_type e auditable_id usam relacionamento polimórfico opcional.
  • actor_type e actor_id usam relacionamento polimórfico opcional.
  • metadata usa cast array.
  • created_at usa cast datetime.
  • Não possui updated_at, pois log de auditoria deve representar um evento ocorrido em determinado momento.

Relacionamentos dos models​

EmailAccount
  hasMany EmailFolder
  hasMany EmailMessage

EmailFolder
  belongsTo EmailAccount
  hasMany EmailMessage

EmailMessage
  belongsTo EmailAccount
  belongsTo EmailFolder
  hasOne EmailClassification
  hasMany EmailSuggestedAction
  hasMany EmailSuggestedReply

EmailClassification
  belongsTo EmailMessage
  hasMany EmailSuggestedAction
  hasMany EmailSuggestedReply

EmailSuggestedAction
  belongsTo EmailMessage
  belongsTo EmailClassification

EmailSuggestedReply
  belongsTo EmailMessage
  belongsTo EmailClassification

AssistantAuditLog
  morphTo auditable
  morphTo actor

Fluxo futuro por issue​

Issue #13 — fundação de banco/modelo​

Entrega:

  • Migrations.
  • Models.
  • Casts.
  • Índices.
  • Relacionamentos.
  • Testes mínimos.
  • Documentação técnica.

Fora do escopo:

  • Conexão IMAP.
  • Job de coleta.
  • Chamada de IA.
  • Telas.
  • Envio SMTP.

Issue #14 — coleta IMAP​

Deverá implementar a leitura dos e-mails, preencher email_messages e respeitar a barreira de duplicidade unique(email_account_id, folder, message_uid).

Detalhes operacionais da coleta IMAP e dos comandos da issue estão documentados em:

Issue #15 — classificação IA​

Deverá usar email_classifications, email_suggested_actions e email_suggested_replies para registrar análise, resumo, risco, ação sugerida e resposta sugerida.

Issue #16 — telas​

Deverá exibir mensagens, classificações, sugestões de ação e sugestões de resposta para revisão do gestor.

Issue #17 — envio SMTP​

Deverá enviar somente respostas aprovadas pelo gestor.

Campos preparados para essa etapa:

email_suggested_replies.approved_at
email_suggested_replies.approved_by
email_suggested_replies.sent_at
email_suggested_replies.smtp_message_id
email_suggested_replies.error_message

Cuidados de segurança​

  • Não salvar credenciais em texto puro.
  • Manter APP_KEY seguro, pois o cast encrypted depende dele.
  • Não expor imap_password e smtp_password em APIs, logs, dumps ou respostas JSON.
  • Não usar dados reais/sensíveis em testes.
  • Registrar eventos relevantes em assistant_audit_logs nas próximas issues.
  • Nunca permitir envio automático por IA sem aprovação humana explícita.

Testes mínimos esperados​

A suíte adicionada para esta issue cobre:

  • Execução das migrations.
  • Existência das tabelas principais.
  • Casts essenciais nos models.
  • Senhas IMAP/SMTP criptografadas no banco.
  • Senhas ocultas na serialização do model.
  • Relacionamento básico EmailAccount -> EmailFolder -> EmailMessage.
  • Bloqueio de duplicidade por unique(email_account_id, folder, message_uid).