JoaoBiomed/nexus-app/src/agents/manifest/nexus-patient-onboarding

NEXUS Patient Onboarding - Skill

Fluxo Completo de Onboarding de Pacientes

Ativa em: paciente, cadastro, onboarding, NEXUS ID, NXID, consentimento, LGPD, convite, magic link, equipe, roles, permissões, ficha do paciente, novo paciente, baseline, avaliação inicial, primeiro protocolo

---

Visão Geral

Este skill cobre o ciclo completo de onboarding de pacientes no Ecossistema NEXUS, desde a geração do NEXUS ID até a primeira avaliação de baseline e início do primeiro protocolo. O sistema é multi-tenant, com suporte a consentimento granular LGPD, controle de roles, e agregação de dados de múltiplos módulos.

---

1. NEXUS ID — Sistema de Identificação

Formato e Geração

• Formato Novo: NX-AANNNN (ex: NX-260001)

  • AA = últimos 2 dígitos do ano (2026 → 26)
  • NNNN = sequencial de 4 dígitos (0001–9999)

• Formato Legacy: NXID-XXXXX (ex: NXID-00042)

  • Suportado para compatibilidade, mas não gerado para novos

Geração Atômica com system_counters

Arquivo: /src/services/firestore/patients.service.ts

export const generateNexusId = async (): Promise<string> => {
    try {
        const year = new Date().getFullYear().toString().slice(-2);
        const counterRef = doc(db, 'system_counters', `patients_nexusid_${year}`);

        const newIdNumber = await runTransaction(db, async (transaction) => {
            const counterDoc = await transaction.get(counterRef);
            let nextNum = 1;

            if (counterDoc.exists()) {
                const currentVal = counterDoc.data()?.lastSequential || 0;
                nextNum = currentVal + 1;
            }

            // Atomic write — sem race conditions
            transaction.set(counterRef, { lastSequential: nextNum }, { merge: true });
            return nextNum;
        });

        return `NX-${year}${String(newIdNumber).padStart(4, '0')}`;
    } catch (error) {
        throw new FirestoreError(`Falha ao gerar NEXUS ID: ...`);
    }
};

Benefícios:

• ✅ Atomicidade: Firestore runTransaction garante lock nativo
• ✅ Determinístico: Mesmo NEXUS ID para retry idêntico
• ✅ Escalável: O(1) — não lê todos os pacientes
• ✅ Por-ano: Contador reset anual

Validação e Parsing

// Valida ambos formatos
export function isValidNexusId(nexusId: string): boolean {
    const newFormat = /^NX-\d{6}$/;          // NX-260001
    const legacyFormat = /^NXID-\d{4,5}$/;  // NXID-00001
    return newFormat.test(nexusId) || legacyFormat.test(nexusId);
}

// Extrai sequencial: NX-260001 → 1, NXID-00042 → 42
export function extractNexusIdNumber(nexusId: string): number | null { ... }

// Extrai ano: NX-260001 → 2026 (legacy retorna null)
export function extractNexusIdYear(nexusId: string): number | null { ... }

---

2. Cadastro de Paciente — Dados Demográficos

Estrutura Principal (PatientTypes.ts)

export interface Patient {
    // Identidade
    id: string;                    // Firebase Doc ID
    nexus_id: string;              // NXID-XXXXX ou NX-AANNNN

    // Dados Demográficos
    name: string;
    searchTerm?: string;           // name.toLowerCase() para busca
    email?: string;
    phone?: string;
    cpf?: string;
    birthDate: Date;
    gender: 'M' | 'F' | 'O';

    // Antropométricos
    height?: number;               // cm
    weight?: number;               // kg
    bloodType?: string;            // A+, O-, etc.

    // Endereço
    address?: {
        street: string;
        number: string;
        complement?: string;
        neighborhood: string;
        city: string;
        state: string;
        zipCode: string;
    };

    // Contato de Emergência
    emergencyContact?: {
        name: string;
        relationship: string;
        phone: string;
        email?: string;
    };

