🎓 Documentação do meuAgente

O meuAgente é o hub de trabalho pessoal do Flávio: um lugar só para organizar as várias organizações em que atua, acompanhar projetos, agenda, e-mails e finanças — com um assistente de IA que lê os dados, avisa o que importa e executa ações.

Fluxo pensado para o dia a dia: entrar → bater o olho no briefing e nos alertas → saber o norte → agir (pelas telas ou falando com o assistente).

🏢 Organizações (ambientes)

Cada empresa/contexto é uma organização. Tudo no app é escopado por ela.

• O seletor no topo troca o ambiente atual (guardado na sessão). O padrão ao entrar é Grupo Orletti.
• Dentro de uma organização você só vê os dados dela (mais itens sem organização). A visão cruzada fica no Painel (ver todos).
• Cada org tem cor, logo, cargo e um tipo (Empresa ou Pessoal) que define o plano de categorias do financeiro.
• O módulo Financeiro é ligado/desligado por organização.

📁 Projetos → Etapas → Tarefas

A hierarquia de trabalho. Etapas medem o andamento; tarefas são as ações datadas.

• Projeto pertence a uma organização e pode ter um Tipo (Desenvolvimento, Implantação, Treinamento, Reimplantação) que já cria as etapas padrão.
• Etapa é a fase do projeto, exibida num quadro Kanban (A fazer / Em andamento / Bloqueada / Concluída) com arrastar e soltar.
• O % de andamento do projeto = etapas concluídas ÷ total de etapas.
• Tarefa é a ação a fazer: fica dentro de uma etapa ou é avulsa. Tem data, hora, prioridade e responsáveis.
• Tarefa com data aparece na Agenda e no Calendário; com data + hora, também pode virar evento na sua agenda do Google/Outlook.

📅 Agenda e Calendário

O que fazer hoje e nos próximos dias, com conflitos de horário.

• Ao entrar numa organização, o topo mostra a Agenda — próximos dias (atrasadas + agrupadas por dia).
• O Calendário mensal mostra as tarefas e, quando as agendas estão conectadas, também as reuniões reais do Google/Outlook (coloridas por organização).
• Ao agendar algo com hora, o assistente avisa conflitos considerando tarefas de todas as organizações e as reuniões reais.

✉️ E-mails (Gmail, Outlook e IMAP)

Lê as caixas, classifica por IA e transforma e-mail em tarefa ou lançamento financeiro.

• Cada organização pode ter várias contas: Gmail (OAuth, leitura), Outlook/Microsoft (OAuth via Graph, lê e envia) e IMAP/SMTP (qualquer provedor, lê e envia).
• A IA classifica cada e-mail (cobrança, família, compras, assinaturas, trabalho, newsletter…), gera um resumo curto e extrai o vencimento de boletos. Sem chave de IA, usa regras por palavra-chave.
• O leitor interno abre o corpo do e-mail dentro do app (Gmail, Outlook e IMAP).
• Botões: 📅 virar tarefa (vai para a agenda) e 💰 virar financeiro (cria o lançamento, com anexo).

💰 Financeiro

Contas a pagar/receber, cartões, contas bancárias, reembolsos e posição do mês.

• Habilitado por organização. As categorias mudam conforme o tipo: Empresa (Faturamento, Folha, Impostos, Ocupação…) ou Pessoal (Moradia, Mobilidade, Alimentação…), cada uma com subcategorias.
• Lançamento pode ser avulso, parcelado (gera uma linha por parcela) ou fixo/recorrente (gera mês a mês entre início e fim).
• Registra forma de pagamento, de onde saiu (conta bancária), cartão, fornecedor e anexo (nota/cupom/comprovante).
• Reembolsável: marca quem reembolsa; o valor entra em A receber e não conta como gasto seu. Ao dar baixa, lança automaticamente a receita correspondente.
• Cartões: limite, dia de fechamento e vencimento, com usado / disponível. Contas bancárias: saldo e saldo projetado (saldo − contas em aberto).
• IA no comprovante: envie a foto/PDF e ela extrai valor, data, fornecedor e categoria.
• A tela mostra a posição do mês: a pagar, pago, gasto líquido, a receber, receitas e vencidas, além do gasto por categoria.

