0015 — Migração de Plataformas (Onboarding Premium Híbrido)

Status

Accepted · 2026-04-26 · Autor: Alexandre + Claude. Decisão delegada à recomendação Claude pela experiência em SaaS.

Contexto

Público primário do ClinicGestor: clínicas SEM sistema atual (clientes diretos dos consultores parceiros). Mas público secundário (importante): clínicas COM sistema concorrente que precisam migrar.

Sem estratégia de migração, plataforma fica refém de “clínicas novas” (mercado limitado). Com estratégia robusta, clínicas insatisfeitas com iClinic/Doctoralia/ProDoctor migram.

Decisão

1. Princípio: migração não é blocker; é multiplicador

Lança em F1 com mínimo viável (CSV genérico). Evolui conforme demanda real.

2. Onboarding paralelo (zero espera) — diferencial central

Princípio: clínica que assina plano recebe acesso imediato à plataforma com dados em branco. Pode atender novo paciente em 1h. Migração de dados antigos roda em paralelo (1-4 semanas).

Razão: principal medo do migrante é “preciso esperar tudo migrar antes de poder usar”. Eliminar esse medo é diferencial vs concorrentes que dizem “ative em 30 dias”.

Implementação: provisão (ADR 0006 §8) cria clínica vazia. Migração é processo separado iniciado depois, sem bloquear uso.

3. Faseamento

F1 (Sprint 7, ~1 semana) — Importador CSV genérico:

Edge functions: start-data-migration, validate-csv-import, execute-csv-import, rollback-data-migration
Wizard: clínica escolhe sistema fonte → upload CSV → mapeia campos → preview → confirma → import
Suporte assistido manual: Alexandre executa primeiros casos via SQL Editor + scripts customizados quando volume permite
Páginas SEO de migração desde Sprint 0 (/migrar, /migrar/iclinic, etc — landing pages)

F1.5 (Sprint 11, ~2-3 semanas) — Importadores específicos:

import-from-iclinic (parser XLS proprietário)
import-from-doctoralia (CSV/XLS específico)
import-from-prodoctor
export-clinic-data-reverse-migration (LGPD + diferencial ético)

F2 (Sprint 14, ~1.5 semanas) — White-Glove Migration:

Serviço pago (R$ 1.500-3.000 one-time)
Time de Migration Specialists (1-2 pessoas contratadas conforme volume)
Treinamento via call de 2h
Acompanhamento dedicado por 30 dias
Dashboard de “saúde” da migração

F2.5+ (escala) — Importadores customizados por demanda real (Vitale, Memed, etc).

4. Concorrentes prioritários BR

Top 3 com importadores específicos:

iClinic (~30k clínicas)
Doctoralia / DoctoraliaPro (~20k)
ProDoctor (~15k)

Outros via CSV genérico ou demanda real (Vitale, Memed, ProMed, Tasy, MV).

5. Modelo de cobrança híbrido

Migração simples (CSV genérico, ≤ 500 pacientes, ≤ 1.000 agendamentos): incluso no plano R$ 700/mês. Zero atrito comercial.
Migração complexa (volume alto, prontuário eletrônico, treinamento): paga à parte (R$ 1.500-3.000 one-time) = White-Glove Migration.

6. Escopo de dados priorizado

Prioridade	Tipo de dado	Quando entra
P0	Pacientes (cadastro básico)	F1 (CSV)
P0	Agenda futura (próximos 30-60 dias)	F1
P1	Histórico de consultas anteriores	F1
P1	Financeiro (cobranças, recebimentos)	F1.5
P2	Prontuário eletrônico	F2 (NLP pra extrair de formato livre)
P2	Exames laboratoriais anexos	F2
P3	Imagens médicas (raio-x, eco)	F3+ (volume + privacidade)
P3	Comunicação histórica (mensagens)	F3+

7. Schema implicado (entra em F1)

