[Feat] 맵 기능 확장을 위한 건물/부대시설 도메인 분리 기반 마련

[rlagkswn00]

배경

• 현재 club 테이블이 building, room, lat, lon을 직접 보유하고 있어 건물 정보가 club에 종속되어 있습니다.
• 앞으로 맵 기능에서 건물 단위 좌표와 부대시설 정보를 공통으로 관리해야 합니다.
• 기존 이슈 [Feat] 동아리 기능 API 개발 #336 에서 동아리 기능 API 개발을 진행했지만, 건물 정보는 맵 확장 관점의 독립 도메인으로 정리되어 있지 않습니다.

목표

• building을 독립 마스터 테이블로 분리합니다.
• facility, building_facility를 도입해 건물별 부대시설 확장 기반을 마련합니다.
• club은 building_id를 참조하고 room만 직접 유지합니다.
• club 상세 API의 location.building/room/lon/lat 응답 계약은 유지합니다.

비목표

• 맵 전용 조회 API 구현
• admin 입력/수정 API 구현
• 부대시설 운영 데이터 입력 절차 구축
• club.building, club.lat, club.lon legacy 컬럼 제거까지 한 번에 처리

제안 동작

• building(id, name, lat, lon) 테이블을 생성합니다.
• facility(id, code, name)와 building_facility(id, building_id, facility_id, detail)를 생성합니다.
• club.building_id nullable FK를 추가하고 room은 유지합니다.
• 마이그레이션은 expand -> backfill -> switch -> contract 순서로 진행합니다.
• 1차에서는 새 테이블과 FK를 추가합니다.
• 2차에서는 기존 club.building/lat/lon에서 building 데이터를 백필하고 club.building_id를 연결합니다.
• 3차에서는 조회 로직을 building join 기준으로 전환하되 API 응답은 유지합니다.
• legacy 컬럼 drop은 운영 검증 후 후속 이슈로 분리합니다.

수용 기준

• building, facility, building_facility 스키마가 생성되어 있습니다.
• 위치가 있는 club은 building join 기반으로 기존과 동일한 location 응답을 제공합니다.
• club.room은 유지됩니다.
• 건물당 대표 좌표 1개를 저장할 수 있습니다.
• 건물별 시설 보유 정보와 상세 메모를 저장할 수 있습니다.
• club 구독/알림/모집 상태 등 기존 기능에 회귀가 없습니다.
• 백필 후 club.building_id가 필요한 데이터에 정상 연결됩니다.

[rlagkswn00]

스읍 코덱스 서운한데

[rlagkswn00]

Building 마이그레이션 후속 작업

남은 작업 TODO

Phase 0. backfill 사전 준비

• 캠퍼스 장소 데이터에서 실제 건물 데이터만 분리
• 건물 기준 데이터 insert SQL 작성
• 기존 club.building 값과 신규 건물 데이터 매핑표 작성
• club 위치 참조 backfill SQL 작성
• backfill 검증 SQL 작성
• dev/main에서 동일하게 실행할 수 있는 runbook 작성
• expand 배포 직후 바로 backfill할 수 있도록 실행 순서와 담당자 확정

Phase 1. dev expand

• dev 환경에 schema expand 배포
• Flyway 적용 확인
  • 위치 기준 테이블 생성
  • club 위치 참조 컬럼 생성
  • 필요한 FK 생성
• 비즈니스 로직은 기존 위치 조회 기준으로 유지

Phase 2. dev backfill

• dev DB에 건물 기준 데이터 insert
• dev DB에서 club 위치 참조 backfill 수행
• dev DB backfill 결과 검증
• 기존 위치 응답에 회귀가 없는지 확인

Phase 3. main expand + backfill

• main 운영 환경에 schema expand 배포
• 운영 DB Flyway 적용 확인
• 운영 DB에 건물 기준 데이터 insert
• 운영 DB에서 club 위치 참조 backfill 즉시 수행
• 운영 DB backfill 결과 검증
• 운영 smoke test 수행

Phase 4. dev switch code

• backfill 완료 후 dev에서 club 상세 조회를 신규 위치 구조 기준으로 전환
• 기존 location.building/room/lon/lat 응답 계약 유지 확인
• dev smoke test 수행

Phase 5. main switch code

• main 운영 환경에 switch code 배포
• 운영 smoke test 수행
• 신규 위치 구조 기준 조회 정상 동작 확인

Phase 6. legacy column drop

• backfill 및 switch code 완료 여부 최종 확인
• legacy 컬럼 의존 코드가 없는지 확인
• club.building, club.lat, club.lon 제거 migration 작성
• develop 환경에 drop migration 배포 및 검증
• main 운영 환경에 drop migration 배포 및 검증

주의사항

• backfill은 Flyway migration에 포함하지 않고 별도 SQL/runbook으로 수행합니다.
• expand 배포 후 즉시 backfill할 수 있도록 Phase 0에서 SQL과 runbook을 먼저 준비합니다.
• club 상세 조회 등 비즈니스 로직 전환은 backfill 검증 이후에 진행합니다.
• club.building, club.lat, club.lon drop은 backfill 및 switch code 검증 후 별도 PR에서 진행합니다.
• 제공된 캠퍼스 장소 데이터는 건물 외 장소도 포함하므로, 실제 건물 데이터와 일반 장소 데이터를 분리해서 다룹니다.