Pular para conteúdo

US2.5

Busca e Filtro de Vagas para Estudantes (RF08)

História de Usuário

Como estudante, quero visualizar e filtrar vagas de voluntariado para encontrar oportunidades alinhadas ao meu interesse e disponibilidade.

Rastreabilidade

Item Código / Referência
User Story US2.5
Requisito Funcional RF08 — Buscar vaga
Característica de Produto CP02 — Ciclo de Vagas e Engajamento
Requisitos Não-Funcionais RNF04 (responsivo iOS/Android), RNF05 (busca ≤3s)
Release Planejada R2 — Perfis e Conexão

Descrição

Implementar a tela inicial de oportunidades do estudante (feed), conforme protótipo Figma. A tela é o primeiro ponto de contato do estudante com as vagas e deve exibir:

  • Saudação personalizada e resumo do perfil (horas acumuladas, inscrições ativas, vagas salvas).
  • Meta de extensão do estudante com barra de progresso.
  • Barra de busca por palavras-chave (tema, ONG, local) e acesso a filtros avançados.
  • Lista horizontal de categorias/áreas de atuação com contador de vagas por categoria.
  • Lista vertical de cards de oportunidades, com destaque para a vaga em evidência, indicador de vagas preenchidas e botão de candidatura.
  • Navegação inferior principal (Explorar, Salvos, Inscrições, Perfil).

Fonte da verdade: o protótipo Figma (mobile e desktop) define a estrutura, hierarquia visual, cores, tipografia e comportamentos desta funcionalidade. Esta documentação foi atualizada para refletir o protótipo.

Critérios de Aceite (BDD / Gherkin)

Cenário 1: Exibição do resumo do perfil no topo

Dado que o estudante está autenticado
Quando acessa a tela inicial de oportunidades
Então o sistema exibe a saudação personalizada com o nome do estudante e um resumo com as horas de extensão acumuladas, a quantidade de inscrições ativas e a quantidade de vagas salvas

Cenário 2: Exibição da meta de extensão

Dado que o estudante possui meta de extensão configurada no perfil
Quando acessa a tela inicial de oportunidades
Então o sistema exibe o percentual de progresso da meta e quantas horas faltam para atingi-la

Cenário 3: Busca por palavra-chave

Dado que existem vagas ativas publicadas
Quando o estudante digita um termo na barra de busca e submete
Então o sistema retorna apenas as vagas cujo título, descrição, categoria, organização ou local correspondam ao termo informado

Cenário 4: Filtro rápido por categoria

Dado que existem vagas publicadas em diferentes categorias
Quando o estudante seleciona uma categoria no carrossel de filtros
Então o sistema aplica o filtro e exibe apenas as vagas daquela categoria, atualizando o contador de resultados

Cenário 5: Filtros avançados

Dado que o estudante deseja refinar a busca
Quando acessa os filtros avançados
Então o sistema apresenta opções adicionais de filtro, como carga horária, localização e data

Cenário 6: Listagem de vagas "Para você"

Dado que existem oportunidades publicadas
Quando o estudante visualiza a listagem principal
Então o sistema exibe as vagas com título, organização, categoria, carga horária, local ou data, quantidade de vagas preenchidas em relação ao total e ação para se candidatar

Cenário 7: Vaga em destaque

Dado que existe uma oportunidade marcada como destaque
Quando o estudante visualiza a listagem
Então o sistema exibe essa vaga destacada das demais e identifica visualmente que ela está salva ou não pelo estudante

Cenário 8: Salvar/remover vaga dos salvos

Dado que o estudante visualiza uma oportunidade
Quando alterna o estado de salvamento da vaga
Então o sistema atualiza a lista de vagas salvas do estudante e reflete a alteração no contador correspondente

Cenário 9: Candidatar-se a uma vaga

Dado que o estudante visualiza uma oportunidade ativa com vagas disponíveis
Quando inicia a candidatura
Então o sistema direciona o estudante para o fluxo de candidatura e, se já existir uma candidatura, exibe o status atual

Cenário 10: Navegação principal

