feat: implementa leitura de eventos

src/application/create-app.ts

@@ -60,6 +60,7 @@ export function createApp({
   const routes: Route[] = [
     ...createPaisRoutes(knex),
     ...createEstadoRoutes(knex),
+    ...createEventoRoutes(knex),
     ...createFaseSucessionalRoutes(knex),
     ...createVegetacaoRoutes(knex),
     ...createEventoRoutes(knex),

src/application/evento/BuscarEventoController.ts

@@ -0,0 +1,51 @@
+import { BuscarEventoPorIdUseCase } from '@/domain/evento/BuscarEventoPorIdUseCase'
+import {
+  HttpRequest, HttpResponse, StatusCode
+} from '@/library/http/common'
+import { BadRequestError } from '@/library/http/error/BadRequestError'
+import { HttpError } from '@/library/http/error/HttpError'
+import { InternalServerError } from '@/library/http/error/InternalServerError'
+import { NotFoundError } from '@/library/http/error/NotFoundError'
+import { NextHandler, RequestHandler } from '@/library/http/Server'
+
+interface Dependencies {
+  buscarEventoPorIdUseCase: BuscarEventoPorIdUseCase
+}
+
+export class BuscarEventoController implements RequestHandler {
+  private readonly buscarEventoPorIdUseCase: BuscarEventoPorIdUseCase
+
+  constructor(dependencies: Dependencies) {
+    this.buscarEventoPorIdUseCase = dependencies.buscarEventoPorIdUseCase
+  }
+
+  async handle(request: HttpRequest, _next: NextHandler): Promise<HttpResponse | HttpError> {
+    const { eventoId } = request.params as { eventoId?: string }
+
+    if (
+      eventoId === undefined
+      || eventoId === null
+      || eventoId === ''
+      || !/^\d+$/.test(eventoId)
+    ) {
+      return new BadRequestError({ message: 'eventoId inválido' })
+    }
+
+    const result = await this.buscarEventoPorIdUseCase.execute({
+      id: Number(eventoId)
+    })
+
+    if (result.left()) {
+      return new InternalServerError({ message: result.value.message })
+    }
+
+    if (!result.value) {
+      return new NotFoundError({ message: 'Evento não encontrado' })
+    }
+
+    return {
+      statusCode: StatusCode.Ok,
+      body: result.value
+    }
+  }
+}

src/application/evento/ListaEventosController.ts

@@ -0,0 +1,72 @@
+import { EventoTipo } from '@/domain/evento/Evento'
+import { ListaEventosUseCase } from '@/domain/evento/ListaEventosUseCase'
+import {
+  HttpRequest, HttpResponse, StatusCode
+} from '@/library/http/common'
+import { BadRequestError } from '@/library/http/error/BadRequestError'
+import { HttpError } from '@/library/http/error/HttpError'
+import { InternalServerError } from '@/library/http/error/InternalServerError'
+import { NextHandler, RequestHandler } from '@/library/http/Server'
+
+interface Dependencies {
+  listaEventosUseCase: ListaEventosUseCase
+}
+
+export class ListaEventosController implements RequestHandler {
+  private readonly listaEventosUseCase: ListaEventosUseCase
+
+  constructor(dependencies: Dependencies) {
+    this.listaEventosUseCase = dependencies.listaEventosUseCase
+  }
+
+  async handle(request: HttpRequest, _next: NextHandler): Promise<HttpResponse | HttpError> {
+    const {
+      expedicaoId,
+      tipo,
+      capturado_de,
+      capturado_ate,
+      limite,
+      pagina
+    } = request.params as {
+      expedicaoId?: string
+      tipo?: string
+      capturado_de?: string
+      capturado_ate?: string
+      limite?: string
+      pagina?: string
+    }
+
+    if (
+      expedicaoId === undefined
+      || expedicaoId === null
+      || expedicaoId === ''
+      || !/^\d+$/.test(expedicaoId)
+    ) {
+      return new BadRequestError({ message: 'expedicaoId inválido' })
+    }
+
+    const filters = {
+      expedicao_id: Number(expedicaoId),
+      ...(limite && !Number.isNaN(Number(limite))
+        ? { limite: Number(limite) }
+        : {}),
+      ...(pagina && !Number.isNaN(Number(pagina))
+        ? { pagina: Number(pagina) }
+        : {}),
+      ...(tipo ? { tipo: tipo as EventoTipo } : {}),
+      ...(capturado_de ? { capturado_de: new Date(capturado_de) } : {}),
+      ...(capturado_ate ? { capturado_ate: new Date(capturado_ate) } : {})
+    }
+
+    const result = await this.listaEventosUseCase.execute(filters)
+
+    if (result.left()) {
+      return new InternalServerError({ message: result.value.message })
+    }
+
+    return {
+      statusCode: StatusCode.Ok,
+      body: result.value
+    }
+  }
+}

src/application/evento/index.ts

@@ -1,20 +1,35 @@
 import { type Knex } from 'knex'
 
 import { AtualizarEventoUseCase } from '@/domain/evento/AtualizarEventoUseCase'
+import { BuscarEventoPorIdUseCase } from '@/domain/evento/BuscarEventoPorIdUseCase'
 import { CriarEventoUseCase } from '@/domain/evento/CriarEventoUseCase'
+import { ListaEventosUseCase } from '@/domain/evento/ListaEventosUseCase'
 import { RemoverEventoUseCase } from '@/domain/evento/RemoverEventoUseCase'
 import { EventoCollectionKnexAdapter } from '@/infrastructure/EventoCollectionKnexAdapter'
 import { Method } from '@/library/http/common'
 import { Route } from '@/library/http/Router'
 
 import { AtualizarEventoController } from './AtualizarEventoController'
+import { BuscarEventoController } from './BuscarEventoController'
 import { CriarEventoController } from './CriarEventoController'
+import { ListaEventosController } from './ListaEventosController'
 import { RemoverEventoController } from './RemoverEventoController'
 
 export function routes(knex: Knex): Route[] {
   const eventoCollection = new EventoCollectionKnexAdapter({ knex })
 
+  // TODO: adicionar autenticação quando a camada HTTP de autenticação estiver disponível.
+
   return [
+    {
+      handlers: [
+        new ListaEventosController({
+          listaEventosUseCase: new ListaEventosUseCase({ eventoCollection })
+        })
+      ],
+      method: Method.Get,
+      path: '/v2/expedicoes/:expedicaoId/eventos'
+    },
     {
       handlers: [
         new CriarEventoController({
@@ -24,6 +39,15 @@ export function routes(knex: Knex): Route[] {
       method: Method.Post,
       path: '/v2/expedicoes/:expedicaoId/eventos'
     },
+    {
+      handlers: [
+        new BuscarEventoController({
+          buscarEventoPorIdUseCase: new BuscarEventoPorIdUseCase({ eventoCollection })
+        })
+      ],
+      method: Method.Get,
+      path: '/v2/eventos/:eventoId'
+    },
     {
       handlers: [
         new AtualizarEventoController({

src/domain/evento/BuscarEventoPorIdUseCase.ts

@@ -0,0 +1,20 @@
+import { Either } from '@/library/either/Either'
+
+import { Attributes } from './Evento'
+import { EventoCollection } from './EventoCollection'
+
+interface Dependencies {
+  eventoCollection: EventoCollection
+}
+
+export class BuscarEventoPorIdUseCase {
+  private readonly eventoCollection: EventoCollection
+
+  constructor(dependencies: Dependencies) {
+    this.eventoCollection = dependencies.eventoCollection
+  }
+
+  execute({ id }: { id: number }): Promise<Either<Error, Attributes | null>> {
+    return this.eventoCollection.findById(id)
+  }
+}

src/domain/evento/EventoCollection.ts

@@ -15,6 +15,15 @@ export interface EventoFilters {
   capturado_de?: Date
   capturado_ate?: Date
   order?: EventoOrder
+  limite?: number
+  pagina?: number
+}
+
+export interface Paginated<T> {
+  itens: T[]
+  total: number
+  limite: number
+  pagina: number
 }
 
 export interface AtualizarEventoAttributes {
@@ -29,7 +38,7 @@ export interface AtualizarEventoAttributes {
 }
 
 export interface EventoCollection {
-  findAll(filters: EventoFilters): Promise<Either<Error, Attributes[]>>
+  findAll(filters: EventoFilters): Promise<Either<Error, Paginated<Attributes>>>
   findById(id: number): Promise<Either<Error, Attributes | null>>
   create(attributes: CreateAttributes): Promise<Either<Error, Attributes>>
   update(id: number, attributes: AtualizarEventoAttributes): Promise<Either<Error, Attributes | null>>

src/domain/evento/ListaEventosUseCase.ts

@@ -0,0 +1,22 @@
+import { Either } from '@/library/either/Either'
+
+import { Attributes } from './Evento'
+import {
+  EventoCollection, EventoFilters, Paginated
+} from './EventoCollection'
+
+interface Dependencies {
+  eventoCollection: EventoCollection
+}
+
+export class ListaEventosUseCase {
+  private readonly eventoCollection: EventoCollection
+
+  constructor(dependencies: Dependencies) {
+    this.eventoCollection = dependencies.eventoCollection
+  }
+
+  execute(filters: EventoFilters): Promise<Either<Error, Paginated<Attributes>>> {
+    return this.eventoCollection.findAll(filters)
+  }
+}

src/infrastructure/EventoCollectionKnexAdapter.ts

@@ -4,7 +4,7 @@ import {
   Attributes, COLETA_FIELDS, ColetaAttributes, CreateAttributes, EventoTipo
 } from '@/domain/evento/Evento'
 import {
-  AtualizarEventoAttributes, EventoCollection, EventoFilters
+  AtualizarEventoAttributes, EventoCollection, EventoFilters, Paginated
 } from '@/domain/evento/EventoCollection'
 import { Either } from '@/library/either/Either'
 
@@ -106,7 +106,7 @@ export class EventoCollectionKnexAdapter implements EventoCollection {
       ])
   }
 
-  async findAll(filters: EventoFilters): Promise<Either<Error, Attributes[]>> {
+  async findAll(filters: EventoFilters): Promise<Either<Error, Paginated<Attributes>>> {
     try {
       const query = this.select()
 
@@ -126,11 +126,28 @@ export class EventoCollectionKnexAdapter implements EventoCollection {
         query.where('eventos.capturado_em', '<=', filters.capturado_ate)
       }
 
-      const order = filters.order ?? { column: 'capturado_em' as const, direction: 'desc' as const }
-      query.orderBy(`eventos.${order.column}`, order.direction)
+      const countQuery = query.clone()
+
+      const countRows = await countQuery
+        .clearSelect()
+        .count<Array<{ count: string }>>('* as count')
+      const [{ count }] = countRows
+
+      const limite = filters.limite && filters.limite > 0 ? filters.limite : 20
+      const pagina = filters.pagina && filters.pagina > 0 ? filters.pagina : 1
+      const offset = (pagina - 1) * limite
+
+      query.orderBy('eventos.capturado_em', 'desc')
+      query.orderBy('eventos.id', 'desc')
+      query.limit(limite).offset(offset)
 
       const rows = await query as Array<Row & Record<string, unknown>>
-      return Either.right(rows.map(toAttributes))
+      return Either.right({
+        itens: rows.map(toAttributes),
+        total: Number(count),
+        limite,
+        pagina
+      })
     } catch (error) {
       return Either.left(new CollectionError({ message: 'Failed to list eventos', cause: error }))
     }

test/integration/evento/evento-collection.test.ts

@@ -168,7 +168,7 @@ describe('EventoCollectionKnexAdapter', () => {
       expect(found.right()).toBe(true)
       if (!found.right()) return
 
-      expect(found.value.map(evento => evento.id)).toEqual([tarde.value.id, cedo.value.id])
+      expect(found.value.itens.map(evento => evento.id)).toEqual([tarde.value.id, cedo.value.id])
     } finally {
       await knex('eventos').whereIn('id', [cedo.value.id, tarde.value.id]).delete()
     }
@@ -186,13 +186,58 @@ describe('EventoCollectionKnexAdapter', () => {
       expect(found.right()).toBe(true)
       if (!found.right()) return
 
-      expect(found.value.map(evento => evento.id)).toEqual([coleta.value.id])
-      expect(found.value[0].coleta).toEqual(ficha)
+      expect(found.value.itens.map(evento => evento.id)).toEqual([coleta.value.id])
+      expect(found.value.itens[0].coleta).toEqual(ficha)
     } finally {
       await knex('eventos').whereIn('id', [diario.value.id, coleta.value.id]).delete()
     }
   })
 
+  test('filtra por intervalo de captura e pagina os resultados', async () => {
+    const antes = await collection.create({
+      ...novoDiario(), capturado_em: new Date('2026-02-14T10:00:00.000Z')
+    })
+    const dentro1 = await collection.create({
+      ...novoDiario(), capturado_em: new Date('2026-02-15T10:00:00.000Z')
+    })
+    const dentro2 = await collection.create({
+      ...novaColeta(), capturado_em: new Date('2026-02-15T14:00:00.000Z')
+    })
+    const depois = await collection.create({
+      ...novoDiario(), capturado_em: new Date('2026-02-16T10:00:00.000Z')
+    })
+
+    expect(antes.right() && dentro1.right() && dentro2.right() && depois.right()).toBe(true)
+    if (!antes.right() || !dentro1.right() || !dentro2.right() || !depois.right()) return
+
+    try {
+      const found = await collection.findAll({
+        expedicao_id: expedicaoId,
+        capturado_de: new Date('2026-02-15T00:00:00.000Z'),
+        capturado_ate: new Date('2026-02-15T23:59:59.999Z'),
+        limite: 1,
+        pagina: 2
+      })
+
+      expect(found.right()).toBe(true)
+      if (!found.right()) return
+
+      expect(found.value.total).toBe(2)
+      expect(found.value.limite).toBe(1)
+      expect(found.value.pagina).toBe(2)
+      expect(found.value.itens.map(evento => evento.id)).toEqual([dentro1.value.id])
+    } finally {
+      await knex('eventos')
+        .whereIn('id', [
+          antes.value.id,
+          dentro1.value.id,
+          dentro2.value.id,
+          depois.value.id
+        ])
+        .delete()
+    }
+  })
+
   test('apaga eventos e fichas junto com a expedição', async () => {
     const [expedicao] = await knex('expedicoes')
       .insert({