5. Regras Arquiteturais

5.1 Regra de acesso ao banco

O cliente nunca acessa diretamente o PostgreSQL.

Cliente → API → Service → Repository → PostgreSQL

5.2 Regra dos Controllers

Controllers recebem requisições, realizam validações básicas, delegam o processamento aos Services e retornam respostas HTTP/JSON.

As regras centrais de negócio não devem ficar concentradas nos Controllers.

5.3 Regra dos Services

Services concentram as regras de negócio e coordenam os módulos.

5.4 Regra dos Repositories

Repositories são responsáveis pela comunicação com o PostgreSQL.

5.5 Regra de imagens

Fotografias devem ser armazenadas no Firebase Storage. O PostgreSQL mantém os metadados do item e o caminho do objeto no bucket. O upload deve ser realizado pelo backend por meio do Firebase Admin SDK; credenciais de serviço não podem ser expostas ao cliente.

O backend deve validar tipo e tamanho do arquivo, usar nomes de objetos únicos e definir uma compensação caso o upload seja concluído, mas a persistência do item falhe. O bucket não deve ser tornado público indiscriminadamente.

5.6 Regra de notificações

O MatchService publica o evento de Match. O módulo de notificações reage ao evento utilizando Observer e FCM.

5.7 Regra de estados

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

Fluxo esperado:

PERDIDO / ENCONTRADO
          ↓
        MATCH
          ↓
      RESERVADO
          ↓
       DEVOLVIDO

---