-- Migrações em andamento
CREATE TABLE public.clinic_data_migrations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  clinic_id UUID NOT NULL REFERENCES public.clinics(id) ON DELETE CASCADE,
  source_system TEXT NOT NULL CHECK (source_system IN (
    'iclinic', 'doctoralia', 'doctoralia_pro', 'prodoctor',
    'vitale', 'memed', 'csv_generic', 'manual_entry', 'other'
  )),
  source_system_other_name TEXT,
  status TEXT NOT NULL DEFAULT 'planned' CHECK (status IN (
    'planned', 'in_progress', 'completed_success', 'completed_partial',
    'failed', 'rolled_back', 'cancelled'
  )),
  scope TEXT[] NOT NULL DEFAULT '{patients}',  -- ['patients', 'appointments', 'consultations', 'financial']
  scope_summary JSONB,                          -- { patients: { expected: 500, imported: 487, failed: 13 } }
  scheduled_at TIMESTAMPTZ,
  started_at TIMESTAMPTZ,
  completed_at TIMESTAMPTZ,
  is_premium BOOLEAN DEFAULT FALSE,             -- White-Glove Migration?
  premium_amount_brl_cents INT,
  premium_payment_status TEXT CHECK (premium_payment_status IN ('pending', 'paid', 'refunded')),
  rollback_snapshot_storage_path TEXT,
  rollback_executed_at TIMESTAMPTZ,
  notes TEXT,
  assigned_specialist_user_id UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Logs de eventos
CREATE TABLE public.clinic_data_migration_logs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  migration_id UUID NOT NULL REFERENCES public.clinic_data_migrations(id) ON DELETE CASCADE,
  event_at TIMESTAMPTZ DEFAULT NOW(),
  event_kind TEXT CHECK (event_kind IN (
    'migration_planned', 'file_uploaded', 'mapping_validated',
    'dry_run_executed', 'import_started', 'records_imported',
    'records_failed', 'import_completed', 'rollback_started',
    'rollback_completed', 'specialist_assigned', 'support_message'
  )),
  event_data JSONB,
  user_id UUID REFERENCES auth.users(id)
);

-- Mapeamentos por concorrente (templates pré-cadastrados em seed)
CREATE TABLE public.clinic_data_migration_mappings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  source_system TEXT NOT NULL,                  -- ex: 'iclinic'
  source_field TEXT NOT NULL,                   -- ex: 'paciente_nome'
  target_table TEXT NOT NULL,                   -- ex: 'patients'
  target_field TEXT NOT NULL,                   -- ex: 'full_name'
  transformation_function TEXT,                 -- ex: 'normalize_brazilian_phone'
  is_required BOOLEAN DEFAULT FALSE,
  default_value TEXT,
  active BOOLEAN DEFAULT TRUE
);

Seed (em 15-seeds.sql): templates de mapping pra iClinic, Doctoralia, ProDoctor.

8. Edge functions

Edge function	Fase	Responsabilidade
`start-data-migration`	F1	Cria registro + storage path pra upload
`validate-csv-import`	F1	Valida CSV uploaded; retorna preview + erros
`execute-csv-import`	F1	Executa import: parseia, aplica mapping, insere, registra logs
`rollback-data-migration`	F1	Reverte migração via snapshot
`import-from-iclinic`	F1.5	Parser específico iClinic
`import-from-doctoralia`	F1.5	Parser Doctoralia
`import-from-prodoctor`	F1.5	Parser ProDoctor
`export-clinic-data-reverse-migration`	F1.5	Cliente que sai exporta CSV+JSON padronizado

9. Telas

