riseup-squad18/ARQUITETURA_DEFINITIVA.md

🎯 ARQUITETURA DEFINITIVA: SUPABASE EXTERNO vs NOSSO SUPABASE

📋 REGRA DE OURO

Supabase Externo (Fechado da Empresa): CRUD básico de appointments, doctors, patients, reports
Nosso Supabase: Features EXTRAS, KPIs, tracking, gamificação, auditoria, preferências

---

🔵 SUPABASE EXTERNO (FONTE DA VERDADE)

Tabelas que JÁ EXISTEM no Supabase Externo:

• ✅ appointments - CRUD completo de agendamentos
• ✅ doctors - Cadastro de médicos
• ✅ patients - Cadastro de pacientes
• ✅ reports - Relatórios médicos básicos
• ✅ availability (provavelmente) - Disponibilidade dos médicos
• ✅ Dados de autenticação básica

Endpoints que PUXAM DO EXTERNO:

MÓDULO 2.1 - Appointments (EXTERNO):

• /appointments/list → Puxa de lá + mescla com nossos logs
• /appointments/create → Cria LÁ + grava log aqui
• /appointments/update → Atualiza LÁ + grava log aqui
• /appointments/cancel → Cancela LÁ + notifica waitlist aqui
• /appointments/confirm → Confirma LÁ + grava log aqui
• /appointments/checkin → Atualiza LÁ + cria registro de checkin aqui
• /appointments/no-show → Marca LÁ + atualiza KPIs aqui

MÓDULO 2.2 - Availability (DEPENDE):

• /availability/list → SE existir LÁ, puxa de lá. SENÃO, cria tabela aqui
• /availability/create → Cria onde for o source of truth
• /availability/update → Atualiza onde for o source of truth
• /availability/delete → Deleta onde for o source of truth

MÓDULO 6 - Reports (EXTERNO):

• /reports/list-extended → Puxa LÁ + adiciona filtros extras
• /reports/export/pdf → Puxa dados LÁ + gera PDF aqui
• /reports/export/csv → Puxa dados LÁ + gera CSV aqui

MÓDULO 8 - Patients (EXTERNO):

• /patients/history → Puxa appointments LÁ + histórico estendido aqui
• /patients/portal → Mescla dados LÁ + teleconsulta aqui

---

🟢 NOSSO SUPABASE (FEATURES EXTRAS)

Tabelas que criamos para COMPLEMENTAR:

✅ Tracking & Auditoria:

• user_sync - Mapear external_user_id → local_user_id
• user_actions - Log de todas as ações dos usuários
• user_sessions - Sessões de login/logout
• audit_actions - Auditoria detalhada (MÓDULO 13)
• access_log - Quem acessou o quê (LGPD)
• patient_journey - Jornada do paciente

✅ Preferências & UI:

• user_preferences - Modo escuro, fonte dislexia, acessibilidade (MÓDULO 1 + 11)
• patient_preferences - Horários favoritos, comunicação (MÓDULO 8)

✅ Agenda Extras:

• availability_exceptions - Feriados, exceções (MÓDULO 2.3)
• doctor_availability - SE não existir no externo (MÓDULO 2.2)

✅ Fila & Waitlist:

• waitlist - Lista de espera (MÓDULO 3)
• virtual_queue - Fila virtual da recepção (MÓDULO 4)

✅ Notificações:

• notifications_queue - Fila de SMS/Email/WhatsApp (MÓDULO 5)
• notification_subscriptions - Opt-in/opt-out (MÓDULO 5)

✅ Analytics & KPIs:

• kpi_cache / analytics_cache - Cache de métricas (MÓDULO 10)
• doctor_stats - Ocupação, no-show %, atraso (MÓDULO 7)

✅ Gamificação:

• doctor_badges - Conquistas dos médicos (MÓDULO 7)
• patient_points - Pontos dos pacientes (gamificação)
• patient_streaks - Sequências de consultas

✅ Teleconsulta:

• teleconsult_sessions - Salas Jitsi/WebRTC (MÓDULO 9)

✅ Integridade:

• report_integrity - Hashes SHA256 anti-fraude (MÓDULO 6)

✅ Sistema:

• feature_flags - Ativar/desativar features (MÓDULO 14)
• patient_extended_history - Histórico detalhado (MÓDULO 8)

Endpoints 100% NOSSOS:

MÓDULO 1 - User Preferences:

• /user/info → Busca role e permissões AQUI
• /user/update-preferences → Salva AQUI (user_preferences)

MÓDULO 2.3 - Exceptions:

• /exceptions/list → Lista DAQUI (availability_exceptions)
• /exceptions/create → Cria AQUI
• /exceptions/delete → Deleta AQUI

MÓDULO 2.2 - Availability Slots:

• /availability/slots → Gera slots baseado em disponibilidade + exceções DAQUI

MÓDULO 3 - Waitlist:

• /waitlist/add → Adiciona AQUI
• /waitlist/list → Lista DAQUI
• /waitlist/match → Busca match AQUI
• /waitlist/remove → Remove DAQUI

MÓDULO 4 - Virtual Queue:

• /queue/list → Lista DAQUI (virtual_queue)
• /queue/checkin → Cria registro AQUI
• /queue/advance → Avança fila AQUI

MÓDULO 5 - Notifications:

• /notifications/enqueue → Enfileira AQUI (notifications_queue)
• /notifications/process → Worker processa fila DAQUI
• /notifications/confirm → Confirma AQUI
• /notifications/subscription → Gerencia AQUI (notification_subscriptions)

