frontend/apps/sn/docs/작업검증/SFR-010-010-지반침하정보/002-qa-SFR-010-010-지반침하정보-통합검증결과.md

SFR-010-010 지반침하정보 통합 검증 결과

1. 문서 목적

• SFR-010-010 지반침하정보의 검증 결과를 기능당 1개 문서로 누적 관리한다.
• 이번 턴은 설계 단계이므로 실행 결과 대신 사전 점검 결과와 미실행 사유를 기록한다.
• 승인 후 구현과 실행 검증이 시작되면 이 문서에 라운드별 결과를 누적한다.

2. 현재 수행 결과

2.1 설계 자료 점검

• 요구사항명세서, 시나리오, HTML, PNG를 읽고 화면 흐름과 API 초안을 정리했다.
• 현재 백엔드 작업트리에서 아래 선반영 범위를 확인했다.
  • GET /api/v1/sinkholes/geometry
  • IL datasource 분리
  • 주소 기반 지오코딩 서비스
• 현재 프론트 코드에서는 지반침하정보 실구현이 없고, 실제 구현은 승인 후 착수해야 함을 확인했다.

2.2 확인된 설계 리스크

• 화면에 필요한 상세 필드 일부가 현재 원천 테이블에 없다.
• 좌표 캐시가 현재 메모리 캐시라 최근 동기화 일시/상태 유지 요구를 그대로 만족하지 못한다.
• 목록 팝업을 별도 popup 창으로 열지, /map 내부 모달로 둘지 구현 기준이 아직 확정되지 않았다.

2.3 2026-06-05 런타임 원인 확인

• 프론트에서 GET /api/v1/sinkholes/geometry 호출 시 500이 재현됐다.
• 같은 시점에 로컬 GET /api/v1/sinkholes, GET /api/v1/sinkholes/{acdntNo}를 직접 확인한 결과 geocodeErrorMessage에 아래 예외가 내려왔다.
  • Unrecognized field "adresTy" ... SinkholeNgiiResponse
• 따라서 이번 런타임 장애의 1차 원인은 프론트 fetch 자체가 아니라 reuse-service 지오코딩 응답 필드 확장을 백엔드가 무시하지 못한 점으로 판정했다.
• ./gradlew compileJava --no-daemon는 시도했으나 로컬 점유 중인 spring-configuration-metadata.json 때문에 Failed to clean up stale outputs로 중단돼, 재기동 후 최종 확인이 필요하다.

2.4 2026-06-09 연도/전체 노드 코드 경로 확인

• 현재 프론트 지반침하 연도 필터 로직을 다시 확인한 결과, tb_sn_lyr_stng에서 내려오는 2026년, 전체 자식 노드는 sinkholeYear 값이 없어 기존 코드가 연도 토큰을 읽지 못하고 있었다.
• 그래서 화면에 연도 노드가 보여도 초기 표출과 팝업 필터 동기화에서는 최근 3개월 기본 조건이 남아 있을 수 있는 상태로 판정했다.
• 이번 수정으로 sinkholeYear가 없더라도 노드 텍스트 2026년, 전체를 각각 2026, ALL로 해석하도록 보강했다.
• 레이어 설정 초기 로딩도 지반침하 트리 보정 유틸을 실제로 거치도록 연결해, DB 자식 노드 유무와 상관없이 같은 정리 경로를 타게 했다.

2.5 2026-06-09 발생기간 조회 시작일 2016년 확장

• 현재 팝업은 빈 조회조건일 때 최근 3개월을 기본값으로 쓰고 있어, 사용자가 장기 이력을 보려 해도 시작일을 다시 넓혀야 하는 상태였다.
• 이번 수정으로 프론트 기본 조회조건을 2016-01-01 ~ 오늘로 바꾸고, 날짜 입력 min도 2016-01-01로 고정했다.
• 백엔드도 같은 날 최대 1년 검증을 제거하고 2016-01-01 이전 날짜만 차단하도록 바꿨다.

