Documento de Requisitos de Software

Histórico de Versões

Glossário

1. Introdução e Visão Geral

1.1 Propósito do Documento

Este documento especifica os requisitos funcionais, os requisitos não funcionais, as regras de negócio e os casos de uso do sistema Frila, servindo de referência para o time de desenvolvimento, para os testes e para a validação com as partes interessadas. O posicionamento de mercado, as personas e a justificativa de cada escolha estão no Documento de Visão v1.3.0, que este documento complementa e não repete.

Uma ressalva de leitura: o Frila ainda não passou por validação de campo. Desde 22/09 há código, o backend no Supabase e o app iOS, com builds internos no TestFlight, e o comportamento da API está no contrato (api/openapi.yaml, versão 0.2.27). As regras e os requisitos aqui derivam de evidência pública sobre o mercado e das falhas observadas nos concorrentes, mas as premissas de comportamento do usuário no Distrito Federal permanecem hipóteses, marcadas com [H]. Requisitos que dependem diretamente de uma hipótese trazem a marca no próprio texto, para que a revisão posterior saiba onde mexer.

1.2 Escopo

Objetivo do Produto

Permitir que um contratante publique um turno avulso e o preencha em poucas horas com um profissional em quem possa confiar, ainda que as duas partes nunca tenham trabalhado juntas. O sistema resolve isso levando a vaga ativamente até quem pode aceitá-la e dando a cada lado um sinal verificável sobre o outro antes da decisão.

Público-alvo

Qualquer negócio que precise cobrir um turno avulso, de qualquer setor: bares, restaurantes, cafeterias, buffets, produtoras de evento, varejo, logística, serviços domésticos e outros. Food service e eventos são o foco da divulgação inicial. Do outro lado, os profissionais que trabalham por turno avulso. Praça inicial: Distrito Federal.

Plataformas

Um aplicativo só, com dois perfis, o do profissional e o do contratante, que publica pelo estabelecimento, em iOS nativo (Swift e SwiftUI), Android nativo (Kotlin) e versão web. Cada conta tem um perfil só (RN25). O Painel é uma feature da versão web, no perfil de contratante, usada pelo gestor. O backend é o Supabase, onde ficam as regras que precisam valer igual nos três clientes. A v1.0, na App Store em 13/11/2026, é só iOS; Android e web, com o Painel, entram na v1.2, no 1º trimestre de 2027 (Escopo do MVP).

Fora do Escopo

Processamento, custódia ou repasse de pagamento. O valor é combinado e pago diretamente entre as partes, e o sistema apenas registra o que foi acordado. Também estão fora: contratação em regime CLT e processo seletivo, emissão de contrato ou nota fiscal, chat interno, avaliação por nota de 1 a 5, feed ou rede social, aval de quem trabalhou com o profissional fora da plataforma, atendimento ao vivo ou plantão da equipe Frila, operação fora do DF antes da consolidação local e qualquer cobrança dentro do aplicativo enquanto o modelo de monetização não estiver definido. Vaga remota faz parte do escopo do produto, mas fica para depois do MVP: na primeira versão, toda vaga é presencial.

1.3 Visão Geral do Documento

Este documento está organizado da seguinte forma: a Seção 2 define as Regras de Negócio, que originam os requisitos; a Seção 3 especifica os Requisitos Funcionais, com prioridade, critério de aceitação, estimativa e matriz de impacto por esforço; a Seção 4 descreve os Requisitos Não Funcionais; a Seção 5 lista o Escopo Não Contemplado; a Seção 6 apresenta os diagramas de casos de uso, de banco de dados, de classes e de arquitetura; e a Seção 7 reúne a matriz de rastreabilidade completa.

2. Regras de Negócio

2.1 Regras Obrigatórias

3. Requisitos Funcionais

3.1 Lista de Requisitos Funcionais

3.2 Tempo e Custo Estimados por RF

Estimativas em dias de trabalho de uma equipe de cinco pessoas, considerando sprint de duas semanas. Custo de desenvolvimento é R$ 0 por ser trabalho interno da equipe; onde há custo, ele é de infraestrutura ou de serviço externo. As estimativas foram feitas antes do código e são preliminares: devem ser revistas com o ritmo medido nas primeiras sprints. [H]

3.3 Matriz Impacto × Esforço

RF06 (despacho ativo) é o maior esforço da lista e também o coração do produto: sem ele o Frila vira mais um mural passivo, que é exatamente o modo de falha identificado em todos os concorrentes. RF19 (escala de evento em lote) tem impacto alto na estratégia de entrada pelo segmento de eventos, mas foi classificado como médio nesta matriz porque o ciclo básico precisa funcionar antes, e é candidato natural à segunda fase de construção. RF25 e RF26 estão entre os de impacto alto porque a App Store rejeita o app sem eles (diretrizes 5.1.1(v) e 1.2). O RF17 foi retirado e não aparece na matriz.

4. Requisitos Não Funcionais

4.1 Lista de Requisitos Não Funcionais

4.2 Tempo e Custo Estimados por RNF

5. Escopo Não Contemplado

Funcionalidade / Recurso

Justificativa da Exclusão

Previsão

Processamento, custódia e repasse de pagamento (carteira, split, escrow)

Exige operação financeira madura, conformidade regulatória e capital de giro. Pagamento retido ou atrasado é a queixa recorrente em Switch, Closeer e eFreela, e assumir a custódia sem estrutura repetiria o problema que o produto quer evitar.

v2.0, condicionado à validação

Cobrança dentro do aplicativo e qualquer modelo de monetização

O modelo de receita está deliberadamente em aberto até a validação de campo. Toda conta de receita depende de um preço que ainda não existe.

Indefinido

Contratação em regime CLT, processo seletivo e banco de currículos

Outro negócio, com outro ciclo, outro comprador e outro tempo de decisão. Currículo e processo seletivo não cabem num turno que começa em duas horas.

Nunca

Emissão de contrato, recibo ou nota fiscal

Depende da definição do modelo de intermediação e de revisão jurídica sobre vínculo. O registro do turno cobre a necessidade imediata de comprovação.

v2.0

Chat interno entre as partes

Na v1 o contato é liberado por WhatsApp ou e-mail após a confirmação, que é onde as pessoas já estão. Construir um canal paralelo adiciona superfície de produto sem resolver nada novo.

v2.0, se a validação indicar necessidade

Avaliação por nota de 1 a 5 e comentários abertos

Média com poucas avaliações não informa nada, e comentário aberto abre frente de moderação. A reputação binária com denominador é a aposta central do produto.

Nunca

Feed, seguidores, perfil público e qualquer camada social

O Frila não é rede social profissional. Não há conteúdo, não há audiência e não há motivo para alguém voltar ao app fora do ciclo do turno.

Nunca

Vagas remotas (design, programação, redação e similares)

Entram no escopo do produto, mas não no MVP. Sem presença no local não há check-in, notificação por distância nem presença verificada para liberar a avaliação: a vaga remota precisa de um fluxo próprio.

Depois do MVP

Aval de quem trabalhou com o profissional fora da plataforma

Retirado em 21/09/2026. Só avalia quem trabalhou junto pelo Frila: um atestado externo é fácil de forjar e não tem turno registrado por trás.

Nunca

Atendimento ao vivo e plantão da equipe Frila

O acompanhamento dos turnos é do gestor do contratante, pelo Painel. A equipe Frila só responde e-mail, em até 5 dias úteis.

Não previsto

Notificação Time Sensitive no iOS e pedido de isenção de economia de bateria no Android

Decisão de 21/09/2026. As metas de notificação passam a ser medidas no provedor de push (RNF02 e RNF03).

