feat: implement Application layer for favorite heritages list API / お気に入り一覧APIのApplication層実装

[zigzagdev]

Parent Issue / 親Issue

#565

Motivation / 目的

Implement the Application layer use case for listing favorite heritages, as part of #565.

お気に入り一覧API（#565）のApplication層として、UseCaseを実装します。

What to do / 実施内容

• GetFavoriteHeritagesUseCase
  • FavoriteRepositoryInterface::getFavoriteWorldHeritageIds() でお気に入りのIDを取得（#566で実装済み）
  • WorldHeritageReadQueryServiceInterface::findByIdsPreserveOrder() で世界遺産データを取得（既存メソッドを再利用）
  • ページネーションして返却

Pagination approach

Favorites are bounded by the total World Heritage catalog size (~1,200 sites) and are scoped per user, so the count involved is always small. Because of that, this fetches all favorite IDs and paginates in application code rather than adding a new DB-level paginate() join method to the repository:

$allIds    = $favoriteRepository->getFavoriteWorldHeritageIds($userId); // ordered by favorited-at desc
$total     = count($allIds);
$pageIds   = array_slice($allIds, ($currentPage - 1) * $perPage, $perPage);
$heritages = $worldHeritageReadQueryService->findByIdsPreserveOrder($pageIds);

$lastPage = (int) ceil($total / $perPage);

Build the pagination metadata (current_page, per_page, total, last_page, from, to, page URLs) by hand, matching the same key structure as the existing PaginationDto::toArray() used by /v1/heritages (items + pagination), rather than wrapping an Eloquent LengthAwarePaginator.

Trade-off: this skips reusing Eloquent's paginator (so URL/meta fields are computed manually instead of generated automatically), but avoids adding a join-based pagination method to FavoriteRepositoryInterface. If favorite counts were ever expected to grow far beyond the heritage catalog size, this assumption would need to be revisited in favor of a DB-level join + paginate().

Tests / テスト

Mockeryを使ったユニットテスト

• test_handle_returns_favorite_heritages_for_user
• test_handle_returns_empty_list_when_no_favorites
• test_handle_paginates_favorite_heritages_correctly