2.6 2026-06-09 다운로드 전체 결과 기준 코드 경로 확인

• 현재 지반침하 다운로드는 화면에 보이는 현재 페이지 rows만 엑셀로 내려가고 있어, 페이지네이션 이후 데이터는 누락되는 상태였다.
• 이번 수정으로 다운로드 시 현재 조회조건을 유지한 채 /api/v1/sinkholes를 최대 2000건 단위로 재호출해 전체 결과를 합친 뒤 엑셀을 생성하도록 변경했다.
• 아직 브라우저에서 2페이지 이상 결과를 실제로 내려받아 행 수를 대조하는 수동 검증은 수행하지 못했다.

2.7 2026-06-09 다운로드 병목 재검토

• 백엔드 목록 API는 각 행마다 SinkholeCoordinateResolver.resolve()를 호출하고, 원천 TM 좌표가 없으면 외부 지오코딩을 타므로 대량 다운로드에서 이 경로가 지연의 핵심 병목이 될 수 있다고 판단했다.
• 그래서 동일 주소의 실패 지오코딩도 30분 단기 캐시에 저장하고, 프론트 다운로드 배치도 2000건으로 올려 1600건 규모에서는 목록 API 1회 호출에 가깝게 줄였다.
• 아직 실제 운영/개발 데이터 1600건 조건에서 전후 다운로드 시간을 계측하지는 못했다.

2.8 2026-06-09 좌표 실패 건 상세 fallback 코드 경로 확인

• 좌표 실패 건 상세 클릭 시 GET /api/v1/sinkholes/{acdntNo}가 generic 500으로 실패하는 사례가 확인됐다.
• 이번 수정으로 목록 행 클릭 경로에서는 상세 API 실패 시 목록 row 데이터를 fallback 상세로 사용하고, 인접관로 조회 실패도 별도 warning으로만 남기도록 바꿨다.
• 추가로 row 자체가 이미 좌표 실패 상태이고 x/y도 없으면, 상세 API를 아예 생략하고 즉시 fallback 상세 패널을 열도록 바꿨다.
• 아직 실제 브라우저에서 실패 좌표 row 클릭 후 우측 패널이 fallback 데이터로 열리는지 재검증은 수행하지 못했다.

2.9 2026-06-09 목록/다운로드 조회조건 변경 코드 경로 확인

• 기본 발생기간은 2016-01-01 고정이 아니라 다시 현재 기준 최근 1년으로 되돌렸다.
• 목록 조회영역에 좌표보정상태 조건을 추가했고, 목록 API query string도 해당 값을 함께 보내도록 바꿨다.
• 다운로드는 includeCoordStatus=false를 붙여 좌표보정상태 열 없이 현재 조회조건 전체 결과를 다시 받아 엑셀을 만들도록 변경했다.

2.10 2026-06-09 조회옵션/헤더범위 마감 확인

• 좌표보정상태 옵션에서 주소없음은 제거되고 전체 / 성공 / 실패만 남는 코드 경로를 확인했다.
• 지반침하 다운로드는 headerRange=A1:I1로 수정돼 첫 데이터 행이 헤더 스타일을 먹지 않도록 정리된 것을 확인했다.

2.11 2026-06-09 팝업 활성 중 필터 우선순위 코드 경로 확인

• 평소 지도 레이어 조회는 트리 연도 체크 상태를 기준으로 하고, 팝업 sync 메시지를 받은 이후에만 팝업 필터가 우선 적용되도록 isSinkholePopupFilterActive 분기가 추가된 것을 확인했다.
• 팝업 close watcher와 레이어 해제 경로에서도 popup-active 상태를 해제하도록 맞춰, 팝업 종료 후 다시 트리 기준으로 복귀하는 코드 경로를 확인했다.

2.12 2026-06-09 기능 테스트 최종 확인