Indefinido

Operação fora do Distrito Federal

A estratégia é territorial e sequencial: dominar o DF antes de abrir qualquer outra praça. Densidade é difícil de construir e fácil de perder.

Depois da consolidação no DF

Verificação de antecedentes criminais

Custo por consulta relevante, impacto direto na barreira de entrada do profissional e implicações de discriminação que exigem análise jurídica.

Indefinido

Seguro de acidentes pessoais para o profissional

Praticado por pelo menos um concorrente e possivelmente relevante, mas depende de parceria e de um modelo de receita que ainda não existe.

Indefinido

Geolocalização em tempo real do profissional a caminho do turno

Custo de bateria e de privacidade alto demais para o benefício, e tensiona a regra que evita caracterizar subordinação (RN16). O check-in lê a localização só no toque (RN22).

Nunca na forma contínua

Integrações com PDV, sistema de ponto e folha de pagamento

O público-alvo primário são operações pequenas, cuja infraestrutura de software costuma ser o celular de quem está no salão.

Indefinido

6. Diagramas

6.1 Diagrama de Casos de Uso

Dezesseis casos de uso ativos cobrem os vinte e seis requisitos funcionais ativos: nenhum RF fica sem caso de uso na matriz da Seção 7.1. O UC12 e o RF17 foram retirados em 21/09/2026, junto com o aval herdado, e os números ficam reservados. Um único desenho com todos eles e quatro atores vira um emaranhado de linhas, então o diagrama é apresentado em três vistas, cada uma respondendo a uma pergunta. Um caso de uso pode aparecer em mais de uma vista.

O despacho (UC02) não tem ator primário. Ele é incluído pela publicação (UC01) e pela reabertura (UC08), e o agrupamento das notificações, os lembretes, os alertas de atraso e de vaga vazia, o fechamento automático do modo seleção e o pedido de avaliação são disparados pelo agendador do sistema. Desenhar o próprio sistema como ator colocaria o Frila do lado de fora do Frila.

Figura 1 — Ciclo do turno: da publicação à avaliação (UC01 a UC08)

Figura 2 — Cadastro, perfil e confiança (UC09 a UC11 e UC13)

Figura 3 — Suporte e direitos de quem usa (UC14 a UC17)

Atores

Ator

Quem é

Casos de Uso

Profissional

Quem executa turnos avulsos: garçom, bartender, cozinheiro, recepcionista, promotor e outras funções operacionais. Maior de 18 anos.

UC03, UC05, UC06, UC08, UC09, UC13, UC14, UC15, UC16, UC17

Contratante

Usuário de um estabelecimento que publica turnos: bar, restaurante, buffet, produtora, loja, residência ou outro negócio. Age com papel de administrador ou de operador do estabelecimento (RF21) e, como gestor, acompanha vagas e turnos pelo Painel.

UC01, UC04, UC05, UC06, UC07, UC08, UC10, UC11, UC13, UC14, UC15, UC16, UC17

Equipe Frila

Pessoa da equipe Frila que responde, por e-mail, suporte, denúncias, contestações e pedidos de revisão do despacho, e pode ocultar vaga com conteúdo impróprio até revisá-la. Não acompanha turnos nem intervém neles.

UC09, UC14, UC15, UC17

Usuário

Generalização de Profissional e Contratante, usada onde os dois têm o mesmo direito.

UC14, UC15, UC16, UC17

Descrição dos Casos de Uso

UC01: Publicar vaga

Ator(es)

Contratante (administrador ou operador do estabelecimento)

Pré-condição

O contratante está autenticado e o estabelecimento tem cadastro completo (UC10).

Fluxo Principal

1. O contratante escolhe publicar uma vaga.

1. O sistema apresenta o formulário com os campos obrigatórios de RN02 (função, data, horário de início e fim, endereço e região administrativa, valor por posição, número de posições, o que está incluso e quem recebe no local), os opcionais (traje exigido, participação no rateio dos 10% e observações), o modo de preenchimento (urgência ou seleção) e a antecedência do alerta de vaga vazia, com padrão de 3 horas.

1. O contratante preenche os campos. O endereço e a região são pré-preenchidos com os do estabelecimento.

1. O sistema valida a obrigatoriedade dos campos conforme RN02.

1. O contratante confirma a publicação.

1. O sistema registra a vaga, cria uma posição por unidade solicitada e inclui UC02.

Fluxo Alternativo

2a. A vaga começa em menos de 24 horas: o modo seleção não é oferecido, e a vaga é publicada em modo urgência; se o pedido chegar com seleção, o servidor o recusa (RN24).

3a. O contratante opta por republicar uma vaga anterior: o sistema pré-preenche todos os campos e solicita apenas a nova data e o novo horário (RF05).

3b. O contratante monta a escala de um evento: informa várias funções, cada uma com seu número de posições, e o sistema publica tudo numa única operação, acompanhando o preenchimento por função (RF19).

4a. Algum campo obrigatório está ausente ou inválido: o sistema indica o campo e impede a publicação.

Pós-condição

Vaga publicada, posições criadas com estado aberto e despacho iniciado.

Regras Relacionadas

RN02, RN03, RN04, RN18, RN24

Critério de Aceitação (BDD)

Dado que sou um contratante autenticado com estabelecimento cadastrado, quando preencho os campos obrigatórios e confirmo, então a vaga é publicada e a notificação aos profissionais elegíveis é disparada.

UC02: Despachar vaga aos profissionais elegíveis

Ator(es)

Nenhum ator primário. Incluído por UC01 e UC08; o agrupamento das notificações e o reenvio de falhas são feitos pelo agendador do sistema.

Pré-condição

Existe ao menos uma posição aberta na vaga.

Fluxo Principal

1. O sistema seleciona os profissionais elegíveis (RN05): função compatível, disponibilidade no horário, até 15 km entre o ponto base e o local, perfil ativo, nenhum bloqueio entre as partes e nenhum turno confirmado que se sobreponha ao da vaga.

1. O sistema inclui os profissionais da equipe de confiança do estabelecimento que tenham a função e estejam disponíveis, mesmo além de 15 km (UC11).

1. Para cada elegível, o sistema aplica o teto de RN23: se ele não recebeu notificação de vaga nos últimos 30 minutos, a notificação sai agora; se recebeu, a vaga entra na próxima notificação agrupada.

1. O sistema envia as notificações de uma vez, sem ordem entre os elegíveis, e registra o envio e o estado de entrega de cada uma.

1. A vaga fica visível na lista de todo o DF enquanto houver posição aberta.

Fluxo Alternativo

1a. Não há nenhum elegível: a vaga segue visível na lista do DF, e o contratante é avisado de que ninguém próximo e disponível foi encontrado.

3a. A vaga é do modo urgência e começa em menos de 2 horas: ela fura o agrupamento e sai na hora, mas conta no teto do profissional (RN23).

4a. O profissional ignora ou recusa a notificação: nada é registrado contra ele (RN16), e ele segue elegível para as próximas vagas.

4b. A entrega da notificação falha: o sistema reenvia e registra o motivo (RNF02).

5a. A posição entra na janela crítica ainda aberta: o contratante recebe o alerta de vaga vazia (RF20).

Pós-condição

Profissionais elegíveis notificados, com registro de envio e de entrega.

Regras Relacionadas

RN04, RN05, RN06, RN16, RN23

Critério de Aceitação (BDD)

Dado que uma vaga foi publicada com posições abertas, quando o despacho é executado, então apenas profissionais elegíveis são notificados, em até 30 segundos e sem ordem entre eles, nenhum inelegível recebe a notificação e nenhum profissional recebe mais de uma notificação de vaga a cada 30 minutos.

