Equipa, papéis, horários e Google Calendar

O FIRO separa propositadamente duas entidades:

• Staff — a pessoa visível no calendário e na página pública (nome, foto, serviços que faz). É o que o cliente vê quando escolhe "marcar com a Joana".
• User — a conta de login que acede ao backoffice. Tem email, eventualmente Google OAuth, e pertence a um ou mais tenants.

A relação entre os dois é via user_tenant. Isto suporta cenários como:

• O owner que não atende clientes (não é staff visível) mas tem login.
• A profissional que tem login no seu tenant mas não no de uma associação onde também trabalha.
• Profissional sem conta — visível como staff no calendário, sem entrar no sistema.

Cada user num tenant tem um papel (user_tenant.role):

• Owner — proprietário do tenant. Acesso total: gestão de planos, equipa, configurações, todos os módulos.
• Manager — gestor administrativo. Acesso a operação corrente: marcações, clientes, serviços, relatórios. Tipicamente sem acesso a billing.
• Staff — colaborador com vista limitada à sua agenda e marcações. Não vê o financeiro nem altera configurações.

Permissões dos colaboradores

O dono (ou um gestor com acesso à conta) escolhe, na ficha de cada colaborador, o que ele pode fazer (user_tenant.permissions):

• ver as marcações de toda a equipa;
• confirmar, recusar e alterar marcações;
• criar marcações para outros colaboradores;
• editar os dados dos clientes;
• registar pagamentos (ligado por omissão).

Por omissão o colaborador vê e trata só as suas marcações. A coluna antiga can_approve_bookings deixou de contar.

StaffSchedule guarda blocos de trabalho para cada profissional, por dia da semana (0–6) com hora de início e fim. Permite:

• Horários repetitivos: terça a sexta, 9h-13h e 14h-19h.
• Múltiplos blocos no mesmo dia (intervalo de almoço fica fora dos slots automaticamente).
• Cada profissional com a sua escala individual.

Horários padrão do tenant

Para arranque rápido, há default_schedules_json ao nível do tenant — um esqueleto que se aplica a novos profissionais.

StaffTimeoff regista períodos em que o profissional não está disponível:

• Férias (uma semana ou um mês inteiros).
• Baixa médica.
• Formações ou eventos pontuais.

Cada registo tem start_at, end_at e um reason opcional para registo. Os slots públicos durante o período desaparecem automaticamente.

Bloqueios em modo class

Alternativamente, criam-se marcações em modo class com preço zero para bloquear apenas algumas horas (uma reunião interna, formação curta) sem mexer no horário base.

O FIRO não usa passwords no fluxo principal — opta por mecanismos mais seguros e sem fricção:

• Magic link por email — o staff insere o email em /staff/login, recebe um link, clica e está autenticado. Tokens com expiração e log de IP/user agent.
• Google OAuth — login com a conta Google profissional/pessoal.

O login centralizado em staff.firo.pt permite que um profissional que trabalha em mais do que um tenant escolha qual abrir após autenticação.

Cada profissional pode ligar a sua conta Google Calendar pessoal. A integração é bidireccional:

• FIRO → Google — todas as marcações criadas aparecem como eventos no Calendar do staff.
• Google → FIRO — eventos criados no Calendar bloqueiam disponibilidade. Tentativas de criar marcação com base nesses eventos são feitas quando relevante.

Detalhes técnicos

• Tokens OAuth (refresh_token, access_token) ficam cifrados em base de dados.
• O staff conecta/desconecta em /profile/google-calendar.
• A funcionalidade pertence ao plano Pro e superiores.

O número de profissionais incluídos depende do plano:

• Starter — 1 profissional. Extras avulso a 4,99 €/mês cada.
• Pro — 3 profissionais. Extras avulso a 4,99 €/mês cada.
• Business — profissionais ilimitados.

O método Tenant::maxStaffCount() calcula o limite efectivo somando o plano + extra_user_seats activos.

Cada user pode personalizar a sua vista de calendário (preferências guardadas em User::calendar_preferences). Suporta:

• Vista por dia, semana ou mês.
• Vista por profissional (uma coluna por staff) ou consolidada.
• Filtros por estado da marcação.
• Drag-and-drop para reagendar.