    // Status
    status: 'ACTIVE' | 'INACTIVE' | 'PENDING' | 'ARCHIVED';
    riskLevel?: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';

    // Clínica
    clinicId?: string;             // Multi-tenant
    assignedDoctorId?: string;
    createdBy?: string;            // User que criou

    // Timestamps
    createdAt: Date;
    updatedAt: Date;
}

PatientFormWizard — Fluxo de Registro

Arquivo: /src/modules/Patient/components/PatientFormWizard.tsx

Steps:

1. Dados Pessoais — Nome, CPF, Email, Phone
2. Dados Médicos — Alergias, Histórico Médico, Histórico Cirúrgico, Histórico Familiar
3. Antropométricos — Altura, Peso, Tipo Sanguíneo
4. Guardian Gate (Baseline) — Avaliação inicial de estilo de vida
5. Endereço e Contato de Emergência
6. Consentimento LGPD

Validação:

• CPF format (11 dígitos)
• Email válido
• Data de nascimento (deve ser ≥ 18 anos)
• Altura/Peso válidos (> 0)

PatientService — Criação

async create(formData: PatientFormData, createdBy: string, clinicId?: string): Promise<Patient> {
    // Gera NEXUS ID atomicamente
    // Mapeia alergias com ID único
    // Seta status = ACTIVE, riskLevel = LOW
    // Marca allergiesReviewed = true se noKnownAllergies OU tem alérgias
    // Marca conditionsReviewed = true se noKnownConditions OU tem condições
    // Registra consentimento geral (legacy)
    return createPatientFirestore(patientData);
}

---

3. Baseline Assessment — Avaliação Inicial

Dados Coletados (Onboarding obrigatório)

// No Patient:
currentMedicationsStatus?: 'NOT_SET' | 'NONE' | 'HAS_MEDICATIONS';
sleepHoursBaseline?: number;                      // horas/noite
stressLevelBaseline?: 1 | 2 | 3 | 4 | 5;         // escala
exerciseFrequencyBaseline?: 'SEDENTARY' | 'LIGHT' | 'MODERATE' | 'HIGH' | 'ATHLETE';
smokingStatusBaseline?: 'never' | 'former' | 'current';
alcoholBaseline?: 'none' | 'occasional' | 'moderate' | 'heavy';
familyHistoryReviewed?: boolean;
onboardingCompletedAt?: Date;

Guardian Gate — Patient Checkin (Magic Link)

Arquivo: /src/ui/pages/public/PatientCheckin.tsx

Fluxo:

1. Médico gera checkinToken (magic link com expiração)
2. Paciente clica no link: https://nexus.clinic/checkin/{token}
3. Sistema valida token contra collection('checkinTokens', token)
4. Paciente preenche formulário de baseline
5. Sistema submete dados em transação, marcando token = USED

Token Validation:

const tokenRef = doc(db, 'checkinTokens', token);
const tokenDoc = await getDoc(tokenRef);

// Validações:
// - Documento existe?
// - status !== 'USED'?
// - expiresAt > agora?

Dados Coletados:

• Sleep Score (0–100)
• Stress Level (slider)
• Hydration (0–100)
• Medication Adherence (0–100)
• Notas livres

---

4. Consentimento LGPD — Granular por Módulo

Bases Legais (Art. 7, 8, 11, 18, 20 da LGPD)

export type ConsentModule =
    | 'endoinject'      // Injeção de endoterapia
    | 'labpro'          // Laboratório
    | 'imeddis'         // Telemedicina
    | 'bodyscan'        // Scan corporal
    | 'lifestyle'       // Dados de estilo de vida
    | 'pharma'          // Farmácia
    | 'sample'          // Coleta de amostra
    | 'aesthetics'      // Procedimentos estéticos
    | 'cortex_ai'       // IA/Cortex
    | 'data_sharing';   // Compartilhamento

