Adicionar uma nova feature

Checklist para implementar uma feature seguindo os padrões do projeto.

Passo a passo

1. DTOs — Criar input/output em src/domain/dtos/{feature}/ com class-validator e @ApiProperty.
2. Enums — Se necessário, adicionar em src/domain/enums/.
3. Entity — Se houver modelo de domínio, criar src/app/entities/{feature}.entity.ts com getFriendlyObject().
4. Escolher padrão de gateway — Default CRUD vs. custom (ver Repository customizado).
5. Gateway — Criar src/app/gateways/{feature}.repository.gateway.ts.
6. Knex row — Se persistência nova, tipo em src/infra/database/knex/entities/.
7. Mapper — src/infra/database/knex/mappers/{feature}.ts implementando MapperGateway.
8. Repository — src/infra/database/knex/repositories/knex-{feature}.repository.ts.
9. DatabaseModule — Registrar { provide: XxxGateway, useClass: KnexXxxRepository }.
10. Use case(s) — src/app/use-cases/{feature}/{action}-{feature}.use-case.ts.
11. HTTPModule — Adicionar use case(s) ao array USECASES (e módulos public/internal se aplicável).
12. Controller — Endpoint em src/infra/http/controllers/{feature}.controller.ts.
13. Testes — test/unit/ espelhando a camada alterada.
14. Permissões — Se rota restrita, @Permission(PERMISSION.X) e enum correspondente.

Walkthrough A — CRUD simples (Attendance Type)

Fluxo completo para listar tipos de atendimento.

Sequência:

GET /attendance-type/list
  → AttendanceTypeController.list(req)
  → ListAttendanceTypeUseCase.execute(companyId)
  → AttendanceTypeRepositoryGateway.findAll(companyId)
  → KnexAttendanceTypeRepository (KnexDefaultRepository)
  → Mapper → AttendanceTypeEntity[]
  → getFriendlyObject() → { success: true, data: [...] }

Este é o caminho mais rápido para tabelas de cadastro: gateway vazio que só estende default, repository com super() no constructor.

Walkthrough B — Domínio complexo (Attendance search + export)

Fluxo para busca paginada e exportação assíncrona por e-mail.

Sequência (busca normal):

POST /attendance/search
  → AttendanceController + @Pagination() + ListAttendanceDTO
  → ListAttendanceUseCase.executePaginated(companyId, filters, pagination)
  → AttendanceRepositoryGateway.search(...)
  → enrichAttendances() com outros gateways
  → { success: true, data: { attendances, totalAttendances } }

Sequência (export por e-mail):

POST /attendance/search + header send-email
  → ListAttendanceUseCase.execute(..., sendEmail: true)
  → BrokerGateway.publish(BROKER_REPORTS_QUEUE, { companyId, filters, userEmail })
  → resposta imediata { reportQueued: true }
  → (async) AttendanceReportConsumer → gateways → CSV → S3 → EmailGateway

Este walkthrough mostra composição de múltiplos gateways, integração com broker e separação entre caminho síncrono e assíncrono no mesmo use case.

Referências de código