[Work 59] 장소 검색과 주변 장소 선택의 정확도를 개선했습니다.

WhereAreYou/WhereAreYou/Core/DI/Implementation/ScreenFactory/ScreenFactory+PlaceSelection.swift

@@ -16,6 +16,9 @@ extension ScreenFactory {
                 nearbyPlaceRepository: container.resolve(NearbyPlaceRepository.self),
                 reverseGeocodingRepository: container.resolve(ReverseGeocodingRepository.self)
             ),
+            getRegionPlaceUseCase: GetRegionPlaceUseCase(
+                reverseGeocodingRepository: container.resolve(ReverseGeocodingRepository.self)
+            ),
             initialCoordinate: initialCoordinate
         )
         return PlaceSelectionViewController(viewModel: viewModel)

WhereAreYou/WhereAreYou/Core/DI/Implementation/ScreenFactory/ScreenFactory+SearchPlaceCard.swift

@@ -12,7 +12,11 @@ extension ScreenFactory {
         style: SearchPlaceCardViewController.Style
     ) -> SearchPlaceCardViewController {
         let viewModel = SearchPlaceCardViewModel(
-            searchPlacesUseCase: SearchPlacesUseCase(repository: container.resolve(PlaceSearchRepository.self))
+            searchPlacesUseCase: SearchPlacesUseCase(
+                repository: container.resolve(PlaceSearchRepository.self),
+                locationRepository: container.resolve(LocationRepository.self),
+                locationPermissionRepository: container.resolve(LocationPermissionRepository.self)
+            )
         )
         return SearchPlaceCardViewController(
             viewModel: viewModel,

WhereAreYou/WhereAreYou/Data/Kakao/KakaoCategoryGroupCode.swift

@@ -28,3 +28,21 @@ enum KakaoCategoryGroupCode: String {
     case hospital = "HP8"         // 병원
     case pharmacy = "PM9"         // 약국
 }
+
+nonisolated extension KakaoCategoryGroupCode {
+
+    /// 코드 정보가 없는 장소에 적용하는 기본 대표성 가중치
+    static let defaultRepresentativeness = 1.0
+
+    /// 지명을 대표하는 정도
+    var representativeness: Double {
+        switch self {
+        case .subwayStation, .publicInstitution, .attraction:
+            return 4.0
+        case .culturalFacility, .hospital, .largeMart:
+            return 2.0
+        default:
+            return Self.defaultRepresentativeness
+        }
+    }
+}

WhereAreYou/WhereAreYou/Data/Kakao/KakaoLocalEndpoint.swift

@@ -7,10 +7,18 @@
 
 import Foundation
 
+/// 카카오 키워드 검색 정렬 기준
+enum KakaoKeywordSort {
+    /// 정확도순 (카카오 기본값)
+    case accuracy
+    /// 기준 좌표와 가까운 순
+    case distance
+}
+
 /// 카카오 로컬 API 요청
 enum KakaoLocalEndpoint {
-    /// 키워드로 장소 검색
-    case keyword(query: String)
+    /// 키워드로 장소 검색, 좌표를 넘기면 응답에 거리(m)가 채워짐
+    case keyword(query: String, page: Int = 1, coordinate: Coordinate? = nil, sort: KakaoKeywordSort = .accuracy)
     /// 좌표 반경 내 카테고리 검색, 거리순 정렬
     case category(code: KakaoCategoryGroupCode, coordinate: Coordinate, radiusMeters: Int)
     /// 좌표 -> 주소 변환
@@ -36,11 +44,20 @@ extension KakaoLocalEndpoint: Endpoint {
 
     var queryItems: [URLQueryItem] {
         switch self {
-        case .keyword(let query):
-            return [
+        case .keyword(let query, let page, let coordinate, let sort):
+            var items = [
                 URLQueryItem(name: "query", value: query),
-                URLQueryItem(name: "size", value: "15")
+                URLQueryItem(name: "size", value: "15"),
+                URLQueryItem(name: "page", value: "\(page)")
             ]
+            if let coordinate {
+                items.append(URLQueryItem(name: "x", value: "\(coordinate.longitude)"))
+                items.append(URLQueryItem(name: "y", value: "\(coordinate.latitude)"))
+                if sort == .distance {
+                    items.append(URLQueryItem(name: "sort", value: "distance"))
+                }
+            }
+            return items
         case .category(let code, let coordinate, let radiusMeters):
             return [
                 URLQueryItem(name: "category_group_code", value: code.rawValue),

WhereAreYou/WhereAreYou/Data/Kakao/Repository/KakaoNearbyPlaceRepository.swift

@@ -7,17 +7,18 @@
 
 import Foundation
 
-/// 좌표 반경 내 가장 가까운 장소 1개 조회 (지도 장소 선택, 현재 위치 표시용, 키워드 검색과 무관)
-/// 카테고리 검색이 요청당 카테고리 1개만 지원해, 서비스가 다루는 카테고리를 병렬 요청 후 가장 가까운 결과 선택
+/// 좌표 반경 내 거리와 대표성을 고려한 장소 1개 조회 (지도 장소 선택, 현재 위치 표시용, 키워드 검색과 무관)
+/// 카테고리 검색이 요청당 카테고리 1개만 지원해, 서비스가 다루는 카테고리를 병렬 요청 후 거리와 카테고리 대표성을 함께 고려해 선택
 /// 지도 이동 1회당 카테고리 수만큼 호출 발생 — PlaceSelectionViewModel의 디바운스/최소 이동 거리로 호출량 제한
 final class KakaoNearbyPlaceRepository: NearbyPlaceRepository {
 
     /// 카카오 API가 허용하는 최대 반경(m)
     private static let maximumRadiusMeters = 20000
 
-    /// 조회 대상 카테고리 — 검색 화면 필터와 무관, PlaceType 매핑 대상만 포함
+    /// 조회 대상 카테고리
     private static let categoryCodes: [KakaoCategoryGroupCode] = [
-        .subwayStation, .restaurant, .cafe, .hospital, .largeMart, .convenienceStore
+        .subwayStation, .attraction, .culturalFacility, .hospital, .largeMart,
+        .restaurant, .cafe, .convenienceStore, .school, .parkingLot
     ]
 
     private let apiClient: APIClient
@@ -26,9 +27,24 @@ final class KakaoNearbyPlaceRepository: NearbyPlaceRepository {
         self.apiClient = apiClient
     }
 
+    /// 카테고리당 수집하는 후보 수
+    private static let candidatesPerCategory = 5
+
+    /// 선택 대상 후보
+    private struct Candidate {
+        let place: Place
+        let distanceMeters: Double
+        let categoryCode: KakaoCategoryGroupCode
+
+        /// 선택 순위, 낮을수록 우선
+        var rank: Double {
+            distanceMeters / categoryCode.representativeness
+        }
+    }
+
     /// 카테고리 하나 조회 결과 — 결과 없음(정상)과 요청 실패를 구분해 상위에서 정책을 결정할 수 있게 함
     private enum CategoryResult {
-        case found(Place, distanceMeters: Double)
+        case found([Candidate])
         case notFound
         case failed(Error)
     }
@@ -39,7 +55,7 @@ final class KakaoNearbyPlaceRepository: NearbyPlaceRepository {
         let results = try await withThrowingTaskGroup(of: CategoryResult.self) { group in
             for code in Self.categoryCodes {
                 group.addTask {
-                    try await self.nearestDocument(code: code, coordinate: coordinate, radiusMeters: radiusMeters)
+                    try await self.fetchCandidates(code: code, coordinate: coordinate, radiusMeters: radiusMeters)
                 }
             }
             var collected: [CategoryResult] = []
@@ -51,17 +67,15 @@ final class KakaoNearbyPlaceRepository: NearbyPlaceRepository {
 
         // 카테고리 중 하나라도 성공(결과 유무 무관)했으면 그 결과로 판단.
         // 전부 요청 실패였을 때만 대표로 첫 실패를 throw — 상위(GetNearbyPlaceUseCase)가 역지오코딩 폴백 여부를 판단할 신호로 사용
-        var best: (place: Place, distance: Double)?
+        var candidates: [Candidate] = []
         var firstFailure: Error?
         var hasSucceeded = false
 
         for result in results {
             switch result {
-            case .found(let place, let distance):
+            case .found(let found):
                 hasSucceeded = true
-                if best == nil || distance < best!.distance {
-                    best = (place, distance)
-                }
+                candidates.append(contentsOf: found)
             case .notFound:
                 hasSucceeded = true
             case .failed(let error):
@@ -72,13 +86,13 @@ final class KakaoNearbyPlaceRepository: NearbyPlaceRepository {
         if !hasSucceeded, let firstFailure {
             throw firstFailure
         }
-        return best?.place
+        return candidates.min { $0.rank < $1.rank }?.place
     }
 
     // MARK: - Private
 
-    /// 카테고리 하나를 조회해 결과 유무/실패를 구분해 반환. 취소는 흡수하지 않고 그대로 다시 throw
-    private func nearestDocument(
+    /// 카테고리 하나의 상위 후보를 조회해 결과 유무/실패를 구분해 반환
+    private func fetchCandidates(
         code: KakaoCategoryGroupCode,
         coordinate: Coordinate,
         radiusMeters: Int
@@ -87,12 +101,16 @@ final class KakaoNearbyPlaceRepository: NearbyPlaceRepository {
             let response: KakaoPlaceResponse = try await apiClient.request(
                 KakaoLocalEndpoint.category(code: code, coordinate: coordinate, radiusMeters: radiusMeters)
             )
-            guard let document = response.documents.first,
-                  let place = document.toPlace(),
-                  let distance = document.distanceMeters else {
-                return .notFound
-            }
-            return .found(place, distanceMeters: distance)
+            let candidates = response.documents
+                .prefix(Self.candidatesPerCategory)
+                .compactMap { document -> Candidate? in
+                    guard let place = document.toPlace(),
+                          let distance = document.distanceMeters else {
+                        return nil
+                    }
+                    return Candidate(place: place, distanceMeters: distance, categoryCode: code)
+                }
+            return candidates.isEmpty ? .notFound : .found(candidates)
         } catch is CancellationError {
             throw CancellationError()
         } catch {

WhereAreYou/WhereAreYou/Data/Kakao/Repository/KakaoPlaceSearchRepository.swift

@@ -16,10 +16,57 @@ final class KakaoPlaceSearchRepository: PlaceSearchRepository {
         self.apiClient = apiClient
     }
 
-    func searchPlaces(keyword: String) async throws -> [Place] {
+    func searchPlaces(keyword: String, near coordinate: Coordinate?) async throws -> [Place] {
+        async let firstPage = fetchDocuments(keyword: keyword, page: 1, coordinate: coordinate)
+        async let secondPage = fetchDocumentsIgnoringFailure(keyword: keyword, page: 2, coordinate: coordinate)
+        async let nearestPage = fetchNearestDocuments(keyword: keyword, coordinate: coordinate)
+
+        let documents = try await firstPage + secondPage + nearestPage
+
+        var seenIDs = Set<String>()
+        let uniqueDocuments = documents.filter { seenIDs.insert($0.id).inserted }
+
+        return KakaoPlaceRanker.rank(uniqueDocuments, keyword: keyword)
+            .compactMap { $0.toPlace() }
+    }
+
+    // MARK: - Private
+
+    private func fetchDocuments(
+        keyword: String,
+        page: Int,
+        coordinate: Coordinate?,
+        sort: KakaoKeywordSort = .accuracy
+    ) async throws -> [KakaoPlaceDocument] {
         let response: KakaoPlaceResponse = try await apiClient.request(
-            KakaoLocalEndpoint.keyword(query: keyword)
+            KakaoLocalEndpoint.keyword(query: keyword, page: page, coordinate: coordinate, sort: sort)
+        )
+        return response.documents
+    }
+
+    /// 보조 페이지 조회
+    private func fetchDocumentsIgnoringFailure(
+        keyword: String,
+        page: Int,
+        coordinate: Coordinate?,
+        sort: KakaoKeywordSort = .accuracy
+    ) async throws -> [KakaoPlaceDocument] {
+        do {
+            return try await fetchDocuments(keyword: keyword, page: page, coordinate: coordinate, sort: sort)
+        } catch {
+            try Task.checkCancellation()
+            return []
+        }
+    }
+
+    /// 기준 좌표에서 가까운 순 후보 조회
+    private func fetchNearestDocuments(keyword: String, coordinate: Coordinate?) async throws -> [KakaoPlaceDocument] {
+        guard let coordinate else { return [] }
+        return try await fetchDocumentsIgnoringFailure(
+            keyword: keyword,
+            page: 1,
+            coordinate: coordinate,
+            sort: .distance
         )
-        return response.documents.compactMap { $0.toPlace() }
     }
 }

WhereAreYou/WhereAreYou/Data/Kakao/Repository/KakaoReverseGeocodingRepository.swift

@@ -18,12 +18,25 @@ final class KakaoReverseGeocodingRepository: ReverseGeocodingRepository {
 
     func reverseGeocode(coordinate: Coordinate) async throws -> Place {
         do {
-            let response: KakaoAddressResponse = try await apiClient.request(
-                KakaoLocalEndpoint.coord2address(coordinate: coordinate)
-            )
+            let response = try await fetchAddress(coordinate: coordinate)
             return try response.toPlace(coordinate: coordinate)
         } catch let error as NetworkError {
             throw error.appError
         }
     }
+
+    func reverseGeocodeRegion(coordinate: Coordinate, level: RegionLevel) async throws -> Place {
+        do {
+            let response = try await fetchAddress(coordinate: coordinate)
+            return try response.toRegionPlace(coordinate: coordinate, level: level)
+        } catch let error as NetworkError {
+            throw error.appError
+        }
+    }
+
+    // MARK: - Private
+
+    private func fetchAddress(coordinate: Coordinate) async throws -> KakaoAddressResponse {
+        try await apiClient.request(KakaoLocalEndpoint.coord2address(coordinate: coordinate))
+    }
 }

WhereAreYou/WhereAreYou/Data/Kakao/Response/KakaoAddressResponse.swift

@@ -26,23 +26,95 @@ struct KakaoAddressDocument: Decodable {
 /// 도로명주소
 struct KakaoRoadAddress: Decodable {
     let addressName: String
+    /// 시/도
+    let region1DepthName: String?
+    /// 시/군/구
+    let region2DepthName: String?
 
     enum CodingKeys: String, CodingKey {
         case addressName = "address_name"
+        case region1DepthName = "region_1depth_name"
+        case region2DepthName = "region_2depth_name"
     }
 }
 
 /// 지번주소
 struct KakaoAddress: Decodable {
     let addressName: String
+    /// 시/도
+    let region1DepthName: String?
+    /// 시/군/구
+    let region2DepthName: String?
 
     enum CodingKeys: String, CodingKey {
         case addressName = "address_name"
+        case region1DepthName = "region_1depth_name"
+        case region2DepthName = "region_2depth_name"
     }
 }
 
 extension KakaoAddressResponse {
 
+    /// 카카오가 약칭으로 내려주는 시/도명을 정식 명칭으로 변환
+    /// 이미 정식 명칭이거나 매핑이 없으면 그대로 사용
+    private static let provinceFullNames: [String: String] = [
+        "서울": "서울특별시",
+        "부산": "부산광역시",
+        "대구": "대구광역시",
+        "인천": "인천광역시",
+        "광주": "광주광역시",
+        "대전": "대전광역시",
+        "울산": "울산광역시",
+        "세종": "세종특별자치시",
+        "경기": "경기도",
+        "강원": "강원특별자치도",
+        "충북": "충청북도",
+        "충남": "충청남도",
+        "전북": "전북특별자치도",
+        "전남": "전라남도",
+        "경북": "경상북도",
+        "경남": "경상남도",
+        "제주": "제주특별자치도",
+    ]
+
+    /// 지정한 행정구역 단위의 Place로 변환, 지역명이 없으면 emptyResult
+    func toRegionPlace(coordinate: Coordinate, level: RegionLevel) throws -> Place {
+        guard let document = documents.first else {
+            throw NetworkError.emptyResult
+        }
+        let rawProvince = document.address?.region1DepthName ?? document.roadAddress?.region1DepthName
+        let city = document.address?.region2DepthName ?? document.roadAddress?.region2DepthName
+
+        guard let rawProvince, !rawProvince.isEmpty else {
+            throw NetworkError.emptyResult
+        }
+        let province = Self.provinceFullNames[rawProvince] ?? rawProvince
+        let name: String
+        switch level {
+        case .province:
+            name = province
+        case .city:
+            // 세종처럼 시/군/구가 없는 지역은 시/도 이름으로 대체
+            if let city, !city.isEmpty {
+                name = city
+            } else {
+                name = province
+            }
+        }
+        let address = [province, city]
+            .compactMap { $0 }
+            .filter { !$0.isEmpty }
+            .joined(separator: " ")
+
+        return Place(
+            id: "region_\(level.rawValue)_\(coordinate.latitude)_\(coordinate.longitude)",
+            name: name,
+            address: address,
+            coordinate: coordinate,
+            type: .other
+        )
+    }
+
     /// Place로 변환, 도로명 우선 없으면 지번, 결과 없으면 emptyResult
     func toPlace(coordinate: Coordinate) throws -> Place {
         guard let document = documents.first else {