MÓDULO 6 - Report Integrity:

• /reports/integrity-check → Verifica hash AQUI (report_integrity)

MÓDULO 7 - Doctor Stats:

• /doctor/summary → Puxa stats DAQUI (doctor_stats) + appointments LÁ
• /doctor/occupancy → Calcula AQUI (doctor_stats)
• /doctor/delay-suggestion → Algoritmo AQUI (doctor_stats)
• /doctor/badges → Lista DAQUI (doctor_badges)

MÓDULO 8 - Patient Preferences:

• /patients/preferences → Salva/busca AQUI (patient_preferences)

MÓDULO 9 - Teleconsulta:

• /teleconsult/start → Cria sessão AQUI (teleconsult_sessions)
• /teleconsult/status → Consulta AQUI
• /teleconsult/end → Finaliza AQUI

MÓDULO 10 - Analytics:

• /analytics/summary → Puxa appointments LÁ + calcula KPIs AQUI
• /analytics/heatmap → Processa appointments LÁ + cache AQUI
• /analytics/demand-curve → Processa LÁ + cache AQUI
• /analytics/ranking-reasons → Agrega LÁ + cache AQUI
• /analytics/monthly-no-show → Filtra LÁ + cache AQUI
• /analytics/specialty-heatmap → Usa doctor_stats DAQUI
• /analytics/custom-report → Query builder sobre dados LÁ + AQUI

MÓDULO 11 - Accessibility:

• /accessibility/preferences → Salva AQUI (user_preferences)

MÓDULO 12 - LGPD:

• /privacy/request-export → Exporta dados LÁ + AQUI
• /privacy/request-delete → Anonimiza LÁ + deleta AQUI
• /privacy/access-log → Consulta AQUI (access_log)

MÓDULO 13 - Auditoria:

• /audit/log → Grava AQUI (audit_actions)
• /audit/list → Lista DAQUI (audit_actions)

MÓDULO 14 - Feature Flags:

• /flags/list → Lista DAQUI (feature_flags)
• /flags/update → Atualiza AQUI

MÓDULO 15 - System:

• /system/health-check → Verifica saúde LÁ + AQUI
• /system/cache-rebuild → Recalcula cache AQUI
• /system/cron-runner → Executa jobs AQUI

---

🔄 FLUXO DE DADOS CORRETO

Exemplo 1: Criar Appointment

1. Frontend → Edge Function /appointments/create
2. Edge Function → Supabase EXTERNO (cria appointment)
3. Edge Function → Nosso Supabase (grava user_actions log)
4. Edge Function → Nosso Supabase (enfileira notificação)
5. Retorna sucesso

Exemplo 2: Listar Appointments

1. Frontend → Edge Function /appointments/list
2. Edge Function → Supabase EXTERNO (busca appointments)
3. Edge Function → Nosso Supabase (busca logs de checkin/no-show)
4. Edge Function → Mescla dados
5. Retorna lista completa

Exemplo 3: Dashboard do Médico

1. Frontend → Edge Function /doctor/summary
2. Edge Function → Nosso Supabase (busca doctor_stats)
3. Edge Function → Supabase EXTERNO (busca appointments de hoje)
4. Edge Function → Nosso Supabase (busca badges)
5. Retorna dashboard completo

Exemplo 4: Preferências do Usuário

1. Frontend → Edge Function /user/update-preferences
2. Edge Function → Nosso Supabase APENAS (salva user_preferences)
3. Retorna sucesso

---

✅ CHECKLIST DE IMPLEMENTAÇÃO

O que DEVE usar externalRest():

• ✅ Criar/listar/atualizar/deletar appointments
• ✅ Buscar dados de doctors/patients/reports
• ✅ Atualizar status de appointments
• ✅ Buscar availability (se existir lá)

O que DEVE usar supabase (nosso):

• ✅ user_preferences, patient_preferences
• ✅ user_actions, audit_actions, access_log
• ✅ user_sync, user_sessions, patient_journey
• ✅ availability_exceptions, doctor_availability (se for nossa tabela)
• ✅ waitlist, virtual_queue
• ✅ notifications_queue, notification_subscriptions
• ✅ kpi_cache, analytics_cache, doctor_stats
• ✅ doctor_badges, patient_points, patient_streaks
• ✅ teleconsult_sessions
• ✅ report_integrity
• ✅ feature_flags
• ✅ patient_extended_history

O que DEVE mesclar (LÁ + AQUI):

• ✅ /appointments/list (appointments LÁ + logs AQUI)
• ✅ /doctor/summary (appointments LÁ + stats AQUI)
• ✅ /patients/history (appointments LÁ + extended_history AQUI)
• ✅ /patients/portal (dados LÁ + teleconsult AQUI)
• ✅ /analytics/* (dados LÁ + cache/KPIs AQUI)

---

🎯 CONCLUSÃO

SUPABASE EXTERNO = CRUD BÁSICO (appointments, doctors, patients, reports)
NOSSO SUPABASE = FEATURES EXTRAS (KPIs, tracking, gamificação, preferências, auditoria)

Todos os endpoints seguem esse padrão:

1. Lê/Escreve no Supabase Externo quando for dado base
2. Complementa com nossa DB para features extras
3. SEMPRE grava logs de auditoria em user_actions

✅ Arquitetura 100% alinhada com a especificação!