> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar

> Autorização OAuth separada do login, calendário escolhido pela organização e sincronização inicial da Orquena para o Google.

# Google Calendar

A integração com Google Calendar é opcional e acontece depois do login, durante o onboarding ou nas configurações da organização.

Entrar com Google não conecta automaticamente a agenda.

## Consentimento separado

```text theme={null}
Continuar com Google
└── openid, email e profile

Conectar Google Calendar
└── scopes necessários para calendário
```

Essa separação permite explicar o propósito da integração no momento correto e manter o menor acesso possível.

## Fonte da verdade

A agenda nativa da Orquena decide:

* Disponibilidade.
* Holds.
* Conflitos.
* Criação do appointment.
* Reagendamento.
* Cancelamento.
* Status e histórico.

O Google Calendar recebe uma representação externa do compromisso.

```text theme={null}
Appointment confirmado na Orquena
        ↓
Outbox transacional
        ↓
Worker de sincronização
        ↓
Evento no Google Calendar
```

Uma falha no Google não desfaz um appointment já confirmado na Orquena.

## Onboarding

A etapa oferece:

```text theme={null}
[ Conectar Google Calendar ]
[ Pular por enquanto ]
```

Pular é uma decisão explícita válida e não impede a ativação da organização.

Depois da autorização, o usuário escolhe o calendário de destino.

A conta usada no login e a conta ou agenda operacional podem ser diferentes.

## Direção inicial

A primeira versão implementa:

```text theme={null}
Orquena → Google Calendar
```

A sincronização bidirecional fica para uma fase posterior, depois de regras de conflito, versões, webhooks, tombstones e reconciliação.

## Operações iniciais

* Criar evento quando o appointment é confirmado.
* Atualizar evento em reagendamento.
* Atualizar ou remover evento em cancelamento conforme a política escolhida.
* Preservar vínculo entre appointment e evento externo.
* Exibir falhas e permitir retry.
* Registrar a última sincronização bem-sucedida.

## Dados da conexão

```text theme={null}
GoogleCalendarConnection
├── organizationId
├── authorizedByUserId
├── googleAccountEmail
├── encryptedRefreshTokenReference
├── grantedScopes
├── status
├── connectedAt
└── lastSuccessfulSyncAt

CalendarBinding
├── organizationId
├── professionalId?
├── googleCalendarId
├── syncDirection
└── status
```

Tokens ficam criptografados e nunca são retornados ao frontend depois de armazenados.

## Estados

```text theme={null}
PENDING_AUTHORIZATION
CONNECTED
DEGRADED
REAUTHORIZATION_REQUIRED
DISCONNECTED
ERROR
```

O dashboard pode mostrar:

* Conta conectada.
* Calendário escolhido.
* Última sincronização.
* Eventos pendentes.
* Falhas.
* Ação de reconectar.

## Mapeamento de evento

O evento pode incluir:

* Nome do serviço.
* Profissional.
* Horário inicial e final.
* Identificador opaco da Orquena.
* Local do atendimento.
* Notas permitidas pela política de privacidade.

Dados sensíveis e conteúdo completo de conversa não são enviados ao Calendar.

## Idempotência

Cada operação externa utiliza uma chave estável derivada do appointment e da versão da operação.

Retries não podem criar eventos duplicados.

O vínculo externo armazena:

```text theme={null}
ExternalCalendarEventMapping
├── appointmentId
├── calendarBindingId
├── externalEventId
├── externalVersion?
├── lastOperation
├── syncStatus
└── lastSyncedAt
```

## Reautorização

Quando o token é revogado ou inválido:

* O appointment continua válido na Orquena.
* A operação fica pendente ou falha de forma visível.
* A organização recebe uma notificação.
* Um usuário autorizado pode reconectar.
* O sistema não solicita credenciais Google por formulário próprio.

## Segurança

* Scopes mínimos para a funcionalidade escolhida.
* Redirect URIs allowlisted.
* OAuth state e proteção contra replay.
* Client secret somente no backend.
* Refresh token criptografado.
* Logs sem tokens ou conteúdo sensível.
* Permissão de integração por organização.
* Revogação auditada.

## Fora da primeira versão

* Ler Gmail.
* Enviar emails pela conta Gmail do cliente.
* Sincronização bidirecional.
* Bloquear horários da Orquena com base em qualquer evento externo sem regra explícita.
* Vários providers de calendário no mesmo onboarding.
* Importação completa de eventos históricos.

## Fonte canônica

```text theme={null}
docs/prds/onboarding-inbox-ai-v1.md
plugins/providers/calendar-google/README.md
```