export type ConsentPurpose =
    | 'treatment'       // Art. 7, II — Tutela à saúde
    | 'sensitive_data'  // Art. 11 — Dados sensíveis
    | 'ai_processing'   // Art. 20 — Decisão automatizada
    | 'data_portability'// Art. 18, V — Portabilidade
    | 'research';       // Art. 7, IV — Pesquisa

Schema consentGranular

export interface ModuleConsent {
    module: ConsentModule;
    purpose: ConsentPurpose;
    given: boolean;                 // Consentimento ativo?
    grantedAt?: Date;              // Quando foi concedido
    revokedAt?: Date;              // Quando foi revogado
    grantedBy?: string;            // Nome do paciente
    collectedBy?: string;          // ID do profissional
    version: string;               // "1.0" — versão do texto
}

// Array dentro de Patient:
consentGranular?: ModuleConsent[];

ConsentService — Operações

Arquivo: /src/services/firestore/consent.service.ts

// Grant — Conceder consentimento
export const grantModuleConsent = async (
    patientId: string,
    module: ConsentModule,
    purpose: ConsentPurpose,
    collectedBy: string,
    version: string = '1.0'
): Promise<void> => {
    // 1. Busca paciente
    // 2. Localiza/cria entrada em consentGranular[]
    // 3. Seta given=true, grantedAt=now
    // 4. Cria log de auditoria
    // 5. Atualiza patient.consentGranular
}

// Revoke — Revogar consentimento
export const revokeModuleConsent = async (
    patientId: string,
    module: ConsentModule,
    purpose: ConsentPurpose,
    revokedBy: string
): Promise<void> => {
    // Seta given=false, revokedAt=now
}

// Check — Verificar consentimento ativo
export const hasModuleConsent = (
    consentGranular: ModuleConsent[] | undefined,
    module: ConsentModule,
    purpose: ConsentPurpose
): boolean => {
    const entry = consentGranular?.find(c =>
        c.module === module && c.purpose === purpose
    );
    return entry?.given === true;
}

// Listar todos ativos
export const getActiveConsents = (
    consentGranular: ModuleConsent[] | undefined
): ModuleConsent[] => {
    return consentGranular?.filter(c => c.given) || [];
}

---

5. PatientContextAggregator — 360° View

Propósito

Agrega dados de TODOS os módulos em um contexto unificado (PatientFullContext) para:

• ✅ Geração inteligente de protocolo
• ✅ Detecção de interações medicamentosas
• ✅ Análise de risco cruzada
• ✅ Cálculo de completude de dados
• ✅ Sugestões de próximos passos

Arquivo: /src/services/PatientContextAggregator.ts

Coleta Paralela (allSettled)

const results = await Promise.allSettled([
    this.getMedicationContext(patientNexusId),
    this.getLabContext(patientNexusId, patientData.gender),
    this.getBodyScanContext(patientNexusId, patientData.weight, patientData.height),
    this.getLifestyleContext(patientNexusId),
    this.getCrossModuleContext(patientNexusId, patientData.id)
]);

// Cada falha usa fallback — não quebra o fluxo inteiro

Contextos Coletados

MedicationContext:

• Medicações ativas (dosagem, frequência)
• Interações medicamentosas (75+ entradas de pharmacopeia)
• Duplicatas (aviso)
• Taxa média de aderência
• Renovações necessárias

LabContext:

• Últimos resultados de exames
• Marcadores anormais
• Alertas de tendência (subida/descida anormal)
• Exames recomendados

BodyScanContext:

• Composição corporal atual (peso, altura, IMC, BF%, massa magra)
• Scan anterior para comparação
• Tendência (ganho/perda de peso)
• Fator de ajuste de dose (baseado em composição)

LifestyleContext:

• Perfil de sono (horas, qualidade)
• Nível de estresse
• Frequência de exercícios
• Tipo de dieta
• Consumo de álcool
• Status de fumo
• Wellness Score (0–100)
• Fatores de risco lifestyle
• Recomendações personalizadas

CrossModuleContext:

