refactor: MatchingMapController로 카메라 제어 + 현재위치/초기복원 복원 (#546)

- MatchingMapController 추가: Screen 내부 MapViewManager에 다리를 놓아
  화면 밖(Fragment)에서 moveCamera/currentBounds 호출
- MatchingMapScreen: controller/onMapReady 파라미터 추가, 지도 준비 시 통로 연결
- MatchingMapFragment: 현재위치 버튼·초기 카메라 복원을 controller 경유로 복원
  (권한/FusedLocation은 Fragment 책임 유지)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: edv-Shin

feature/matching/src/main/java/com/project200/feature/matching/map/MatchingMapFragment.kt

@@ -1,14 +1,26 @@
 package com.project200.feature.matching.map
 
+import android.Manifest
+import android.annotation.SuppressLint
+import android.content.pm.PackageManager
 import android.view.View
 import android.widget.Toast
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.core.content.ContextCompat
 import androidx.core.view.isVisible
 import androidx.fragment.app.viewModels
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.lifecycleScope
 import androidx.lifecycle.repeatOnLifecycle
 import androidx.navigation.fragment.findNavController
+import com.google.android.gms.location.FusedLocationProviderClient
+import com.google.android.gms.location.LocationServices
+import com.kakao.vectormap.LatLng
+import com.project200.common.constants.RuleConstants.SEOUL_CITY_HALL_LATITUDE
+import com.project200.common.constants.RuleConstants.SEOUL_CITY_HALL_LONGITUDE
+import com.project200.common.constants.RuleConstants.ZOOM_LEVEL
 import com.project200.feature.matching.map.cluster.MapClusterItem
+import com.project200.feature.matching.map.compose.MatchingMapController
 import com.project200.feature.matching.map.compose.MatchingMapScreen
 import com.project200.feature.matching.map.filter.FilterBottomSheetDialog
 import com.project200.feature.matching.map.filter.MatchingFilterRVAdapter
@@ -25,21 +37,37 @@ class MatchingMapFragment :
     BindingFragment<FragmentMatchingMapBinding>(R.layout.fragment_matching_map) {
     private val viewModel: MatchingMapViewModel by viewModels()
 
+    // 지도 본체(MatchingMapScreen) 내부 카메라를 제어하기 위한 통로
+    private val mapController = MatchingMapController()
+    private var isMapInitialized = false
+    private lateinit var fusedLocationClient: FusedLocationProviderClient
+
     private val filterAdapter by lazy {
         MatchingFilterRVAdapter(
             onFilterClick = { type -> viewModel.onFilterTypeClicked(type) },
             onClearClick = { viewModel.clearFilters() },
         )
     }
 
+    private val locationPermissionLauncher =
+        registerForActivityResult(ActivityResultContracts.RequestPermission()) { isGranted ->
+            if (isGranted) moveToCurrentLocation()
+        }
+
     override fun getViewBinding(view: View): FragmentMatchingMapBinding {
         return FragmentMatchingMapBinding.bind(view)
     }
 
     override fun setupViews() {
+        isMapInitialized = false
+        fusedLocationClient = LocationServices.getFusedLocationProviderClient(requireActivity())
+
+        // 지도 본체는 Compose(MatchingMapScreen)로 호스팅. 마커/클러스터/카메라 idle은 Screen 내부 처리.
         binding.mapComposeView.applyAppTheme {
             MatchingMapScreen(
                 viewModel = viewModel,
+                controller = mapController,
+                onMapReady = { restoreInitialCamera() },
                 onClusterClick = { items -> showMembersBottomSheet(items) },
                 onPlaceMarkerClick = {
                     findNavController().navigate(
@@ -56,7 +84,7 @@ class MatchingMapFragment :
 
     private fun initListeners() {
         binding.currentLocationBtn.setOnClickListener {
-            // TODO: 현재 위치 이동 구현
+            checkPermissionAndMove()
         }
 
         binding.exercisePlaceListBtn.setOnClickListener {
@@ -66,6 +94,67 @@ class MatchingMapFragment :
         }
     }
 
+    /**
+     * 지도가 준비되면 1회 호출되어 초기 카메라 위치를 복원한다.
+     * 저장된 위치가 있으면 그곳으로, 없으면 현재 위치(권한 시) 또는 기본 위치(서울시청)로 이동한다.
+     */
+    private fun restoreInitialCamera() {
+        if (isMapInitialized) return
+
+        val savedPosition = viewModel.initialMapPosition.value
+        if (isLocationPermissionGranted()) {
+            if (savedPosition != null) {
+                mapController.moveCamera(
+                    LatLng.from(savedPosition.latitude, savedPosition.longitude),
+                    savedPosition.zoomLevel,
+                )
+            } else {
+                moveToCurrentLocation()
+            }
+        } else {
+            mapController.moveCamera(
+                LatLng.from(SEOUL_CITY_HALL_LATITUDE, SEOUL_CITY_HALL_LONGITUDE),
+                ZOOM_LEVEL,
+            )
+            locationPermissionLauncher.launch(Manifest.permission.ACCESS_FINE_LOCATION)
+        }
+
+        isMapInitialized = true
+    }
+
+    private fun checkPermissionAndMove() {
+        if (isLocationPermissionGranted()) {
+            moveToCurrentLocation()
+        } else {
+            locationPermissionLauncher.launch(Manifest.permission.ACCESS_FINE_LOCATION)
+        }
+    }
+
+    @SuppressLint("MissingPermission") // 권한은 isLocationPermissionGranted()로 이미 확인됨
+    private fun moveToCurrentLocation() {
+        fusedLocationClient.lastLocation.addOnSuccessListener { location ->
+            val latLng =
+                if (location != null) {
+                    LatLng.from(location.latitude, location.longitude)
+                } else {
+                    Toast.makeText(
+                        requireContext(),
+                        R.string.error_cannot_find_current_location,
+                        Toast.LENGTH_SHORT,
+                    ).show()
+                    LatLng.from(SEOUL_CITY_HALL_LATITUDE, SEOUL_CITY_HALL_LONGITUDE)
+                }
+            mapController.moveCamera(latLng, ZOOM_LEVEL)
+        }
+    }
+
+    private fun isLocationPermissionGranted(): Boolean {
+        return ContextCompat.checkSelfPermission(
+            requireContext(),
+            Manifest.permission.ACCESS_FINE_LOCATION,
+        ) == PackageManager.PERMISSION_GRANTED
+    }
+
     override fun setupObservers() {
         viewLifecycleOwner.lifecycleScope.launch {
             repeatOnLifecycle(Lifecycle.State.STARTED) {

feature/matching/src/main/java/com/project200/feature/matching/map/compose/MatchingMapController.kt

@@ -0,0 +1,28 @@
+package com.project200.feature.matching.map.compose
+
+import com.kakao.vectormap.LatLng
+import com.project200.domain.model.MapBounds
+import com.project200.feature.matching.map.MapViewManager
+
+/**
+ * 지도 카메라를 화면 밖(Fragment)에서 제어하기 위한 통로.
+ *
+ * MapViewManager 는 MatchingMapScreen 내부에서 비동기로 생성되므로,
+ * 권한/현재위치/초기 복원처럼 Fragment 가 담당하는 로직이 카메라를 만지려면 이 컨트롤러로 다리를 놓는다.
+ * 준비 전(manager == null)에는 카메라 명령이 무시된다.
+ */
+class MatchingMapController {
+    internal var manager: MapViewManager? = null
+
+    val isReady: Boolean
+        get() = manager != null
+
+    fun moveCamera(
+        latLng: LatLng,
+        zoomLevel: Int,
+    ) {
+        manager?.moveCamera(latLng, zoomLevel)
+    }
+
+    fun currentBounds(): MapBounds? = manager?.getCurrentBounds()
+}

feature/matching/src/main/java/com/project200/feature/matching/map/compose/MatchingMapScreen.kt

@@ -30,6 +30,8 @@ import com.project200.feature.matching.map.cluster.MapClusterItem
 fun MatchingMapScreen(
     viewModel: MatchingMapViewModel,
     modifier: Modifier = Modifier,
+    controller: MatchingMapController? = null,
+    onMapReady: () -> Unit = {},
     onClusterClick: (List<MapClusterItem>) -> Unit = {},
     onPlaceMarkerClick: () -> Unit = {},
 ) {
@@ -67,10 +69,13 @@ fun MatchingMapScreen(
                         onLabelClick = { label ->
                             handleLabelClick(label, manager, clusterCalculator, onClusterClick, onPlaceMarkerClick)
                         },
-                    )
+                    ).also { mgr ->
+                        controller?.manager = mgr // 카메라 제어 통로 연결
+                        onMapReady() // Fragment가 초기 복원 등을 시작하도록 통지
+                    }
             },
         )
-        // TODO: 필터, 현재위치 버튼 등 오버레이 여기에 추가
+        // 현재위치 버튼 등 오버레이는 Fragment XML 유지(추후 Compose 전환)
     }
 
     // 데이터(또는 지도 준비) 변경 시 마커/클러스터 다시 그리기