UC03: Candidatar-se a uma posição

Ator(es)

Profissional

Pré-condição

O profissional está autenticado, tem perfil ativo e recebeu a notificação (UC02) ou encontrou a vaga na lista do DF (RF07).

Fluxo Principal

1. O profissional toca na notificação, que abre o detalhe da vaga, ou abre a vaga na lista.

1. O sistema exibe função, endereço, data, horário, valor, o que está incluso e o perfil do contratante com reputação e denominador.

1. O profissional se candidata, sem formulário. A tela avisa que, se ele for confirmado, telefone e WhatsApp serão mostrados ao estabelecimento (RN10).

1. O sistema registra a candidatura e a submete a UC04.

Fluxo Alternativo

3a. A posição já foi preenchida enquanto o profissional visualizava: o sistema informa o encerramento e oferece outras vagas próximas.

3b. O profissional já tem turno confirmado que se sobrepõe a este: o sistema impede a candidatura e mostra o turno em conflito. A regra é garantida no banco de dados, e não só na tela (RN21).

3c. O perfil está suspenso: o sistema mostra o motivo e o caminho para contestar (UC15).

3d. Há bloqueio entre o profissional e o estabelecimento: a vaga não aparece para ele, nem na notificação nem na lista (RF26).

3e. O profissional não tem a função da vaga, ou ainda não completou o perfil: a candidatura é recusada, e o app leva à tela de funções.

Pós-condição

Candidatura registrada e submetida ao fluxo de confirmação.

Regras Relacionadas

RN03, RN05, RN08, RN10, RN21

Critério de Aceitação (BDD)

Dado que recebi a notificação de uma vaga elegível, quando toco em candidatar-me, então a candidatura é registrada sem formulário e sem negociação de valor.

UC04: Confirmar profissional na posição

Ator(es)

Contratante no modo seleção. No modo urgência, a confirmação é automática.

Pré-condição

Existe ao menos uma candidatura válida para a posição.

Fluxo Principal

1. No modo urgência, o sistema confirma automaticamente o primeiro candidato elegível que aceita.

1. No modo seleção, o sistema apresenta os candidatos ao contratante com reputação, denominador e taxa de comparecimento, e o contratante escolhe.

1. O sistema marca a posição como confirmada e garante que nenhuma outra confirmação ocorra para ela; quando todas as posições estão ocupadas, a vaga passa a preenchida.

1. O sistema notifica os dois lados com função, local, horário, valor e identificação da contraparte.

1. O sistema libera o contato direto entre as partes, visível até 7 dias depois do fim do turno (RN10).

Fluxo Alternativo

2a. No modo seleção, o contratante não escolhe até 24 horas antes do início: a vaga fecha automaticamente, as posições ainda abertas são canceladas, as candidaturas pendentes expiram, e candidatos e estabelecimento são avisados (RN24).

2b. O profissional retira a candidatura antes de ser escolhido: a retirada não gera penalidade, e ele segue livre para outras vagas (RN24).

2c. No modo seleção, a escolha ocupa a última posição aberta: as candidaturas ainda pendentes são recusadas, com aviso.

3a. Duas confirmações chegam simultaneamente: o sistema confirma exatamente uma, e a outra recebe a resposta de posição já ocupada.

Pós-condição

Posição preenchida, ambas as partes notificadas e contato liberado.

Regras Relacionadas

RN08, RN10, RN19, RN24

Critério de Aceitação (BDD)

Dado que há candidaturas para uma posição, quando a confirmação ocorre, então os dois lados recebem a notificação com os dados completos do turno, o contato é liberado e a posição deixa de aparecer entre as vagas abertas.

UC05: Registrar a execução do turno

Ator(es)

Profissional e Contratante

Pré-condição

Existe uma posição confirmada cujo horário de início se aproxima.

Fluxo Principal

1. O sistema envia o lembrete pré-turno para os dois lados, 24 horas e 3 horas antes do início, com função, horário e região administrativa; o endereço e o contato ficam dentro do app, e não na tela de bloqueio (RF12).

1. Ao chegar, o profissional faz o check-in, a partir de 60 minutos antes do início. O app lê a localização só nesse toque, calcula a distância até o endereço da vaga e envia só ela; o servidor registra como geolocalizado o check-in a até 200 m (RN22).

1. O sistema grava a hora e a distância medida e avisa o contratante.

1. Ao terminar, o profissional faz o check-out da mesma forma; a distância é registrada, sem limite.

1. O sistema grava início, fim e valor acordado, e disponibiliza o registro aos dois.

Fluxo Alternativo

1a. (v1.1) De 3 horas antes até 15 minutos depois do início, o profissional confirmado avisa que está a caminho: o estabelecimento vê a hora do aviso, que não conta como presença nem substitui o check-in.

2a. A geolocalização falha (sem sinal, permissão negada, GPS impreciso ou a mais de 200 m): o profissional faz check-in manual, e o contratante confirma com um toque, no app ou no Painel web. Sem confirmação, o turno fica “não verificado” e não conta a favor nem contra na taxa de comparecimento.

2b. Chega o horário de início sem check-in: o profissional recebe um lembrete.

2c. Passam 15 minutos do início sem check-in: o contratante é alertado e decide esperar ou reabrir a vaga. Se reabrir, conta como falta do profissional, e a posição segue para UC08.

2d. O turno termina sem check-in nenhum, e o contratante não reabriu a vaga: o sistema cancela a posição com falta do profissional, e o turno fica “não verificado”.

4a. O fim previsto passa sem check-out: os dois lados recebem uma notificação. O que acontece com o valor fica entre as partes; o sistema não calcula hora extra.

4b. O contratante discorda do registro: vale o registro geolocalizado. O Frila não arbitra, e o contratante pode registrar a discordância na avaliação (UC06).

Pós-condição

Turno registrado com horários, distância medida e valor, e avaliação liberada após o término previsto quando a presença foi verificada.

Regras Relacionadas

RN09, RN11, RN18, RN22

Critério de Aceitação (BDD)

Dado que um turno confirmado começou, quando faço check-in a até 200 m do endereço, então o sistema grava a hora e a distância, avisa o contratante e disponibiliza o registro para consulta e exportação pelos dois (UC13).

UC06: Avaliar após o turno

Ator(es)

Profissional e Contratante

Pré-condição

O horário de término previsto do turno já passou, e a presença foi verificada: check-in geolocalizado ou manual confirmado pelo contratante (RN22).

Fluxo Principal

1. O sistema solicita a avaliação a cada lado.

1. Cada um responde a uma única pergunta: “Você chamaria essa pessoa de novo?” para o contratante, “Você trabalharia nesse local de novo?” para o profissional.

1. O sistema registra a resposta e atualiza a reputação da contraparte.

1. O sistema recalcula a taxa de comparecimento a partir dos registros de UC05.

Fluxo Alternativo

2a. Uma das partes não responde: a reputação da outra não é alterada, e o denominador exibido considera apenas as respostas efetivamente dadas.

2b. Outro membro do estabelecimento já respondeu: vale a resposta gravada, um voto por lado do turno, e o app mostra que a casa já avaliou.

3a. O turno foi cancelado antes de começar ou o profissional não compareceu: nenhuma avaliação é solicitada. A falta conta só na taxa de comparecimento, para não pesar duas vezes.

3b. O turno ficou “não verificado”: nenhuma avaliação é solicitada, e o turno não entra na taxa de comparecimento.

Pós-condição

Reputação dos dois lados atualizada; taxa de comparecimento do profissional recalculada.

Regras Relacionadas

RN07, RN08, RN22

Critério de Aceitação (BDD)

