Esta seção descreve os módulos principais do Esqueceram AI, suas responsabilidades, funcionalidades, classes mais relevantes e os padrões de projeto utilizados.

O detalhamento prioriza os módulos centrais da aplicação e apresenta diagramas nos pontos em que eles são mais relevantes.

Foram escolhidos padrões que possuem aplicação direta no sistema.

Outros padrões não serão adicionados apenas para aumentar a quantidade. Novos padrões poderão ser utilizados caso exista necessidade concreta.

Controla as contas dos usuários e as informações necessárias para identificar cada participante.

• cadastrar usuário;
• realizar login e logout;
• manter sessão autenticada;
• consultar e atualizar perfil;
• controlar permissões de acesso.

Usuario, Perfil, UsuarioController, UsuarioService e UsuarioRepository.

Responsável pelo cadastro e manutenção dos objetos perdidos e encontrados. Cada registro pode conter descrição, categoria, cor, marca, modelo, localização, data, fotografia, tipo de registro e estado atual.

• cadastrar item perdido;
• cadastrar item encontrado;
• editar informações;
• consultar item;
• alterar estado;
• associar fotografia;
• informar localização;
• classificar categoria;
• encaminhar o item ao processo de Match.

Item, ItemEletronico, ItemDocumento, ItemAcessorio, ItemController, ItemService e ItemRepository.

classDiagram
    class Item {
        <<abstract>>
        +Long id
        +String descricao
        +String cor
        +String imagemUrl
        +String localizacao
        +StatusItem status
        +TipoRegistro tipoRegistro
    }
    class ItemEletronico {
        +String marca
        +String modelo
    }
    class ItemDocumento {
        +String tipoDocumento
        +String orgaoEmissor
    }
    class ItemAcessorio {
        +String material
        +String marca
    }
    class Usuario {
        +Long id
        +String nome
        +String email
    }
    class PostoColeta {
        +Long id
        +String nome
        +String endereco
    }
    class ItemRepository {
        +salvar(item)
        +buscarPorId(id)
        +buscarPorFiltros(filtros)
    }

    Item <|-- ItemEletronico
    Item <|-- ItemDocumento
    Item <|-- ItemAcessorio
    Usuario "1" --> "0..*" Item : registra
    PostoColeta "0..1" --> "0..*" Item : recebe
    ItemRepository --> Item : persiste

O Abstract Factory será utilizado para criar objetos específicos conforme a categoria do item. Um eletrônico pode possuir marca e modelo, enquanto um documento pode possuir tipo e órgão emissor.

classDiagram
    class Item {
        <<abstract>>
    }
    class ItemEletronico
    class ItemDocumento
    class ItemAcessorio
    class ItemFactory {
        <<interface>>
        +criarItem(dados) Item
    }
    class EletronicoFactory {
        +criarItem(dados) Item
    }
    class DocumentoFactory {
        +criarItem(dados) Item
    }
    class AcessorioFactory {
        +criarItem(dados) Item
    }

    Item <|-- ItemEletronico
    Item <|-- ItemDocumento
    Item <|-- ItemAcessorio
    ItemFactory <|.. EletronicoFactory
    ItemFactory <|.. DocumentoFactory
    ItemFactory <|.. AcessorioFactory
    EletronicoFactory --> ItemEletronico : cria
    DocumentoFactory --> ItemDocumento : cria
    AcessorioFactory --> ItemAcessorio : cria

• encapsula a criação dos objetos;
• reduz condicionais no código de negócio;
• facilita a inclusão de novas categorias;
• separa a responsabilidade de criação;
• reduz o acoplamento entre serviços e tipos concretos.

Permite encontrar registros de itens utilizando características fornecidas no cadastro.

• buscar por descrição;
• filtrar por categoria;
• filtrar por localização;
• filtrar por data;
• filtrar por cor;
• filtrar por marca;
• combinar filtros;
• consultar possíveis itens relacionados.

BuscaService, FiltroItem, BuscaController e ItemRepository.

A busca fornece candidatos e não deve ser considerada, sozinha, como confirmação de propriedade.

Compara características de itens perdidos e encontrados para identificar possíveis correspondências.

Podem ser consideradas características como categoria, descrição, cor, marca, modelo, localização, período aproximado e fotografia, quando disponível.

O resultado deve ser tratado como possível correspondência, e não como prova automática de propriedade.

• receber item encontrado;
• buscar itens perdidos candidatos;
• comparar características;
• calcular grau de compatibilidade;
• registrar possíveis matches;
• notificar módulos interessados;
• permitir confirmação ou recusa.

Match, MatchService, MatchController, MatchRepository e MatchObserver.

classDiagram
    class Match {
        +Long id
        +double score
        +StatusMatch status
        +Date dataCriacao
    }
    class Item {
        +Long id
        +String descricao
        +String cor
        +String marca
        +String localizacao
    }
    class MatchService {
        +procurarMatches(item)
        +calcularScore(itemA, itemB)
        +confirmarMatch(id)
        +recusarMatch(id)
    }
    class MatchRepository {
        +salvar(match)
        +buscarPorUsuario(id)
        +buscarPorId(id)
    }

    Item "1" --> "0..*" Match : participa
    MatchService --> MatchRepository : utiliza
    Match --> Item : relaciona

