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!**