Pra clínica (/clinic/migracao/*):

dashboard.md — status atual + histórico
nova.md — wizard: escolher sistema fonte → upload CSV → mapeamento → preview → confirmar
detalhe.md — detalhe + logs + rollback (se elegível)

Pra platform_admin (/platform/migracoes/*):

fila-acompanhamento.md — todas migrações em curso + alertas
specialist-assignments.md (F1.5+) — atribuição de Migration Specialists
templates-mapeamento.md — gestão de mappings por concorrente

Públicas (SEO):

/migrar — landing geral
/migrar/iclinic — guia “Como migrar do iClinic pra ClinicGestor”
/migrar/doctoralia
/migrar/prodoctor
/migrar/vitale
/migrar/outros — guia genérico CSV

10. SEO desde Sprint 0

Landing pages publicadas em clinicgestor.com/migrar/<concorrente> desde o lançamento. Estratégia de aquisição zero-custo:

Visitor lendo “como migrar do iClinic” já está pronto pra trocar (alta conversão)
Captura busca orgânica (~5k-10k/mês entre os 5 concorrentes)
CTAs claros: “Quer ajuda pra migrar? Fale com a gente” → conversão pra trial

11. Reverse migration (LGPD + ética)

Cliente que decide sair (cancela plano) tem direito a export completo dos dados em CSV+JSON padronizado em ≤ 7 dias.

Edge function export-clinic-data-reverse-migration (F1.5):

Recebe clinic_id + auth check (clinic_owner OU consultancy_owner OU platform_admin)
Gera export em background (job pode levar minutos pra clínica grande)
Quando pronto, envia email com link signed URL (Supabase Storage privado)
Link expira em 7 dias após geração
Logs em clinic_data_migration_logs com event_kind=‘reverse_export’

Razão:

LGPD — direito do titular ao seu dado (Art. 18 LGPD)
Boa prática — clientes que sabem que podem sair fácil ficam mais
Diferencial ético defensável — concorrentes tornam saída difícil; ClinicGestor não

12. Independência de outros silos

Migração mantém-se INDEPENDENTE de:

Programa Acolhe — silos separados
Marketplace — silos separados
Pacotes Avulsos — silos separados

Razão: cada um tem propósito distinto. Acoplá-los dilui e complica.

13. Consultor parceiro pode revender migration assistance (F2)

Consultor pode oferecer “Eu cuido da migração da sua clínica” como serviço adicional dele:

Revenue share opcional configurável por consultor
Migração executada pela equipe da plataforma (Migration Specialists)
Consultor cobra cliente; plataforma cobra consultor

(F2+ — não bloqueia F1.)

Consequências

Positivas

Onboarding paralelo elimina principal medo do migrante (zero espera)
CSV genérico cobre 80% dos casos — importadores específicos são polish
SEO de migração é aquisição barata + alta conversão
Reverse migration é diferencial ético vs concorrentes
White-Glove Migration vira receita extra premium

Negativas

Importadores específicos demandam manutenção (formato proprietário muda)
Migration Specialists = custo operacional crescente

Riscos

Migração mal-feita corrompe dados da clínica recém-migrada
- Mitigação: snapshot pré-import + rollback fácil; validate-csv-import força dry-run antes
Cliente reclama que “perdeu dados na migração” (sem perdeu)
- Mitigação: clinic_data_migration_logs + ata detalhado; comunicação clara durante processo

Alternativas consideradas

1. Sem importadores específicos (apenas CSV genérico)

Prós: simplicidade; cobre 80%
Contras: clínicas com volume alto preferem upload de XLS direto do iClinic vs converter pra CSV
Rejeitado — F1.5 adiciona específicos sem custo grande.

2. White-Glove Migration desde F1

Prós: serviço premium desde dia 1
Contras: precisa Migration Specialists contratados antes de validar volume; CAC alto
Rejeitado — F2 quando volume justifica.

3. Sem reverse migration

Prós: vendor lock-in
Contras: viola LGPD + reputação ruim; concorrentes ético-defensáveis ganham
Rejeitado.

Atualizações de documentos

AGENTS.md §inventário (Migração F1, F1.5, F2)
docs/clinic/migracao-*.md
docs/platform/migracoes-*.md
docs/edge-functions/execute-csv-import.md etc

Referências

ADR 0001 (multi-consultancy — clínica direta também migra)
AGENTS.md §inventário
Decisões pendentes: contratação Migration Specialists em F1.5