• EndoInject: sessões totais, completadas, agendadas, eventos adversos
• Sample Queue: tickets, recoleções
• Protocolos: histórico, distribuição por módulo
• Pharma: alertas de estoque baixo/vencimento
• Agenda: próximas consultas
• Integration Score (0–100)

Completude de Dados (0–100%)

const completenessBreakdown = {
    patient: calculatePatientCompleteness(patientData),    // 25%
    lab: labContext.latestResults ? 100 : 0,               // 30%
    medications: 100,                                      // 15%
    bodyScan: currentScan ? 100 : (weight && height ? 50 : 0),  // 15%
    lifestyle: lifestyleContext.wellnessScore > 0 ? 100 : 0 // 15%
};

const dataCompleteness = Math.round(
    (completenessBreakdown.patient * 0.25) +
    (completenessBreakdown.lab * 0.30) +
    (completenessBreakdown.medications * 0.15) +
    (completenessBreakdown.bodyScan * 0.15) +
    (completenessBreakdown.lifestyle * 0.15)
);

---

6. Roles e Controle de Acesso

Estrutura de Roles

interface User {
    id: string;
    email: string;
    displayName: string;
    role: 'ADMIN' | 'DOCTOR' | 'RECEPTIONIST' | 'PENDING';
    clinicId: string;
    createdAt: Date;
}

Permissões por Role:

| Role | Criar Paciente | Editar Paciente | Ver Protocolos | Gerar Protocolo | Convidar | |------|---|---|---|---|---| | ADMIN | ✅ | ✅ | ✅ | ✅ | ✅ | | DOCTOR | ✅ | ✅ | ✅ | ✅ | ❌ | | RECEPTIONIST | ✅ | ⚠️* | ❌ | ❌ | ❌ | | PENDING | ❌ | ❌ | ❌ | ❌ | ❌ |

*RECEPTIONIST pode editar dados demográficos apenas

RoleGuard — Componente

Arquivo: /src/ui/components/RoleGuard.tsx

interface RoleGuardProps {
    allowedRoles: string[];
    children: React.ReactNode;
}

export function RoleGuard({ allowedRoles, children }: RoleGuardProps) {
    const user = useAuthStore(s => s.user);

    if (!user || !allowedRoles.includes(user.role)) {
        return <AccessDeniedUI />;  // Exibe "Acesso Restrito"
    }

    return <>{children}</>;
}

// Uso:
<RoleGuard allowedRoles={['ADMIN', 'DOCTOR']}>
    <ProtocolGenerationPage />
</RoleGuard>

---

7. Team Invite — Convite para Equipe

Fluxo de Convite (Magic Link)

Arquivo: /src/ui/pages/public/TeamInvite.tsx

Etapas:

1. ADMIN cria invite:

   • POST /api/team-invites com email, role, clinicId
   • Sistema cria documento em teamInvites/{token} com expiração (e.g., 7 dias)

2. Email enviado com link:

   • https://nexus.clinic/team-invite/{token}

3. Usuário clica no link:

   • Página valida token:
     • Existe?
     • status !== 'ACCEPTED'?
     • expiresAt > agora?

4. Formulário de Registro:

   • Campo: Nome completo
   • Campo: Senha (6+ chars)
   • Confirmação de senha

5. Submissão:

   • Cria Firebase Auth user (email + password)
   • Atualiza profile (displayName)
   • Cria documento em users/{uid} com role e clinicId
   • Marca teamInvites/{token}.status = 'ACCEPTED'

Team Invites Schema

interface TeamInviteData {
    email: string;
    role: 'DOCTOR' | 'RECEPTIONIST';
    clinicId: string;
    status: 'PENDING' | 'ACCEPTED';
    expiresAt: Timestamp;
    createdAt?: Timestamp;
    createdBy?: string;
}

// Armazenado em: db.collection('teamInvites').doc(token)
// Token = criado aleatoriamente (UUID v4 recomendado)

---

8. Primeiro Protocolo — Do Onboarding ao Protocol Generation

Status Flow (Paciente)