🤖 Assistente (IA) e voz

Conversa que lê seus dados e executa ações — por texto ou por voz.

• Usa o Claude com ferramentas: ele consulta seus dados e age no banco.
• Pergunte: “quais minhas ações para hoje?”, “como estão os projetos e percentuais?”, “tenho contas vencendo?”.
• Mande fazer: “crie um projeto de Implantação na FLS com as etapas padrão”, “agende reunião amanhã às 15h” (avisa conflito e cria o evento na agenda).
• Voz: microfone (fala → texto → envia), leitura das respostas em voz alta e escuta contínua com a palavra de ativação “meuAgente”.
• Briefing do dia: ao entrar numa organização, a IA resume o seu “norte” — contas vencidas primeiro, depois tarefas, prazos e projetos travados. Fica em cache por dia.

🩺 Saúde

Acompanhamento de saúde da família: remédios, medições, exames e consultas.

• Habilitado por organização (mesmo padrão do Financeiro). Cada pessoa acompanhada é um perfil, então dá para cuidar da família toda.
• Medicamentos com horários e frequência, registro de doses tomadas/puladas, adesão dos últimos 30 dias e estoque que desconta a cada dose.
• Medições (pressão, glicemia, peso e outras) com faixas de referência: a glicemia é avaliada pelo contexto (jejum/pós-prandial) e a pressão pela pior entre sistólica e diastólica. Metas do médico substituem a faixa geral.
• Jornada de exames: envie as folhas de pedido, a IA separa exame por exame (preparo, motivo, urgência) e cada um segue a esteira pendente → agendado → realizado → resultado → analisado. Ao anexar um resultado, ele é casado automaticamente com o pedido.
• O plano mostra a sequência de idas agrupada por preparo (ex.: tudo que é em jejum no mesmo dia), o que já voltou, o que falta e o que conversar com o médico.
• Consultas viram tarefa na agenda. Há ainda registro de refeições e atividades.
• Regra de segurança: a IA explica e organiza, mas nunca diagnostica nem prescreve — essa instrução vai em todos os prompts.

💾 Backup

Cópia do banco e do código, local e no Google Drive.

• Gera dump do PostgreSQL + tar do código, com retenção e envio opcional ao Google Drive.
• Roda automaticamente no primeiro acesso do dia (desligável por BACKUP_ON_ENTRY=0) e tem tela própria em /backup.

/backup — 5 rota(s)

/chat — 3 rota(s)

/docs — 1 rota(s)

/documentos — 11 rota(s)

/emails — 12 rota(s)

/etapas — 5 rota(s)

/financeiro — 15 rota(s)

/main — 4 rota(s)

/orgs — 5 rota(s)

/people — 4 rota(s)

/project_types — 4 rota(s)

/projects — 4 rota(s)

/saude — 45 rota(s)

/tarefas — 7 rota(s)

AnaliseSaude · tabela analises_saude

Panorama gerado pela IA (cacheado por dia, igual ao Briefing).

Atividade · tabela atividades_fisicas

Exercício físico — parte do tratamento de diabetes e hipertensão.

Briefing · tabela briefings

Resumo diário (IA) por organização — o 'norte do dia'.

Cartao · tabela cartoes

Cartão de crédito — limite, fechamento e vencimento.

CategoriaDocumento · tabela categorias_documento

Uma pasta de documentos. Vira uma pasta de verdade no disco.

ChatMessage · tabela chat_messages

Histórico de conversa com o assistente (agente IA).

Condicao · tabela condicoes_saude

Condição de saúde acompanhada (ex.: Diabetes tipo 2, Hipertensão).

Consulta · tabela consultas_saude

Consulta médica — o que foi orientado é o que vira plano de ação.

ContaBancaria · tabela contas_bancarias

Conta bancária / carteira — de onde o dinheiro sai e entra.

Despesa · tabela despesas

Despesa fixa/recorrente (modelo que gera lançamentos por período).

Documento · tabela documentos

Um arquivo guardado no cofre, com o que a IA entendeu dele.

DoseRegistro · tabela doses_registro

Registro de uma dose: prevista para tal dia/hora, tomada ou pulada.