• 사용자 확인 기준으로 아래 주요 흐름이 기대대로 동작함을 최종 확인했다.
  • 지반침하 트리 기본 체크 상태 유지
  • 2026년 / 전체 상위조건과 팝업 조회조건의 결합
  • 팝업 목록보기 오픈 시 지도 즉시 동기화
  • 팝업 닫힘 시 트리 기준 복귀
  • 팝업 열린 상태에서 레이어 재체크 시 조건 유지
  • 다운로드 첫 데이터 행 헤더 스타일 오염 제거
• 현재 대화 범위에서는 기능 테스트 성공으로 판정한다.

2.13 2026-06-11 목록 총 건수 헤더 표시 확인

• 검증 대상
  • FE_APP_ROOT/app/(map-layout)/map/components/sinkhole/SinkholePopupPage.tsx
• 확인 내용
  • 지반침하 팝업 목록 테이블이 total 상태값을 이미 보유하고 있는지 코드 경로를 다시 확인했다.
  • 테이블 헤더를 지반침하 조회 결과 총 {total.toLocaleString()}건으로 지정하고 isHideCount={true}를 적용해, 노후관로와 같은 문구 형식으로 총 건수가 노출되도록 보강했다.
  • 사용자 확인 결과 반경이 정상 적용되었고, 요구한 총 건수 문구가 지반침하 팝업 상단에 표시되는 것을 확인했다.
• 검증 결과
  • 사용자 확인 완료
  • 추가 브라우저 재현 캡처와 빌드 재실행은 이번 라운드에서 수행하지 않음

2.14 2026-06-25 반경 내 관로정보 경과년도 컬럼 및 요약문구 코드 검증

• 검증 대상
  • FE_APP_ROOT/app/(map-layout)/map/components/sinkhole/SinkholeDetailPanel.tsx
  • FE_APP_ROOT/app/(map-layout)/map/components/sinkhole/sinkholeTypes.ts
  • BE_REPO_ROOT/src/main/java/iipbs/ms/domain/SinkholeNearbyPipeRepository.java
  • BE_REPO_ROOT/src/main/java/iipbs/sewerage/api/sinkhole/dto/SinkholeNearbyPipeRowDto.java
• 확인 내용
  • 백엔드 nearbyPipes row DTO에 elapsedYears가 추가되고 native query 결과 매핑 인덱스가 함께 조정됐는지 확인했다.
  • 프론트 반경 내 관로정보 표에서 용도 컬럼을 제외하고 경과년도 컬럼과 제목 아래 요약문구(건수, 평균경과, 최장경과 값 파란색 볼드)가 추가되는지 코드 경로를 확인했다.
  • git diff --check를 FE/BE 변경 파일 기준으로 실행해 공백 오류가 없음을 확인했다.
  • 백엔드 ./gradlew.bat compileJava 통과를 확인했다.
• 미확인 내용
  • FE tsc --noEmit은 로컬 tsc 명령 부재로 실행하지 못했다.
  • 실제 브라우저에서 4개 컬럼과 요약문구가 잘리지 않는지, API 응답 elapsedYears 값으로 평균경과/최장경과가 계산되는지는 개발서버 수동 검증이 필요하다.

2.15 2026-06-25 반경 조회 회귀 방지 확인

• map/page.tsx에 추가했던 반경 조회 fallback 변경을 제거하고, 기존 조회 흐름으로 원복했음을 확인했다.
• FE 컬럼 추가와 타입 추가, BE 응답 필드 추가만 남긴 상태에서 git diff --check를 다시 수행한다.
• 실제 브라우저에서 사고번호 20260026처럼 기존에 24건이 나오던 케이스가 그대로 유지되는지 재확인이 필요하다.

2.16 2026-06-26 레이어 연도범위 설정 전환 사전 분석 결과