┌─────────┐   (onboarding)   ┌────────┐   (baseline +  ┌────────┐
│ PENDING │ ─────────────────► ACTIVE │    lab/scan)   │PROTOCOL│
└─────────┘                   └────────┘  ─────────────► READY  │
                                                         └────────┘

Condições para Gerar Protocolo

1. Paciente status = ACTIVE
2. Baseline completo:
   • currentMedicationsStatus ≠ 'NOT_SET'
   • sleepHoursBaseline, stressLevelBaseline, exerciseFrequencyBaseline setados
3. Consentimento LGPD mínimo:
   • hasModuleConsent(consentGranular, 'endoinject', 'treatment') = true
   • Ou consentimento geral (legacy)
4. Dados complementares (desejáveis, não obrigatórios):
   • Último resultado de laboratório (labContext.latestResults)
   • Body scan (composição corporal)
   • Alergias reviewed
   • Condições reviewed

ProtocolContextBuilder

Arquivo: /src/services/protocol/ProtocolContextBuilder.ts

// Transforma PatientFullContext em contexto estruturado para IA/Gemini
public buildFromPatient(patient: Patient, fullContext: PatientFullContext): ProtocolContext {
    return {
        nexusId: patient.nexus_id,
        basicInfo: { name, age, gender, ...},
        medicalHistory: { conditions, allergies, ... },
        currentMedications: fullContext.medications,
        labResults: fullContext.lab,
        bodyComposition: fullContext.bodyScan,
        lifestyle: fullContext.lifestyle,
        dataCompleteness: fullContext.dataCompleteness,
        crossModuleSignals: fullContext.crossModule,
        riskAssessment: this.calculateRiskProfile(...)
    };
}

Protocol Generation Flow

1. Checkout de dados:

   Patient + PatientContextAggregator.getFullContext()
   → PatientFullContext
   

2. Build context:

   ProtocolContextBuilder.buildFromPatient(patient, fullContext)
   → ProtocolContext
   

3. AI Generation (Gemini):

   GeminiProtocolService.generateProtocol(protocolContext)
   → Protocol JSON
   

4. Validação e Save:

   Protocol → Firestore (collection='protocols')
   ProtocolOrchestrator.setActive() → Marca como ativo
   

---

9. Dados Enrichment — Patient Computed Fields

O patient armazenado no Firestore recebe enriquecimento em memória quando recuperado:

private enrichPatient(patient: Patient): Patient {
    const birthDate = patient.birthDate instanceof Date
        ? patient.birthDate
        : new Date(patient.birthDate);

    const age = Math.floor(
        (Date.now() - birthDate.getTime()) / (365.25 * 24 * 60 * 60 * 1000)
    );

    return {
        ...patient,
        age,                          // Computed
        conditions: patient.conditions || [],
        modulesLinked: patient.modulesLinked || [],
        consent: patient.consent || { given: false },
    };
}

NÃO são persistidos no Firestore:

• age — sempre recalculado
• currentMedications — buscado do medications.service
• latestLabs — buscado do labResults.service
• bodyComposition — buscado do bodyScan.service
• lifestyle — buscado do lifestyle.service

---

10. Hooks e Stores

usePatientData / usePatientHub

Hooks customizados para carregar e gerenciar dados de pacientes em componentes React.

usePatientStore (Zustand)

interface PatientStore {
    patients: Patient[];
    selectedPatient: Patient | null;
    loading: boolean;
    error: string | null;

    fetch: (clinicId?: string) => Promise<void>;
    fetchOne: (id: string) => Promise<void>;
    create: (data: PatientFormData) => Promise<Patient>;
    update: (id: string, data: Partial<Patient>) => Promise<void>;
    select: (patient: Patient) => void;
}

const usePatientStore = create<PatientStore>(...)

---

11. Validações Importantes

validatePatient.ts

• CPF: 11 dígitos, validação de dígito verificador
• Email: RFC 5322 básico
• Birthdate: Mínimo 18 anos
• Altura: 100–250 cm
• Peso: 30–250 kg
• Alergias: Não duplicadas
• Baseline: Todos os campos marcados como required