EmailAccount · tabela email_accounts

Conta de e-mail conectada a uma organização (Gmail agora, Outlook depois).

EmailMessage · tabela email_messages

E-mail sincronizado (cache local) com categoria atribuída pela IA.

Etapa · tabela etapas

Fase de um projeto (cartão do quadro Kanban).

Exame · tabela exames

Solicitação ou resultado de exame, com anexo e leitura pela IA.

ExameItem · tabela exame_itens

Um exame individual.

Lancamento · tabela lancamentos

Conta a pagar / pagamento — a unidade do financeiro.

Medicamento · tabela medicamentos

Medicamento em uso, com frequência, horários e controle de estoque.

Medicao · tabela medicoes

Um monitoramento pontual: glicemia, pressão, peso, exame laboratorial…

MetaSaude · tabela metas_saude

Meta definida com o médico (ex.: glicemia de jejum entre 80 e 130).

Organization · tabela organizations

The base class of the :attr:`.SQLAlchemy.Model` declarative model class.

PerfilSaude · tabela perfis_saude

Pessoa acompanhada (você, cônjuge, filho…). Raiz de tudo no módulo.

PerguntaSaude · tabela perguntas_saude

Pergunta que a IA faz ao paciente para fechar as lacunas do acompanhamento.

Person · tabela people

Responsável — pessoa atribuída a tarefas (e futuramente notificada por e-mail).

PlanoSaude · tabela planos_saude

Plano de acompanhamento gerado pela IA a partir das solicitações + resultados.

Project · tabela projects

The base class of the :attr:`.SQLAlchemy.Model` declarative model class.

ProjectType · tabela project_types

Tipo de projeto com etapas padrão (boas práticas, enxutas).

Refeicao · tabela refeicoes

Registro alimentar — com estimativa da IA de carboidratos, sódio etc.

Tarefa · tabela tarefas

Ação que o usuário precisa fazer, com data agendada. Pode pertencer a uma

services/agent.py

Assistente (agente IA) do meuAgente.

• generate_briefing(org)
• run_chat(history, user_message, current_org)
  history: lista de {role, content} (texto). Retorna (texto, acoes[]).

services/backup.py

Backup diário do meuAgente — banco de dados + código da aplicação.

• archive_app(dest_dir: pathlib.Path) -> pathlib.Path
  Compacta o código da aplicação (inclui o `.env`, que guarda as chaves).
• dump_database(dest_dir: pathlib.Path) -> pathlib.Path
  Grava o dump do banco em `dest_dir` e devolve o caminho do arquivo.
• last_backup() -> dict | None
  Metadados do último backup concluído (ou None se nunca rodou).
• list_backups() -> list[dict]
  Backups locais existentes, do mais recente para o mais antigo.
• maybe_daily_backup(app)
  Se ainda não houve backup hoje, dispara um em segundo plano.
• prune_old(keep=14)
  Mantém apenas os `keep` backups locais mais recentes.
• ran_today() -> bool
• run_backup(upload=True) -> dict
  Executa um backup completo. Devolve o manifest (também salvo em disco).

services/calendars.py

Camada unificada de calendários (Google Agenda + Outlook/Graph).

• contas_com_agenda(org=None)
• criar_evento(org, titulo, inicio, fim=None, descricao=None)
  Cria o evento na primeira conta com agenda da organização. Devolve (ok, mensagem/link).
• eventos(inicio, fim, org=None)
  Eventos de todas as contas (ou de uma org), já normalizados.
• eventos_do_dia(dia, org=None)
• eventos_do_mes(ano, mes, org=None)

services/classify.py

Classificação de e-mails por IA (Claude) com fallback por regras.

• classify_batch(items)
  Classifica uma lista de e-mails.

services/documentos_ai.py

IA do cofre de Documentos (Claude).

• classificar(file_bytes: bytes, media_type: str, categorias_existentes=None, contexto: str = '')
  Lê o documento e devolve o dict conforme _SCHEMA, ou None se o formato do arquivo não for suportado (não é imagem nem PDF).

services/finance_ai.py

Extração de dados de nota fiscal / cupom / comprovante via IA (Claude vision).