• 이번 턴은 구현 전 분석 단계이므로 코드 수정, 브라우저 실행, API 호출 검증은 수행하지 않았다.
• 기존 문서와 코드 경로를 대조한 결과, 현재 지반침하 레이어 조회는 2026년/전체 자식 노드와 applySinkholeYearFilters에 의존하는 구조가 남아 있음을 확인했다.
• SinkholeLayerSettingPanel에는 현재 반경 입력만 있고 시작/종료년도 입력이 없어, 다음 구현에서 패널 props와 상태를 확장해야 한다.
• BE SinkholeListSearchDto와 SinkholeQueryService는 startYmd, endYmd, 최소일 검증을 이미 제공하므로 신규 BE 계약은 필요하지 않은 것으로 판정했다.
• COMMON_DOCS_ROOT/DB작업.sql에는 2026년, 전체 자식 레이어 생성/아이콘 보정 DML이 남아 있어, 다음 구현에서 기준 데이터 삭제/비활성화 DML을 함께 정리해야 한다.
• 다음 검증은 구현 후 지반침하정보 루트 on/off, 설정패널 연도 범위 API 파라미터, 팝업 초기조건 동기화, 기존 반경/상세 회귀 순서로 수행한다.

2.17 2026-06-26 레이어 연도범위 설정 전환 구현 검증 결과

• 코드 검색 결과 2026년/전체 합성 연도 노드 의존 심볼(buildSinkholeYearNodes, isSinkholeYearNode, applySinkholeYearFilters)은 지도 화면 코드에서 제거됐다.
• 변경 TS/TSX 3개 파일(page.tsx, SinkholeLayerSettingPanel.tsx, sinkholeTypes.ts)은 로컬 TypeScript 파서 기준 diagnostics 0건을 확인했다.
• 기존 dev 서버에서 http://localhost:3002/map 요청이 200으로 응답해 페이지 컴파일 진입이 가능함을 확인했다.
• git diff --check는 FE/공통 변경 파일 기준 공백 오류 없음으로 통과했다. Git 줄바꿈 정책 경고는 일부 파일에서만 출력됐다.
• next lint와 tsc --noEmit는 현재 프로젝트 도구 설정 문제로 완료하지 못했다. 실제 로그인 화면에서의 레이어 트리/Network query string 검증은 후속 수동 검증으로 남긴다.

2.18 2026-06-26 상세 fallback 및 설정 UI 보정 검증 결과

• page.tsx와 SinkholeLayerSettingPanel.tsx 변경분을 TypeScript 파서로 확인했고 diagnostics 0건이었다.
• 기존 dev 서버에서 http://localhost:3002/map 요청이 200으로 응답했다.
• git diff --check는 변경 FE 파일 기준 공백 오류 없이 통과했다. Git 줄바꿈 정책상 LF→CRLF 경고만 출력됐다.
• 상세 API 500 상황에서 fallback이 실제 화면에서 패널을 유지하는지, 반경 적용 후 Network 요청이 좌표 기반으로 나가는지는 로그인 세션이 있는 브라우저에서 후속 수동 확인이 필요하다.

3. 미실행 항목

• FE 브라우저 검증
• BE API 호출 검증
• 반경 내 관로 거리 계산 검증
• 관리자 권한 분기 검증
• 다운로드 파일 검증
• FE 빌드 검증
• BE compile/test 최종 검증

미실행 사유:

• 작성자 승인 전 구현 금지 지시
• 이번 턴 범위가 설계 및 문서 초안 작성까지로 제한됨
• 이번 유지보수 라운드에서는 코드 경로 점검과 최소 수정까지만 수행했고, 개발 서버 실행 여부를 확인하지 못해 FE 빌드를 별도로 돌리지 않았다.

4. 현재 상태 판정

• 설계 검토: 완료
• 코드 구현: 완료
• 기능 테스트: 성공
• 브라우저/API 정밀 재검증: 일부 미실행

5. 후속 실행 조건

• 작성자 구현 승인
• FE/BE 코드 반영 완료
• 로그인 가능한 FE/BE 실행 환경 준비
• 관리자/일반 사용자 테스트 계정 준비