---

12. Fluxo Resumido: Novo Paciente até Primeiro Protocolo

1. RECEPCIONISTA clica "Novo Paciente"
   → PatientFormWizard abre

2. Preenche Dados Demográficos (Step 1–3)
   → Sistema gera NEXUS ID atomicamente
   → Patient criado com status=PENDING

3. Médico faz Guardian Gate (Baseline Vital)
   → Gera checkinToken com magic link
   → Envia link para paciente via SMS/Email

4. PACIENTE clica link (PatientCheckin)
   → Valida token
   → Preenche Sleep, Stress, Hydration, Adherence
   → Submits em transação (token → USED)

5. MÉDICO completa cadastro
   → Alergias reviewed? Sim
   → Condições reviewed? Sim
   → Endereço preenchido
   → Patient status → ACTIVE

6. CONSENTIMENTO LGPD
   → Médico valida checkboxes (endoinject/treatment, lab/sensitive_data)
   → grantModuleConsent(patientId, 'endoinject', 'treatment', doctorId)
   → consentGranular[] atualizado

7. PRIMEIRA COLETA (opcional mas recomendado)
   → LabPro: solicita exames iniciais
   → Sample: agenda coleta
   → BodyScan: mede composição

8. PROTOCOL GENERATION
   → Médico clica "Gerar Protocolo"
   → Sistema chama PatientContextAggregator.getFullContext()
   → Agrupa dados de todos módulos
   → ProtocolContextBuilder.buildFromPatient()
   → GeminiProtocolService.generateProtocol()
   → Protocol salvo, status=ACTIVE

9. PACIENTE inicia primeiro protocolo

---

Quick Reference: Arquivos Principais

| Arquivo | Responsabilidade | |---------|------------------| | /src/types/PatientTypes.ts | Schema de Patient, Alergy, ModuleConsent | | /src/modules/Patient/PatientService.ts | CRUD de pacientes | | /src/services/firestore/patients.service.ts | Firestore ops, generateNexusId, fixDuplicates | | /src/services/PatientContextAggregator.ts | Agregação 360° de dados | | /src/modules/Patient/components/PatientFormWizard.tsx | Fluxo de registro em 6 steps | | /src/ui/pages/public/PatientCheckin.tsx | Magic link para baseline (paciente) | | /src/ui/pages/public/TeamInvite.tsx | Magic link para team (staff) | | /src/services/firestore/consent.service.ts | Grant/revoke consentimento LGPD | | /src/ui/components/RoleGuard.tsx | Proteção de rotas por role | | /src/services/protocol/ProtocolContextBuilder.ts | Transform context para IA |

---

Troubleshooting Comum

Q: Paciente com NEXUS ID duplicado?

• Execute: fixDuplicateNexusIds(keepPatientId?) da patients.service

Q: Token expirado ou já usado?

• Gere novo token: POST /api/checkin-tokens com patientId
• Expiração padrão: 7 dias

Q: Como verificar consentimento de um módulo?

• Use: hasModuleConsent(patient.consentGranular, 'labpro', 'treatment')
• Verifique given === true e revokedAt === null

Q: Dados de baseline incompletos?

• PatientFormWizard auto-navega para Step 4 se detectar falta
• Todas as 5 linhas do baseline são obrigatórias

Q: Paciente vê "Acesso Restrito" em página?

• Verifique RoleGuard.allowedRoles vs user.role
• Verifique se user.role foi salvo em Firestore users/{uid}

---

Relacionados

• nexus-id-system.md — Detalhe técnico do NXID
• patient-registration.md — Fluxo visual do cadastro
• lgpd-consent.md — Artigos da LGPD e implementação
• baseline-assessment.md — Guardian Gate em detalhe
• patient-context-360.md — PatientContextAggregator deep-dive
• roles-access-flow.md — RoleGuard e flows de auth
• first-protocol-flow.md — Caminho da geração

---

Status: MVP de onboarding pronto para clínicos Última atualização: 2026-03-07 Versão: 1.0