Dado que um turno com presença verificada terminou, quando ambas as partes respondem à pergunta binária, então a reputação de cada uma é atualizada e passa a ser exibida com o denominador, sem que nenhuma média de 1 a 5 seja apresentada.

UC07: Acompanhar vagas e turnos pelo Painel

Ator(es)

Contratante, como gestor do estabelecimento, na versão web. O alerta de vaga vazia e a confirmação de check-in manual também existem no app.

Pré-condição

O contratante está autenticado, e o estabelecimento tem vagas publicadas ou turnos confirmados.

Fluxo Principal

1. O gestor abre o Painel na versão web do Frila, com a conta de contratante.

1. O sistema mostra as vagas abertas, os candidatos, os profissionais confirmados, os check-ins do dia e os turnos não verificados.

1. As posições ainda vagas dentro da janela crítica aparecem destacadas, com o tempo que falta para o início.

1. O gestor confirma check-ins manuais pendentes, escolhe candidatos do modo seleção (UC04) ou cancela e reabre posições (UC08).

1. O sistema registra cada ação no turno.

Fluxo Alternativo

3a. Uma posição entra na janela crítica ainda vaga: o contratante recebe um alerta por notificação, 3 horas antes do início ou na antecedência escolhida na publicação (RF20).

4a. O gestor está no celular: o alerta de vaga vazia e a confirmação de check-in manual estão no app, sem precisar do Painel.

Pós-condição

Vagas e turnos acompanhados pelo próprio estabelecimento, sem participação da equipe Frila.

Regras Relacionadas

RN12, RN22, RN24

Critério de Aceitação (BDD)

Dado que uma posição continua vaga a 3 horas do início, quando o prazo é atingido, então o contratante recebe o alerta no app, e a posição aparece destacada no Painel web com o tempo que falta para o início.

UC08: Cancelar e reabrir posição

Ator(es)

Profissional ou Contratante

Pré-condição

Existe uma posição confirmada ainda não executada, ou um não comparecimento em que o contratante decidiu reabrir a vaga (UC05).

Fluxo Principal

1. A parte solicita o cancelamento e informa o motivo.

1. O sistema registra autor, momento, antecedência e motivo.

1. O sistema notifica a contraparte.

1. O sistema mantém a posição cancelada no histórico, cria na mesma vaga uma posição nova, aberta, e inclui UC02 imediatamente.

1. O sistema contabiliza o evento no histórico da parte que cancelou: cancelamento do profissional com mais de 24 horas não entra na taxa de comparecimento; com menos de 24 horas, ou não comparecimento, conta como falta.

Fluxo Alternativo

1a. O contratante cancela a vaga inteira: as posições abertas e confirmadas são canceladas com o motivo, os profissionais confirmados são avisados, e ninguém recebe falta.

4a. O cancelamento acontece depois do início: não há reabertura, e a outra parte é avisada de que o turno ficou descoberto.

4b. Reabertura por atraso (UC05, 2c): conta falta para o profissional, e a posição nova aceita candidatura até 1 hora antes do fim previsto, pelo valor integral (RN01).

5a. Uma parte cancela com frequência: o sistema não suspende nem bloqueia; o efeito é só na taxa de comparecimento, exibida no perfil (RN13).

Pós-condição

Cancelamento registrado, posição reaberta quando cabível e histórico atualizado.

Regras Relacionadas

RN12, RN13, RN16

Critério de Aceitação (BDD)

Dado que uma posição confirmada é cancelada antes do início do turno, quando o motivo é informado, então a contraparte é notificada, a vaga ganha uma posição nova, aberta, e uma nova notificação é disparada em até 30 segundos.

UC09: Cadastrar-se e manter o perfil profissional

Ator(es)

Profissional

Pré-condição

Não existe conta com o mesmo e-mail. O telefone pode se repetir em outra conta (RN25).

Fluxo Principal

1. O profissional informa o e-mail e digita o código de uso único que chega nele. Não há senha nem SMS.

1. O profissional escolhe o perfil de profissional, que fica fixo na conta (RN25), informa nome, telefone com WhatsApp e data de nascimento e aceita a versão vigente dos termos e da política de privacidade. O servidor confere a maioridade pela data de nascimento; do telefone, só o formato.

1. O profissional declara suas funções, o ponto base e a disponibilidade por dia e faixa de horário. Não há distância para configurar: a notificação vai para quem está a até 15 km do local (RN05).

1. O sistema ativa o perfil, que passa a receber notificações de vaga.

1. A qualquer momento, o profissional altera funções, ponto base ou disponibilidade, e a mudança vale na notificação seguinte, sem novo login.

Fluxo Alternativo

2a. A data de nascimento indica menos de 18 anos: o cadastro é recusado, e nada além do necessário para registrar a recusa é guardado (RN20).

2b. A pessoa já tem conta de contratante: para trabalhar em turnos, cria outra conta, com outro e-mail; o telefone pode ser o mesmo (RN25).

3a. O profissional sai antes de declarar funções e ponto base: o cadastro fica salvo, mas o perfil não recebe notificação até completá-los.

5a. O sistema pede verificação de identidade: ela é progressiva e acontece depois da primeira notificação, nunca como barreira de entrada. O documento não aparece em log (RN14, RN15).

5b. O profissional abre “Por que recebo vagas”: o sistema explica os critérios (função, disponibilidade e distância de até 15 km) e oferece o botão “Contestar”, que envia um pedido de revisão à Equipe Frila, respondido em até 5 dias úteis (RF27).

Pós-condição

Perfil ativo e apto a receber notificações de vaga, sem nenhuma cobrança no cadastro.

Regras Relacionadas

RN01, RN05, RN14, RN15, RN20, RN25

Critério de Aceitação (BDD)

Dado que tenho 18 anos ou mais, quando entro com o código enviado ao meu e-mail e informo nome, telefone, funções, ponto base e disponibilidade, então fico apto a receber notificações de vaga sem enviar documento e sem pagar nada.

UC10: Cadastrar o estabelecimento e gerenciar seus usuários

Ator(es)

Contratante com papel de administrador do estabelecimento

Pré-condição

O responsável tem 18 anos ou mais e uma conta de contratante (RN25), criada com código no e-mail.

Fluxo Principal

1. O contratante informa nome ou razão social, documento (CNPJ ou CPF), tipo de negócio, endereço e região administrativa do DF.

1. O sistema valida o documento e localiza o endereço no mapa.

1. O sistema cria o estabelecimento, com quem cadastrou como administrador.

1. (v1.2, RF21) O administrador convida outros usuários pelo e-mail e atribui a cada um o papel de administrador ou de operador do estabelecimento.

1. O convidado aceita com a própria conta de contratante, sem compartilhar acesso. Uma conta de profissional não pode aceitar o convite (RN25).

Fluxo Alternativo

2a. O endereço não é localizado com precisão: o sistema pede que o contratante confirme o ponto no mapa.

4a. O administrador remove um usuário: o acesso é revogado na hora, e o histórico do estabelecimento permanece.

4b. O responsável muda: a administração é transferida, e vagas, turnos e reputação continuam com o estabelecimento.

Pós-condição

Estabelecimento apto a publicar vagas (UC01), com usuários e papéis registrados.

Regras Relacionadas

RN15, RN20, RN25

Critério de Aceitação (BDD)

Dado que cadastrei o estabelecimento, quando convido um gerente como operador, então ele passa a publicar e acompanhar vagas com a própria conta, sem compartilhar acesso, e o histórico permanece com o estabelecimento se eu sair.

UC11: Manter a equipe de confiança

Ator(es)

Contratante com papel de administrador do estabelecimento

