frontend/apps/sn/docs/작업내용/SN-도시침수지도-정보제공포털-목록보기/001-fe-SN-도시침수지도-정보제공포털-목록보기-통합구현기록.md

SN 도시침수지도(정보제공포털) 목록보기 통합 구현 기록

1. 문서 목적

• 도시침수지도 목록보기와 일반 지도 표출의 현재 구현 상태를 기능 단위로 통합 기록한다.
• 본 문서에는 2026-08-05 maintenance에서 확정된 WMS·SLD 전환을 최종 일반 표출 기준으로 기록한다.

2. 입력 근거

• 공통 설계: IIPBS/docs/작업계획/SN-도시침수지도-정보제공포털-목록보기/001-de-SN-도시침수지도-정보제공포털-목록보기-설계.md
• WMS·SLD 매뉴얼: IIPBS/docs/작업계획/공통-GeoServer-WMS-SLD적용/001-공통-GeoServer-WMS-SLD적용-매뉴얼.md
• 레이어 설정: sm_bs_sn.tb_sn_lyr_stng
• 대상 레이어: tb_ms_flood_dngr_map

3. 공통 계약

• 화면 노출 빈도는 30년, 50년, 80년이며 100년은 추가하지 않는다.
• 부모 59·60·58은 각각 빈도 030, 050, 080의 실제 WMS 레이어다.
• 자식 15건은 actlLyrYn='N'으로 유지하며 침수심도 SLD와 범례의 메타데이터로 사용한다.
• 백엔드는 기존 레이어 설정 응답 계약을 유지한다.

4. 구현 라운드 요약

4.1 2026-08-04 목록보기 구현

• 도시침수지도 목록 팝업, 검색·페이징·정렬, 그룹 범위 이동을 구현했다.
• 목록 데이터와 범위 조회는 대용량 원본 GeoJSON을 직접 반환하지 않는 구조로 정리했다.
• 이 라운드의 일반 지도 WFS 복원 기록은 2026-08-05 WMS 전환으로 대체한다.

4.2 2026-08-05 일반 지도 WMS·SLD 전환

• gis.wms-sld.js
  • 부모 번호로 자식 레이어 설정 5건을 선별하고 순서를 정렬한다.
  • 자식 필터에서 N330~N334를 추출해 SLD Rule 5개를 만든다.
  • RGBA를 16진 색상과 opacity로 변환하고 XML 특수문자를 이스케이프한다.
  • 정확히 5건의 유효 설정이 아닐 때 null을 반환해 잘못된 스타일 표출을 차단한다.
• gis.layer.js
  • TileWMS 요청에 CQL_FILTER, SLD_BODY, PNG 투명 배경을 적용한다.
  • SLD 내부 레이어명은 접두사 없는 tb_ms_flood_dngr_map을 사용한다.
  • WMS 레이어의 drawOrdr, minViewSize, 문자열 ID를 정상 반영한다.
• gis.core.js
  • SLD 검증 실패로 WMS 레이어가 생성되지 않은 경우 지도 추가를 안전하게 중단한다.
• GisTree.js
  • 실제 WMS 부모를 자동 재생 대상에 포함한다.
  • 숨겨진 자식은 범례 메타데이터로 유지하되 실제 레이어와 자동 재생 대상에서는 제외한다.

5. 기능별 현재 상태

기능	현재 상태
목록 팝업	기존 구현 유지
행 선택 지도 이동	기존 그룹 범위 이동 유지
일반 지도 통신	빈도 부모 3개 TileWMS
빈도 제한	부모 flterSql을 WMS CQL_FILTER로 전달
침수심도 스타일	GeoServer 레이어 기본 스타일(2026-10-16부터, 11절). 이전에는 자식 5건 기반 동적 SLD
범례	숨겨진 자식 설정의 기존 색상·명칭 유지
100년 빈도	화면 및 WMS 전환 대상에서 제외
기존 다른 레이어	기존 WFS 경로 유지

6. BE 공유 사항

• 신규 API나 응답 필드는 필요하지 않다.
• 레이어 설정 DTO의 flterSql, upperLyrSn, lnColor, polgnColor, lnWdth를 계속 제공해야 한다.
• DB 전환 DML은 공통 IIPBS/docs/DB작업.sql에서 관리한다.

7. 검증 요약

• SLD 단위검사 통과
• ESLint 오류 0건
• @common/business_components 빌드 성공
• 개발 DB 부모 3건·자식 15건 정합성 정상
• 30·50·80년 ON/OFF 정상
• 30년 WMS 요청과 SLD 규칙 5개 정상

8. 남은 리스크

• TileWMS는 논리 레이어 1개당 화면 타일 수만큼 GetMap을 요청하므로 HTTP 요청 개수를 정확히 3개로 판단하면 안 된다.
• 운영 프록시의 URL 길이 제한과 GeoServer SLD_BODY 허용 설정은 운영 반영 시 재확인한다.
• 전체 SN Next 빌드는 개발 서버 종료 후 별도 수행한다.

9. 흡수한 기존 문서

• 별도 SN 기능 문서는 없었다. 공통 2026-08-04 바이브코딩 기록의 목록보기 핵심 상태를 본 문서에 요약했다.

10. 2026-09-09 운영 목록 행 선택 이동 보완 공유

• 프론트 코드와 행 선택 메시지 흐름은 변경하지 않았다.
• 운영에서 행 선택 후 그룹 extent API가 ST_Envelope 스키마 해석 오류로 실패해 지도 이동이 중단된 원인을 백엔드 SQL에서 보완했다.
• 기존 시군구·침수빈도 그룹 범위 이동 계약과 화면 동작은 유지한다.
• 재배포 후 목록 행 클릭, 지도 중심 이동, 선택 빈도 WMS 표출을 회귀 확인한다.

11. 2026-10-16 WMS SLD_BODY 제거

• 근거: COMMON_DOCS_ROOT/작업계획/SN-도시침수지도-정보제공포털-목록보기/003-de-SN-도시침수지도-WMS502-SLD_BODY제거-작업계획.md (SFR-011-008·009, 화면설계서 24·28쪽 SN_MN010205·SN_MN010206)
• 운영에서 SLD_BODY가 포함된 WMS 요청이 nginx 502로 실패해, 침수심도 스타일을 GeoServer 레이어 기본 스타일로 옮기고 요청에서 SLD_BODY를 뺐다.
• gis.layer.js
  • getWmsLayer()에서 도시침수지도 SLD_BODY 생성 분기와 gis.wms-sld.js import를 제거했다.
  • STYLES=''(레이어 기본 스타일), 빈도 CQL_FILTER, drawOrdr, minViewSize는 그대로다.
• gis.wms-sld.js: 삭제했다(사용처가 gis.layer.js 하나뿐).
• 범례(water-depth.tsx)는 기존처럼 숨겨진 자식 5건의 DB 색상을 쓴다. GeoServer 기본 스타일이 제공 SLD(tb_ms_flood_dngr_map_depth.sld)로 교체되어야 지도 색과 범례가 일치한다.
• 검증: 남은 참조 없음, git diff --check·ESLint 통과, 개발 GeoServer 동일 파라미터 요청 HTTP 200 PNG.
• 미수행: 사용자 개발 서버 실행 중이라 business_components·sn 빌드 보류, 로그인 필요로 브라우저 Network 확인 보류.
• 롤백: gis.layer.js의 SLD 분기와 gis.wms-sld.js를 복원한다.