• extract_receipt(file_bytes: bytes, media_type: str)
  Devolve dict {valor, data, fornecedor, categoria, descricao} ou None.

services/gdrive.py

Envio dos backups para o Google Drive.

• account_email() -> str | None
  E-mail da conta conectada (para mostrar na tela).
• authorization_url()
• build_flow(state=None)
• disconnect()
• exchange_code(code, state=None, code_verifier=None)
  Troca o `code` do callback pelas credenciais e salva o token em disco.
• is_connected() -> bool
• upload_folder(folder_name: str, files: list[pathlib.Path]) -> list[dict]
  Sobe `files` para `meuAgente Backups/<folder_name>/` no Drive.

services/gmail.py

Integração com o Gmail — OAuth 2.0 (somente leitura) e busca de e-mails.

• authorization_url()
• build_flow(state=None)
• counts(account)
  Contadores rápidos: total estimado e não lidos na caixa de entrada.
• create_event(account, titulo, inicio, fim, descricao=None)
  Cria um evento na agenda principal.
• exchange_code(code, state=None, code_verifier=None)
  Troca o `code` do callback por credenciais e devolve (token_json, email).
• fetch_body(account, provider_id)
  Busca o corpo (texto) de um e-mail específico do Gmail.
• fetch_recent(account, max_results=25)
  Busca metadados dos e-mails recentes da caixa de entrada.
• list_events(account, inicio, fim)
  Eventos entre dois datetimes. Devolve lista normalizada.
• refreshed_token_json(account)
  Garante um access token válido; devolve token_json atualizado (ou o mesmo).

services/health_ai.py

IA do módulo de Saúde (Claude).

• analisar_exame(file_bytes: bytes, media_type: str, contexto: str = '')
  Lê o anexo do exame. Devolve dict conforme _EXAME_SCHEMA, ou None se o formato do arquivo não for suportado.
• analisar_refeicao(descricao: str, contexto: str = '', file_bytes: bytes = None, media_type: str = None)
  Estima nutrientes e comenta a refeição. Devolve dict conforme _REFEICAO_SCHEMA.
• gerar_panorama(dossie: str)
  Recebe o dossiê em texto e devolve dict conforme _PANORAMA_SCHEMA.
• montar_plano(dossie: str, exames_texto: str)
  Devolve o plano da jornada de exames conforme _PLANO_SCHEMA.

services/imap_mail.py

Contas de e-mail genéricas via IMAP (receber) + SMTP (enviar).

• can_send(account)
• config(account)
• fetch_body(account, provider_id)
  Busca o corpo (texto) de um e-mail específico via IMAP, pelo Message-ID.
• fetch_recent(account, max_results=50)
  Busca os e-mails recentes da INBOX (headers + flags).
• imap_cfg(account)
• make_token_json(imap, smtp=None)
• send_email(account, to_addr, subject, body)
  Envia um e-mail simples pela conta (SMTP).
• smtp_cfg(account)
• test_imap(cfg)
  Levanta exceção se não conseguir logar; devolve True se OK.
• test_smtp(cfg)

services/mailutil.py

Utilitários comuns de e-mail.

• html_to_text(html: str) -> str

services/outlook.py

Integração Microsoft/Outlook via OAuth (Microsoft Graph).

• build_auth_flow()
  Inicia o fluxo OAuth; devolve o dict do MSAL (guardar na sessão).
• create_event(account, titulo, inicio, fim, descricao=None)
• exchange_code(flow, args)
  Conclui o login. Devolve (token_json, email).
• fetch_body(account, provider_id)
• fetch_recent(account, max_results=50)
• list_events(account, inicio, fim)
  Eventos entre dois datetimes (calendarView).
• send_email(account, to_addr, subject, body)

• Testes nunca rodam no banco real: usam o PostgreSQL meuagente_test.
• As integrações degradam com elegância: sem credencial/permissão, a tela continua funcionando.
• Migrações leves rodam na subida do app (adicionam colunas sem apagar dados).
• O .env guarda as credenciais e nunca é versionado.

Guias passo a passo em docs/EMAIL_SETUP.md, docs/OUTLOOK_SETUP.md, docs/BACKUP.md e docs/ARQUITETURA.md.