Pré-condição

O profissional tem perfil ativo no Frila e ao menos um turno com presença verificada no estabelecimento.

Fluxo Principal

1. O administrador abre o perfil de um profissional a partir do histórico de turnos do estabelecimento (UC13).

1. O administrador adiciona o profissional à equipe de confiança do estabelecimento.

1. O sistema registra a inclusão, e o profissional passa a receber a notificação das próximas vagas do estabelecimento para as quais tiver a função e estiver disponível, mesmo além de 15 km (UC02).

1. O administrador pode remover o profissional da equipe a qualquer momento.

Fluxo Alternativo

2a. O profissional não tem turno com presença verificada na casa: a inclusão é recusada, e o motivo é explicado.

2b. Quem tenta incluir ou remover é operador: a ação é recusada, porque é do administrador (RF21).

3a. O profissional da equipe não tem a função ou não está disponível: ele não é notificado. A equipe dispensa só o limite de distância, nunca os outros critérios de elegibilidade (RN05).

3b. O profissional recusa vagas da equipe: não há penalidade nem remoção automática (RN16).

3c. A equipe não tem prioridade de tempo: a notificação sai para ela e para os demais elegíveis ao mesmo tempo.

Pós-condição

Equipe atualizada, valendo a partir da próxima vaga.

Regras Relacionadas

RN05, RN06, RN16, RN23

Critério de Aceitação (BDD)

Dado que um profissional está na equipe de confiança do meu estabelecimento, tem a função e está disponível, quando publico uma vaga a mais de 15 km dele, então ele recebe a notificação ao mesmo tempo que os demais elegíveis.

UC12: Retirado

Situação

Retirado em 21/09/2026, junto com o RF17. O aval de quem trabalhou com o profissional fora da plataforma saiu do produto: só avalia quem trabalhou junto pelo Frila (RN07). O número fica reservado e não é reutilizado.

UC13: Consultar e exportar o histórico de turnos

Ator(es)

Profissional e Contratante

Pré-condição

Existe ao menos um turno registrado em UC05.

Fluxo Principal

1. O usuário escolhe o período.

1. O sistema lista os turnos com data, função, horários registrados, valor acordado e contraparte.

1. O usuário pede a exportação em CSV ou PDF.

1. O sistema gera o arquivo e o disponibiliza para download ou envio por e-mail.

Fluxo Alternativo

1a. O período não tem turnos: o sistema informa e não gera arquivo vazio.

2a. Um turno ficou “não verificado”: ele aparece marcado assim, sem entrar na taxa de comparecimento.

Pós-condição

Arquivo gerado com os turnos do período. O valor é o acordado e registrado, nunca um pagamento processado pelo Frila.

Regras Relacionadas

RN09, RN11, RN17, RN18

Critério de Aceitação (BDD)

Dado que tenho turnos registrados no mês, quando exporto o período, então o arquivo traz data, função, horários auditados, valor acordado e contraparte de cada turno, pronto para o fechamento contábil.

UC14: Acionar suporte durante o turno

Ator(es)

Usuário (Profissional ou Contratante), atendido pela Equipe Frila por e-mail

Pré-condição

Existe um turno confirmado em andamento ou prestes a começar.

Fluxo Principal

1. O usuário aciona o suporte a partir da tela do turno.

1. O app abre o e-mail do suporte já com os dados do turno, e o usuário escolhe o motivo (endereço, atraso, conduta, segurança ou outro) e descreve o caso.

1. O app mostra o prazo de resposta declarado: até 5 dias úteis.

1. A Equipe Frila responde por e-mail.

Fluxo Alternativo

2a. O motivo é de segurança: além do e-mail, o app mostra atalhos para ligar para o 190 (Polícia) e o 180 (Central de Atendimento à Mulher).

2b. O caso é assédio, discriminação ou risco: o app oferece também denunciar e bloquear a outra parte (UC17).

4a. Não há atendimento ao vivo: questões práticas do turno em andamento são combinadas direto com a outra parte, pelo contato liberado (RN10).

Pós-condição

E-mail enviado com os dados do turno e respondido no prazo declarado.

Regras Relacionadas

RN10, RN11, RN15

Critério de Aceitação (BDD)

Dado que estou num turno confirmado, quando aciono o suporte, então o e-mail abre já com os dados do turno, e eu vejo o prazo de resposta de até 5 dias úteis.

UC15: Consultar e contestar suspensão

Ator(es)

Usuário suspenso (Profissional ou Contratante), atendido pela Equipe Frila por e-mail

Pré-condição

O perfil foi suspenso por denúncia grave confirmada, com motivo registrado (UC17).

Fluxo Principal

1. Ao entrar, o usuário vê o motivo e a data da suspensão.

1. O usuário toca em “Contestar” e escreve o motivo, com evidência se quiser.

1. O sistema envia a contestação à Equipe Frila e informa o prazo de resposta: até 5 dias úteis.

1. A Equipe Frila apura e decide, registrando o fundamento.

1. O sistema comunica a decisão. Se a contestação for aceita, a conta volta na hora.

Fluxo Alternativo

4a. O prazo vence sem decisão: o usuário é avisado do atraso.

5a. A suspensão é mantida: o usuário recebe o fundamento por escrito.

Pós-condição

Contestação decidida, com fundamento registrado.

Regras Relacionadas

RN13, RN15, RN16

Critério de Aceitação (BDD)

Dado que meu perfil foi suspenso, quando abro o aplicativo, então vejo o motivo registrado e consigo contestar, com resposta em até 5 dias úteis.

UC16: Exportar dados pessoais e excluir a conta

Ator(es)

Usuário (Profissional ou Contratante)

Pré-condição

O usuário está autenticado.

Fluxo Principal

1. O usuário abre as configurações de privacidade da conta.

1. O usuário pede a exportação, e o sistema gera um arquivo com seus dados pessoais.

1. O usuário pede a exclusão da conta dentro do aplicativo e confirma.

1. O sistema registra a solicitação, encerra as sessões e tira o perfil do despacho e da busca na hora.

1. Em até 15 dias, os dados pessoais são apagados, e os turnos já realizados são anonimizados, preservando o histórico da contraparte.

Fluxo Alternativo

3a. O usuário tem turnos confirmados no futuro: o sistema avisa que a exclusão os cancela e, confirmada a exclusão, cancela cada posição com o motivo “exclusão de conta”, sem contar falta, e a vaga ganha uma posição nova (UC02).

3b. O usuário é o único administrador de um estabelecimento com outros usuários: o sistema pede que ele transfira a administração antes (UC10).

3c. O usuário é o único membro de um estabelecimento: as vagas abertas são canceladas, as candidaturas pendentes são retiradas e os profissionais são avisados; um turno já em andamento segue até o fim.

Pós-condição

Conta excluída; histórico da contraparte preservado de forma anônima.

Regras Relacionadas

RN15

Critério de Aceitação (BDD)

Dado que quero sair do Frila, quando peço a exclusão dentro do aplicativo, então a conta deixa de aparecer na hora e é excluída em até 15 dias, sem precisar de e-mail ou site externo, como exige a diretriz 5.1.1(v) da App Store.

UC17: Denunciar e bloquear

Ator(es)

Usuário (Profissional ou Contratante); a denúncia é respondida pela Equipe Frila por e-mail

Pré-condição

O usuário está autenticado e vê o perfil ou o turno da outra parte.

Fluxo Principal

1. O usuário toca em “Denunciar” no perfil ou no turno da outra parte.

1. O usuário escolhe o motivo (assédio, discriminação, risco à segurança ou outro) e descreve o caso.