Responsável por informar os usuários sobre eventos relevantes. A entrega será realizada pelo Firebase Cloud Messaging.

• enviar notificação de possível match;
• informar alterações relevantes na recuperação;
• informar eventos relacionados ao item;
• manter dados necessários para o envio;
• integrar com o FCM.

NotificacaoService, NotificationObserver e FCMClient.

O módulo funciona como observador dos eventos de Match. O MatchService não precisa conhecer os detalhes de envio.

Representa os locais físicos onde itens encontrados podem ser entregues e posteriormente retirados pelos proprietários.

• cadastrar posto;
• consultar postos;
• exibir localização;
• associar item ao posto;
• registrar recebimento;
• registrar retirada.

PostoColeta, PostoColetaService, PostoColetaController e PostoColetaRepository.

Os itens não precisam ficar expostos fisicamente ao público no posto. O sistema utiliza os registros cadastrados para controlar o fluxo de entrega e retirada.

Registra benefícios associados à contribuição de usuários que encontram e entregam itens.

• atribuir pontos;
• consultar pontuação;
• registrar recompensa;
• registrar recebimento;
• associar recompensa a item recuperado.

Recompensa, Pontuacao, RecompensaService e RecompensaRepository.

Controla o processo posterior à identificação de uma possível correspondência.

• confirmar propriedade;
• recusar correspondência;
• reservar item;
• controlar estado da recuperação;
• registrar retirada;
• registrar devolução.

Recuperacao, RecuperacaoService, MatchService e PostoColetaService.

Possível Match
      ↓
Confirmação de propriedade
      ↓
Item reservado
      ↓
Retirada no posto
      ↓
Item devolvido

Um item no estado RESERVADO não deve ser disponibilizado para uma segunda reserva concorrente.

O Observer será utilizado para desacoplar o reconhecimento de um match das ações que devem ocorrer como consequência desse evento.

Depois que um match é identificado, mais de uma ação pode ocorrer:

Match identificado
       ↓
 ┌─────┴───────────┐
 ↓                 ↓
Notificação     Recompensa
 ↓                 ↓
FCM              Pontos

O MatchService não deve precisar conhecer todos os detalhes dessas ações.

classDiagram
    class MatchObserver {
        <<interface>>
        +atualizar(evento)
    }
    class NotificationObserver {
        +atualizar(evento)
    }
    class RewardObserver {
        +atualizar(evento)
    }
    class HistoryObserver {
        +atualizar(evento)
    }
    class MatchService {
        +processarMatch()
        +notificarObservers(evento)
    }

    MatchObserver <|.. NotificationObserver
    MatchObserver <|.. RewardObserver
    MatchObserver <|.. HistoryObserver
    MatchService --> MatchObserver : notifica

MatchService
      ↓
Evento MatchIdentificado
      ↓
 ┌──────────────┬───────────────┬──────────────┐
 ↓              ↓               ↓
Notification   Reward          History
Observer       Observer        Observer
 ↓              ↓               ↓
FCM            Pontos          Histórico

• reduz acoplamento;
• facilita inclusão de novas reações;
• favorece separação de responsabilidades;
• facilita integrações externas;
• melhora a extensibilidade do Match.

O cenário representa o processo em que uma pessoa registra um item encontrado e o sistema verifica possíveis itens perdidos compatíveis.

sequenceDiagram
    actor Encontrador
    actor Proprietario
    participant Web as Aplicação Web
    participant API as ItemController
    participant ItemService as ItemService
    participant MatchService as MatchService
    participant Repo as ItemRepository
    participant DB as PostgreSQL
    participant Storage as Firebase Storage
    participant Observer as NotificationObserver
    participant FCM as Firebase FCM

    Encontrador->>Web: Cadastra item encontrado
    Web->>API: POST /api/itens
    API->>ItemService: registrarItem(dados)
    ItemService->>Storage: upload da fotografia (se informada)
    Storage-->>ItemService: storage_path
    ItemService->>Repo: salvar(item)
    Repo->>DB: INSERT item
    DB-->>Repo: Item salvo
    Repo-->>ItemService: Item
    ItemService->>MatchService: procurarMatches(item)
    MatchService->>Repo: buscarItensPerdidos()
    Repo->>DB: SELECT candidatos
    DB-->>Repo: Lista de candidatos
    Repo-->>MatchService: Candidatos
    MatchService->>MatchService: calcularScore()

    alt Match encontrado
        MatchService->>Repo: salvarMatch()
        Repo->>DB: INSERT match
        MatchService->>Observer: MatchIdentificado
        Observer->>FCM: enviarNotificacao()
        FCM-->>Proprietario: Nova possível correspondência
    else Nenhum match
        MatchService-->>ItemService: Nenhuma correspondência
    end

    ItemService-->>API: Resultado
    API-->>Web: JSON

    Proprietario->>Web: Confirma propriedade
    Web->>API: POST /api/matches/{id}/confirmar
    API->>MatchService: confirmarMatch(id)
    MatchService->>Repo: reservarItem(id)
    Repo->>DB: UPDATE status = RESERVADO