Dado que o estudante está na tela de oportunidades
Quando visualiza a navegação principal
Então o sistema permite acessar as seções Explorar, Salvos, Inscrições e Perfil, exibindo as respectivas contagens quando aplicável

Cenário 11: Estado vazio

Dado que não existem vagas publicadas ou nenhuma corresponde aos filtros selecionados
Quando o estudante acessa ou filtra a listagem
Então o sistema exibe uma mensagem informando que não há oportunidades e oferece uma ação para limpar filtros ou voltar à listagem completa

Cenário 12: Filtro por modalidade

Dado que existem vagas de diferentes modalidades (presencial, remoto e híbrido)
Quando o estudante filtra a listagem por uma modalidade (ex.: remoto)
Então o sistema exibe apenas as vagas correspondentes à modalidade selecionada

Regras de Negócio

  • Apenas oportunidades com status published e inscrições abertas devem aparecer no feed.
  • A ordenação padrão da lista "Para você" deve privilegiar vagas em destaque primeiro e, em seguida, a data de publicação (mais recentes primeiro).
  • Cada categoria deve exibir um contador com o número de vagas disponíveis naquela categoria.
  • O contador total de oportunidades deve refletir o resultado atual, considerando filtros ativos.
  • As categorias disponíveis no protótipo são: Todas, Educação, Saúde, Tecnologia, Meio Ambiente e Social (Assistência Social).
  • Cada categoria possui cor identificadora própria (conforme tokens do Figma):
  • Educação: azul (#1d5faa)
  • Saúde: verde (#1d7a4a)
  • Tecnologia: roxo (#6c3fc4)
  • Meio Ambiente: verde-escuro (#2e7d32)
  • Assistência Social: vermelho (#c0392b)
  • O indicador de vagas deve mostrar "X de Y" (vagas preenchidas do total) e uma barra de progresso visual.
  • O botão de candidatura deve ficar desabilitado ou alterar o texto quando a vaga estiver esgotada ou já tiver candidatura do estudante.
  • A navegação inferior deve refletir contagens reais: inscrições ativas e vagas salvas do estudante autenticado.
  • A meta de extensão exibida deve vir do perfil acadêmico do estudante (StudentProfile.horas_extensao_exigidas e horas já registradas).

Requisitos Técnicos

  • Backend:
  • Endpoint GET /api/v1/opportunities/ com filtros por search, area, featured, location, workload_max e ordenação.
  • Endpoint GET /api/v1/students/dashboard/ (ou similar) para retornar resumo do estudante: horas acumuladas, inscrições ativas, vagas salvas, meta de extensão e progresso.
  • Endpoint POST /api/v1/opportunities/{id}/save/ e DELETE /api/v1/opportunities/{id}/save/ para salvar/remover vaga dos favoritos (ou equivalente no app de oportunidades).
  • Otimização com select_related/prefetch_related e índices em campos de busca frequentes (title, description, area, status).
  • Utilizar django-filter + SearchFilter do DRF para composição de filtros.
  • Frontend (React Native + Expo):
  • Tela StudentHome / OpportunitiesScreen consumindo os endpoints acima.
  • Componentes reutilizáveis: OpportunityCard, CategoryPill, SearchBar, BottomNav, StatsCard, ProgressBar.
  • Barra de busca com debounce de 300ms.
  • Lista de categorias como FlatList horizontal.
  • Lista de vagas como FlatList vertical com scroll infinito/paginação.
  • Design tokens centralizados (src/theme/) para cores, tipografia e espaçamento, garantindo fidelidade 1:1 ao Figma.
  • Responsividade entre iOS e Android (RNF04).
  • Performance:
  • Tempo de resposta da busca ≤3s (RNF05).
  • Lazy loading de imagens/ícones dos cards.
  • Testes:
  • Backend: pytest cobrindo filtros, ordenação por destaque, contadores de categoria, salvamento de vaga e endpoint de resumo.
  • Frontend: Jest + RNTL para renderização dos cards, filtros, estados vazios e navegação inferior.

Referências de Design

Fonte da verdade: os protótipos abaixo definem a experiência desta issue.

  • Protótipo Figma (Mobile — Oportunidades | Liaison): https://www.figma.com/design/f6bQuVohTvZLF5WWPEbNob/Liaison?node-id=32-2&t=s8sAfL2P1EwyHsQ2-0

Dependências

  • Relacionada a: #19 (Criação de Vagas — RF18/US2.1), #51 (Publicação de Vagas — RF20/US2.3)
  • Bloqueada por: #19 (RF18 — Criar oportunidade), #51 (RF20 — Publicar oportunidade), #15 (Gerenciar perfil do estudante — RF04/US1.4, para resumo de horas/meta)
  • Bloqueia: #21 (Visualização de Detalhes da Vaga — RF09/US2.6), #22 (Candidatura — RF10/US2.7)

Notas

  • ICE Score: I=9 C=6 E=3 = 162 | MoSCoW: Must | Quadrante: Plan
  • Esta issue foi atualizada após a criação do protótipo Figma. O protótipo é a fonte da verdade para estrutura visual, conteúdo e comportamentos; esta documentação deve ser mantida sincronizada com futuras alterações no Figma.
  • O escopo de "filtros avançados" pode ser fatiado em uma sub-issue se o esforço crescer; para esta issue, basta o acesso ao painel de filtros e filtros básicos funcionando.
  • O badge de notificações no header faz parte de outra funcionalidade (notificações — não mapeada como RF no MVP), mas seu posicionamento visual está definido no protótipo.

Definição de Preparado (DoR)

Item de Verificação (Universal) Evidência / Rastreabilidade Situação
A história está bem descrita e com critérios de aceite? Documentada e alinhada com o escopo do MVP. ✔ Sim
Possui protótipos de interface necessários? Interface mapeada e disponível no Figma da equipe. ✔ Sim
A história é independente o suficiente para ser entregue? Cadeia de dependências resolvida (vide Matriz MVP). ✔ Sim
Foi estimada pela equipe? Estimada utilizando o método ICE Score. ✔ Sim

Definição de Pronto (DoD)

Pergunta Fundamental (Universal) Evidência de Implementação Status
O código foi implementado e revisado? Pull Request aprovado e fundido na branch principal. ✔ Sim
Coerente com o protótipo validado? O layout segue os componentes e tokens de design. ✔ Sim
Passou nos testes necessários? Testes (unitários/integração) executados e aprovados. ✔ Sim
A documentação está atualizada? Atualizada no repositório de requisitos. ✔ Sim

Critérios de Aceitação (CA)

  • Saudação personalizada: Ao abrir a tela de oportunidades, o estudante vê seu nome, total de horas acumuladas, quantidade de inscrições ativas e vagas salvas.
  • Meta de extensão: O progresso da meta de horas de extensão aparece com percentual e quantas horas faltam.
  • Busca por palavra-chave: O estudante digita um termo e vê apenas as vagas cujo título, descrição, categoria, organização ou local correspondem ao que foi buscado.
  • Filtro rápido por categoria: Ao selecionar uma categoria (ex.: Educação, Saúde, Tecnologia), apenas as vagas daquela categoria são exibidas.
  • Filtros avançados: O estudante acessa opções adicionais de filtro como carga horária, localização e data.
  • Lista de vagas: As vagas são exibidas com título, organização, categoria, carga horária, local/data e quantidade de vagas preenchidas (ex.: "3 de 10").
  • Vaga em destaque: Vagas marcadas como destaque aparecem com visual diferenciado na lista.
  • Salvar/remover vaga: O estudante consegue marcar/desmarcar uma vaga como favorita — a contagem de vagas salvas é atualizada na hora.
  • Candidatura direta: A partir da lista, o estudante consegue iniciar a candidatura a uma vaga ativa. Se já tiver se candidatado, o status atual é exibido.
  • Navegação inferior: A barra de navegação (Explorar, Salvos, Inscrições, Perfil) é sempre visível com contagens reais.
  • Lista vazia: Se não houver vagas ou nenhuma corresponder ao filtro, o sistema exibe mensagem informativa com opção para limpar os filtros.

Acesso & Evidência

  • Código Homologado: Repositório Principal
  • Status de Conclusão: 100% Entregue (conforme Matriz de Completude).