1. O sistema registra a denúncia, envia à Equipe Frila e mostra o prazo de resposta: até 5 dias úteis.

1. O sistema oferece bloquear a outra parte.

1. A Equipe Frila apura e responde por e-mail.

Fluxo Alternativo

1a. O usuário só quer bloquear: toca em “Bloquear”, e o bloqueio vale na hora, sem denúncia.

4a. Com o bloqueio, as partes não voltam a se cruzar: o profissional não recebe notificação nem vê vagas do estabelecimento, o estabelecimento não recebe candidatura dele, e o perfil de um deixa de aparecer para o outro (decisão de 30/09, a implementar).

5a. A denúncia grave é confirmada (assédio, ou fraude e documento falso, que chegam pelo motivo “outro”): o perfil denunciado é suspenso, com motivo registrado e direito de contestar (UC15); os turnos futuros dele são cancelados, a contraparte é avisada e as posições são reabertas (RN13).

5b. Há risco imediato: o app mostra atalhos para o 190 e o 180, sem esperar a resposta da Equipe Frila.

5c. A denúncia é sobre uma vaga com conteúdo impróprio: a Equipe Frila pode ocultá-la até revisar, sem cancelar turnos confirmados; a vaga sai da lista e do despacho, e o estabelecimento vê que ela foi ocultada.

Pós-condição

Denúncia registrada e respondida no prazo, e bloqueio em vigor quando pedido.

Regras Relacionadas

RN05, RN13, RN15

Critério de Aceitação (BDD)

Dado que sofri assédio num turno, quando denuncio e bloqueio a outra parte, então a denúncia chega à Equipe Frila com prazo de resposta de até 5 dias úteis, e a outra parte deixa de aparecer para mim, e eu para ela, em notificações, listas, candidaturas e no perfil, na hora. É o mecanismo que a diretriz 1.2 da App Store exige.

6.2 Diagrama de Banco de Dados (DER)

O eixo do modelo é uma cadeia só — vaga → posição → turno → avaliação —, o ciclo de vida de uma unidade de trabalho da publicação à reputação. Despacho, notificação e candidatura penduram-se nela como o registro de quem foi chamado e quem respondeu. As vistas abaixo são do mesmo esquema: separá-las evita o emaranhado de linhas que um único desenho com dezoito entidades produz.

Figura 4 — O ciclo de uma vaga: da publicação à avaliação

Figura 5 — Cada conta com um perfil só (RN25)

Figura 6 — O que decide quem recebe a notificação

Figura 7 — Os estados de uma posição e as transições válidas

A tabela descreve as dezoito entidades de domínio. O banco implementado, nas migrações de frila-backend, tem também a tabela associativa profissional_funcao, duas tabelas de operação (entrada_demonstracao e pedido_de_exclusao) e tabelas auxiliares num schema que a API não expõe; a Modelagem de Banco de Dados lista todas.

Descrição das Entidades Principais

Entidade

Descrição

Atributos Principais

Relacionamentos

Usuario

Conta de acesso, com um perfil só, profissional ou contratante (RN25). A entrada é por código no e-mail, a credencial fica no Supabase Auth e o id é o mesmo da conta de autenticação. O e-mail é único entre as contas não anonimizadas; o telefone, não.

id, perfil, nome, telefone, email, nascimento, estado, termos_versao, termos_aceite_em, demonstracao, criado_em, anonimizado_em

1:1 com Profissional, na conta de profissional; N:N com Estabelecimento via MembroEstabelecimento, na conta de contratante

Profissional

Perfil de quem executa turnos.

id, usuario_id, perfil, ponto_base, taxa_comparecimento, turnos_realizados, aval_positivas, aval_total

1:1 com Usuario; N:N com Funcao; 1:N com Disponibilidade e Candidatura; alvo de Avaliacao

Estabelecimento

Contratante de qualquer setor: bar, restaurante, buffet, produtora, loja, residência ou outro negócio.

id, nome, documento, tipo, endereco, regiao_administrativa, ponto, aval_positivas, aval_total, criado_em

1:N com Vaga e EquipeConfianca; N:N com Usuario via MembroEstabelecimento

MembroEstabelecimento

Vínculo entre um usuário e um estabelecimento, com papel.

id, usuario_id, estabelecimento_id, papel, criado_em

N:1 com Usuario; N:1 com Estabelecimento

Funcao

Catálogo de funções operacionais (garçom, bartender, chapeiro, montador, repositor…).

id, nome, categoria, ativo

N:N com Profissional; 1:N com Vaga

Vaga

Turno publicado por um estabelecimento.

id, estabelecimento_id, publicado_por, funcao_id, inicio_em, fim_em, local, regiao_administrativa, ponto, valor_centavos, posicoes, inclui_refeicao, inclui_transporte, exige_material_proprio, responsavel_local, traje, participa_rateio, observacoes, modo, alerta_antecedencia, estado, rodada_despacho, publicado_em, chave_cliente

N:1 com Estabelecimento e Funcao; 1:N com Posicao e Despacho

Posicao

Unidade preenchível de uma vaga. Uma vaga de 4 garçons tem 4 posições.

id, vaga_id, estado, profissional_id, confirmado_em, falta, reaberta_por_atraso_de, inicio_em, fim_em

N:1 com Vaga; 1:N com Candidatura; 1:1 com Turno

Disponibilidade

Janelas em que o profissional aceita trabalhar.

id, profissional_id, dia_semana, hora_inicio, hora_fim

N:1 com Profissional

Despacho

Registro de cada vaga enviada a um profissional elegível, uma vez por rodada; a reabertura por atraso abre rodada nova.

id, vaga_id, profissional_id, notificacao_id, rodada, criado_em

N:1 com Vaga, Profissional e Notificacao

Notificacao

Cada aviso enviado a uma conta, de profissional ou de membro do estabelecimento, com um de 18 tipos. Só os avisos de vaga, com uma ou mais vagas agrupadas, contam no teto de RN23.

id, usuario_id, tipo, referencia_id, profissional_id, rodada, enviada_em, urgente, estado_entrega, entregue_em, motivo_falha

N:1 com Usuario; 1:N com Despacho

Candidatura

Manifestação de interesse de um profissional por uma posição.

id, posicao_id, profissional_id, criada_em, estado

N:1 com Posicao; N:1 com Profissional

Turno

Execução efetiva de uma posição confirmada.

id, posicao_id, checkin_em, checkin_tipo, checkin_distancia_m, checkin_confirmado_em, checkout_em, checkout_distancia_m, a_caminho_em, verificacao, valor_acordado_centavos

1:1 com Posicao; 1:N com Avaliacao

Avaliacao

Resposta binária de um lado sobre o outro, após turno com presença verificada: uma por turno e por lado.

id, turno_id, autor_id, alvo_tipo, alvo_id, resposta, criada_em

N:1 com Turno

EquipeConfianca

Profissionais que recebem as vagas do estabelecimento mesmo além de 15 km.

estabelecimento_id e profissional_id (chave composta), adicionado_em

N:1 com Estabelecimento; N:1 com Profissional

Evento

Agrupamento de vagas de um mesmo evento, para escala em lote.

id, estabelecimento_id, nome, data, local

N:1 com Estabelecimento; 1:N com Vaga

Ocorrencia

Registro de cancelamento, suspensão, contestação, suporte, denúncia ou pedido de revisão do despacho.

id, tipo, turno_id, posicao_id, usuario_id, estabelecimento_id, autor_id, motivo, relato, criada_em, resultado, resolvido_em, chave_cliente

N:1 com Posicao, Turno, Usuario e Estabelecimento

Bloqueio

Bloqueio entre duas partes: impede que voltem a se cruzar.

id, autor_id, bloqueado_id, criado_em

N:1 com Usuario (autor e bloqueado)

Dispositivo

Token de push (FCM) de cada aparelho do usuário. Sem ele, a notificação não tem destino.

id, usuario_id, token_fcm, plataforma, atualizado_em

N:1 com Usuario

6.3 Diagrama de Classes

A regra de dependência vale em toda seta: o domínio é alvo de todas e origem de nenhuma. Quando precisa falar com o mundo, declara um protocolo e espera que alguém o implemente — é o que permite testar despacho, elegibilidade e reputação sem rede, sem interface e sem simulador. As regras que precisam valer igual nos três clientes são garantidas no backend (Seção 6.4): DespachoService, NotificacaoService e ElegibilidadeSpec são a especificação dessas funções e não têm classe no app. O domínio do app cuida das regras de tela, e o Diagrama de Classe mostra a correspondência entre o desenho e os nomes do código em frila-frontend/iOS.

Figura 8 — A regra de dependência entre as camadas

Figura 9 — Camada de domínio: entidades e serviços

Figura 10 — Portas e implementações: produção e teste

Figura 11 — Camada de apresentação

Descrição das Classes Principais

Classe

Responsabilidade

Atributos Principais

Métodos Principais

Vaga

Representar o turno publicado e seu estado.

id: UUID, funcao: Funcao, periodo: Periodo, local: Local, valor: Dinheiro, inclusos: Inclusos, responsavelLocal: String, modo: ModoPreenchimento, alertaAntecedencia: TimeInterval, posicoes: [Posicao]

posicoesAbertas(): [Posicao], estaNaJanelaCritica(): Bool, aceitaModoSelecao(): Bool, encerrar(): Void

Posicao

Controlar o preenchimento de uma unidade da vaga.

id: UUID, estado: EstadoPosicao, profissional: Profissional?, candidaturas: [Candidatura]

confirmar(_: Profissional) -> ResultadoConfirmacao, reabrir(motivo: String) -> Ocorrencia

Profissional

Guardar perfil, elegibilidade e reputação de quem executa.

id: UUID, funcoes: [Funcao], pontoBase: Coordenada, disponibilidades: [Disponibilidade], reputacao: Reputacao

— (quem decide a elegibilidade é o backend)

Estabelecimento

Representar o contratante e sua equipe.

id: UUID, nome: String, endereco: Local, membros: [Membro], equipeConfianca: [Profissional]

publicar(_: Vaga) throws, incluirNaEquipe(_: Profissional): Void

Turno

Registrar o check-in, o check-out e a presença.

id: UUID, posicao: Posicao, checkin: RegistroDePresenca?, checkout: RegistroDePresenca?, verificacao: Verificacao, valorAcordado: Dinheiro

registrarCheckin(distanciaMetros: Double?, em: Date): Void, confirmarCheckinManual(por: Ator): Void, registrarCheckout(distanciaMetros: Double?, em: Date): Void, temPresencaVerificada(): Bool

Avaliacao

Guardar a resposta binária de um lado sobre o outro.

id: UUID, turno: Turno, autor: Ator, alvo: Ator, resposta: Bool

aplicar(): Void

Reputacao

Calcular e formatar o sinal de confiança exibido.

positivas: Int, total: Int, taxaComparecimento: Double?, turnosConsiderados: Int

descricao(): String, temHistorico(): Bool

DespachoService

Especificar a seleção dos elegíveis e a notificação de uma vez, com teto e agrupamento (RN23). Roda no backend, em privado.despachar_vaga.

vaga: Vaga, distanciaMaximaKm: Double (15), tetoIntervalo: TimeInterval (30 min)

elegiveis(): [Profissional], notificar() async

NotificacaoService

Especificar o agrupamento, o envio, o acompanhamento da entrega e o reenvio. Roda no backend, na Edge Function enviar-push.

provedor: NotificacaoPort, pendentes: [Notificacao]

agrupar(_: [Vaga], para: Profissional): Notificacao, enviar(_: Notificacao) async throws, confirmarEntrega(_: UUID): Void, reenviarFalhas() async

ElegibilidadeSpec

Especificar as regras de quem pode receber uma vaga. Roda no backend, em privado.elegiveis.

distanciaMaximaKm: Double, exigeFuncao: Bool, exigeDisponibilidade: Bool

satisfaz(_: Profissional, _: Vaga): Bool

VagaRepositorio

Persistir e consultar vagas, posições e candidaturas (protocolo; VagaRepositorioHTTP em produção e VagaRepositorioEmMemoria nos testes).

fonte: FonteDeDados

salvar(_: Vaga) async throws, abertas(ordenadasPorDistanciaDe: Coordenada, filtro: FiltroVagas) async -> [Vaga], confirmar(posicao: UUID, profissional: UUID) async -> ResultadoConfirmacao

PublicarVagaViewModel

Orquestrar a tela de publicação e validar RN02.

rascunho: RascunhoVaga, erros: [CampoInvalido], estado: EstadoTela

validar(): Bool, publicar() async, carregarDeVagaAnterior(_: UUID): Void

FeedVagasViewModel

Orquestrar a lista de vagas do DF e a candidatura do profissional.

vagas: [Vaga], filtro: FiltroVagas, estado: EstadoTela

carregar() async, candidatar(a: Posicao) async

AcompanhamentoViewModel

Orquestrar, no perfil de contratante, as vagas em alerta e a confirmação de check-in manual. O Painel do gestor é web.

emAlerta: [Posicao], checkinsPendentes: [Turno]

carregar() async, confirmarCheckin(_: Turno) async

SessaoUsuario

Guardar identidade, o perfil da conta, que é fixo (RN25), e as permissões. O token fica no Keychain, nunca no objeto.

usuario: Usuario, perfil: PerfilConta, idCredencial: String

encerrar(): Void

6.4 Arquitetura

A arquitetura foi decidida em 21/09/2026. Os aplicativos são nativos: Swift e SwiftUI no iOS, Kotlin no Android, e uma versão web; a v1.0 é só iOS, e Android e web entram na v1.2. O backend é o Supabase (Postgres com PostGIS, autenticação, Edge Functions, pg_cron, pg_net e fila pgmq), escolhido pelo plano gratuito de até 50 mil usuários ativos por mês; a migração será reavaliada a partir de certa rentabilidade. O código está na organização FrilaApp do GitHub: frila-backend (branch develop) e frila-frontend (pasta iOS/).

As regras que precisam valer igual nos três clientes ficam no backend e são escritas uma vez, como funções e restrições no banco: quem recebe a notificação (RN05 e RN23), a confirmação sem duplicidade (RN19), o turno sobreposto (RN21), o check-in a até 200 m (RN22) e o fechamento do modo seleção (RN24). O despacho roda fora da requisição: publicar grava, enfileira o despacho na pgmq e responde; depois do commit, o pg_net aciona a Edge Function despachar, o pg_cron roda os lembretes, os alertas e os prazos, e o push sai pela Edge Function enviar-push. Cada app mantém o próprio domínio para a tela e para os testes.

O contrato entre os apps e o backend foi escrito antes do código (decisão B16) e está em api/openapi.yaml, no repositório frila-docs (OpenAPI 3.1; primeira versão em 22/09/2026, versão 0.2.27 em 30/09/2026). Toda mudança passa primeiro por ele, depois pelo backend e só então chega ao app. Cada operação com regra de negócio é uma função RPC do Supabase; as recusas de regra voltam com código estável, como posicao_ja_preenchida (409) e inelegivel (422), e reenviar a mesma escrita devolve o mesmo resultado.

Dentro do aplicativo iOS, as camadas são quatro:

• Apresentação: telas em SwiftUI e view models por funcionalidade, sem regra de negócio.

• Domínio: entidades, objetos de valor, reputação exibida e as portas (protocolos) que as outras camadas implementam. Não importa SwiftUI, Supabase, SwiftData nem CoreLocation, e é testável sem rede e sem interface.

• Dados: repositórios, cliente do Supabase, cache local em SwiftData e fila de ações offline.

• Infraestrutura: notificação push (FCM, que entrega no iOS via APNs), geolocalização lida no toque, mapa, keychain e telemetria.

Dependências e Pacotes

Pacote / Lib

Finalidade

SwiftUI

Produção de telas nos aplicativos iOS

Swift Concurrency (async/await, actors)

Operações assíncronas e isolamento de estado na sincronização e na fila offline

CoreLocation

Leitura da localização no momento do check-in e do check-out, nunca em segundo plano (entra na Sprint 2)

MapKit

Exibição do local do turno e da distância até ele (Sprint 2)

UserNotifications

Recebimento e apresentação das notificações de vaga (Sprint 2)

Supabase Swift (supabase-swift)

Entrada por código no e-mail e chamada das funções RPC do backend; guarda a sessão no Keychain

MetricKit e OSLog

Relatório de falhas e telemetria sem dado pessoal

Keychain Services

Armazenamento de credenciais e token de sessão

Firebase Cloud Messaging (FCM)

Push de vaga no Android e no iOS (no iOS, via APNs); o SDK entra no app na Sprint 2

SwiftData

Cache local dos turnos confirmados e fila de ações offline (exige iOS 17)

Swift Testing

Testes de unidade das regras de domínio

XCTest (XCUITest)

Testes de interface dos fluxos principais

XcodeGen

Geração do projeto Xcode a partir do project.yml

Supabase (backend)

Postgres com PostGIS, autenticação, Edge Functions, pg_cron, pg_net e pgmq: persistência, regras críticas, despacho e envio de push; testes em pgTAP

Diagrama de arquitetura

Figura 12 — Contexto: atores e dependências externas

Figura 13 — Contêineres: o app iOS (Android e web na v1.2), o Supabase e o despacho em fila

Figura 14 — A estratégia decidida para iOS, Android e web: nativo em cada plataforma, regras críticas no backend

Figura 15 — As quatro camadas dentro do aplicativo

Figura 16 — Da publicação à confirmação, com os prazos de cada etapa

Módulo 1 (obrigatório)

Nome do Módulo

Frila (iOS), aplicativo do Profissional e do Estabelecimento, em frila-frontend/iOS; bundle ID com.frila.org.app

Padrão Arquitetural

MVVM com camada de domínio isolada (Clean Architecture enxuta)

Justificativa

MVVM é o padrão idiomático de SwiftUI e mantém as telas livres de regra de negócio. A camada de domínio separada é o ponto que importa neste produto: elegibilidade, presença e reputação sustentam a tese inteira e precisam ser testáveis sem interface, sem rede e sem simulador, inclusive porque vão mudar conforme a validação de campo corrigir as hipóteses. As regras que precisam valer igual no Android e na web moram no backend. O app é dividido em quatro módulos (FrilaDominio, FrilaDados, FrilaInfraestrutura e a apresentação) e no alvo que os compõe.

Linguagem / Framework

Swift e SwiftUI

frila-frontend/iOS/

├── project.yml # projeto gerado pelo XcodeGen

├── Sources/

│ ├── App/ # composição: liga as camadas e escolhe o ambiente

│ ├── Apresentacao/ # telas SwiftUI, view models, componentes e tokens

│ ├── Dominio/ # FrilaDominio: entidades, objetos de valor e portas

│ ├── Dados/ # FrilaDados: cliente Supabase, cache SwiftData e fila offline

│ └── Infraestrutura/ # FrilaInfraestrutura: Keychain, telemetria, conexão

├── Tests/

│ ├── Unitarios/ # Swift Testing

│ └── UI/ # XCUITest

├── Contrato/ # cópia do openapi.yaml, com a soma de verificação

├── Resources/ # assets, strings pt-BR, fixtures do contrato, manifesto de privacidade

└── Configurations/ # ambientes (Local, Dev, Beta e Prod)

7. Documentação de Apoio

7.1 Matriz de Rastreabilidade Completa

RF

Descrição Resumida

RN(s) Relacionadas

RNF(s) Relacionados

UC(s) Relacionados

RF01

Cadastro e entrada do profissional por código no e-mail

RN14, RN15, RN20, RN25

RNF07, RNF08, RNF09

UC09

RF02

Cadastro do estabelecimento

RN15, RN20, RN25

RNF07, RNF08

UC10

RF03

Funções, ponto base e disponibilidade do profissional

RN05

RNF09

UC09, UC02

RF04

Publicação de vaga

RN02, RN03, RN18, RN24

RNF01, RNF09

UC01

RF05

Republicação de vaga anterior

RN02

RNF01

UC01

RF06

Notificação da vaga aos elegíveis

RN04, RN05, RN06, RN23

RNF02, RNF03, RNF11

UC02

RF07

Lista de vagas do DF

RN05, RN06

RNF01, RNF05

UC03

RF08

Candidatura sem formulário

RN03, RN21

RNF09

UC03

RF09

Modo urgência e modo seleção

RN19, RN24

RNF14

UC01, UC04

RF10

Confirmação e notificação das partes

RN10, RN19, RN21

RNF02, RNF14

UC04

RF11

Liberação do canal de contato

RN10

RNF07, RNF08

UC04

RF12

Lembrete pré-turno (24 h e 3 h)

RN10, RN15

RNF02

UC05

RF13

Check-in e check-out geolocalizados

RN11, RN12, RN18, RN22

RNF06, RNF13

UC05, UC07

RF14

Cancelamento com reabertura

RN12, RN16

RNF03, RNF13

UC08

RF15

Avaliação binária bidirecional

RN07, RN22

RNF13

UC06

RF16

Exibição de reputação e comparecimento

RN07, RN08

RNF09, RNF10

UC03, UC04, UC06

RF17

Retirado (aval externo)

—

—

— (UC12 retirado)

RF18

Equipe de confiança

RN05, RN06, RN23

RNF03

UC11, UC02

RF19

Escala de evento em lote

RN02, RN18

RNF01, RNF11

UC01

RF20

Alerta de vaga vazia e Painel do gestor

RN12, RN22, RN24

RNF12, RNF13

UC07

RF21

Múltiplos usuários por estabelecimento

RN15, RN25

RNF07

UC10

RF22

Histórico e exportação de turnos

RN11, RN17

RNF13

UC13

RF23

Suporte por e-mail

RN10, RN15

RNF12

UC14

RF24

Consulta e contestação de suspensão

RN13, RN16

RNF13

UC15

RF25

Exportação e exclusão de dados pessoais

RN15

RNF08, RNF13

UC16

RF26

Denúncia e bloqueio

RN05, RN13, RN15

RNF08, RNF13

UC17

RF27

Explicação do despacho e pedido de revisão

RN05, RN06

RNF09

UC09

RN01 (sem desconto no valor do turno) e RN09 (não processar pagamento) não aparecem vinculadas a nenhum requisito porque são restrições de produto que valem sobre o sistema inteiro e determinam o que não existe. Elas são verificadas por ausência, já que nenhum fluxo pode introduzi-las, e não por um requisito específico que as implemente. A RN20 (maioridade) aparece em RF01 e RF02, mas vale para todo cadastro, dos dois perfis. O RF17 e o UC12 foram retirados em 21/09/2026 e seguem na tabela só para preservar a numeração.