frontend/apps/sn/docs/작업계획/SFR-011-008-침수예측/001-fe-SFR-011-008-침수예측현황-작업계획.md

SFR-011-008 침수예측현황 FE 작업계획

작업 목적

지도 분석도구의 기존 침수예측현황 placeholder를 검색·목록·Excel·지도연계가 가능한 실제 WindowPopup으로 전환한다.

근거

• 요구사항: SFR-011-008
• 화면: SN_MN010205 침수예측현황
• route: /popup/fldngPredcPrst
• 참고: PipeAnalysisPopupPage, FloodDngrMapPopupPage, /oper/obsltPplBiz

수정 예정 범위

• src/features/fldngPredcPrst/{api,model,ui}/**
• src/features/windowPopup/model/popupDefinitions.ts
• src/features/windowPopup/registry.tsx
• app/(map-layout)/map/components/analysisMenu/AnalysisPopupMenu.tsx
• 공통 app/(popupLayout)/popup/[popupKey] route는 재사용하고 popup key를 fldngPredcPrst로 변경한다.
• 공통 패키지는 수정하지 않는다.

화면·상태 계약

• 강우시작시각은 최초 진입 시 미입력으로 두고, 분석일시는 오늘 00:00~현재 KST를 기본값으로 설정한다.
• 시도 변경 시 시군구를 전체로 초기화한다.
• 입력 조건과 실제 적용 조건을 분리하여 페이지 이동이 마지막 조회조건을 유지한다.
• 20건 서버 페이징, 허용 컬럼 서버 정렬, 전체건수 기반 no를 제공한다.
• 시도 헤더는 ctpvCd 서버 정렬키를 사용한다.
• 강수량은 소수점 한 자리로 표시하고 초과빈도년도 값은 년 접미사 없이 숫자로 표시한다.
• ListDiv 내부에서 최소 테이블 폭과 가로 스크롤을 제공한다.
• Excel은 현재 적용 검색조건을 동일하게 전달한다.
• 신규 파일과 함수에 화면/API 역할 한글 주석을 작성한다.
• 결과표는 시도, 시군구, 분석시각, 강우시작시각, 관측 누적강수량, 예측시간, 예측 누적강수량, 초과 빈도(년), 침수위험도 순서로 표시한다.
• 예측시간은 N시간 후, 관측·예측 누적강수량은 소수점 한 자리로 표시한다.
• 지도화면 분석도구는 공용 분석시각 범위와 위험 조건의 count API를 조회하여 침수예측현황(x건)으로 표시한다.

지도 연계

• 행 선택 시 기존 도시침수지도 group extent API를 호출한다.
• 부모 창에 기존 MAP_SEARCH_SHOW_FLOOD_GROUP 메시지를 보내 범위 이동·레이어 표시를 요청한다.
• 도시침수지도 빈도는 30년 이하를 030, 100년 초과를 100으로 보정하고 그 외 미지원 빈도는 안내한다.

검증

• TypeScript 정적검사 및 sn 빌드(실행 중 개발서버가 없거나 사용자 확인 후)
• /popup/fldngPredcPrst 직접 진입
• 분석도구 클릭 별도 창 진입
• 기본 날짜·종속 시군구·조회·페이지·정렬·가로스크롤
• Excel 파일명/열/검색조건
• 행 클릭 후 부모 지도 Network·extent·레이어 동작

롤백과 위험

• 신규 route/feature를 제거하고 registry를 placeholder로 복원한다.
• 팝업 경로와 기존 popup key가 다르므로 route 연결 누락을 회귀 확인한다.
• 행정구역 코드와 도시침수지도 빈도 자료가 없는 행은 지도 이동이 제한될 수 있다.

구현 결과 (2026-08-13)

• 분석도구 메뉴와 WindowPopup key를 fldngPredcPrst로 변경하고 placeholder를 실제 화면으로 교체했다.
• 강우시작시각 미입력·분석일시 당일 00:00~현재 기본값, 시도·시군구 종속조건, 두 날짜 범위, 빈도년도 검색을 구현했다.
• 20건 서버 페이징·정렬, ListDiv 가로 스크롤, 적용조건 기준 Excel 다운로드를 구현했다.
• 행 클릭 시 기존 extent API와 MAP_SEARCH_SHOW_FLOOD_GROUP 메시지를 사용한다.
• 도시침수지도가 없는 빈도는 30·50·80년 중 임의 근사하지 않고 안내한다.
• 2026-08-18 시도 헤더를 정렬 가능 상태로 전환하고 ctpvCd 서버 정렬을 연결했다.
• pnpm --filter sn run build를 통과했다.
• 독립 tsc --noEmit은 현재 수정과 무관한 조사사업·침수이력·지도·노후관로·팝업 registry 등의 기존 타입 오류로 실패했다. 이번 변경 파일에서는 오류가 보고되지 않았다.
• 2026-08-18 목록 강수량을 소수점 한 자리로, 헤더를 초과빈도년도로 변경하고 값의 년 접미사를 제거했다.
• 기존 .next 산출물을 재생성한 뒤 pnpm --filter sn run build를 최종 통과했다.
• TypeScript 정적검사는 저장소 기존 ignoreDeprecations 설정과 실행 중 산출물 잠금 때문에 완료하지 못했고, Next 빌드는 최적화 단계 장기 대기 후 중단했다.

Excel 프론트 생성 전환 결과 (2026-09-03)

• 현재 적용 검색조건으로 /api/v1/fldng/predc/prst를 500건 단위 전체 페이지 조회한다.
• 공통 fetchAllPages로 totalElements와 실제 수집 건수 일치를 검증한다.
• fldng-predc-prst-excel.ts가 화면 열 순서의 단일 시트 침수예측현황.xlsx를 브라우저에서 생성한다.
• 서버 /prst/excel Blob 호출과 getBlobData, fileDownload 사용을 제거했다.
• 독립 TypeScript --noEmit 검증을 통과했다.

2026-10-21 강우 명칭·시간 단위 입력 통일 계획 (2026-10-21 승인·구현)

배경

• 사용자 지시(2026-10-21)
  • 강우 관련 명칭: 검색란 강우시각, 목록 강우시작시각. 침수예측현황도 바꿔야 하면 이 문서에 추가한 뒤 승인 후 수정한다.
  • 검색란의 분석시각·강우시각은 datetime-local(2026-10-21 오후 03:00 형태)로 두되 시간까지만 선택한다. 분은 00으로 고정하고 수정할 수 없다. 침수예측현황도 같이 수정한다.
• 통수위험 쪽 계획: COMMON_DOCS_ROOT/작업계획/SFR-011-007-통수위험분석/004-de-SFR-011-007-통수위험분석-매핑관로없음위험-분석시각-작업계획.md 16절.

현재 명칭

위치	현재	기준과 일치
검색란 라벨 (ui/fldng-predc-prst-popup-content.tsx)	강우시각	예
목록 컬럼 (ui/fldng-predc-prst-popup-content.tsx)	강우시작시각	예
지도 정보 (lib/use-flood-prediction-map.ts)	강우시작시각	예
검색 오류 문구 (ui/fldng-predc-prst-popup-content.tsx validateFilters)	강우 시작시각의 시작은 종료보다 늦을 수 없습니다.	아니오(검색란 이름은 강우시각)
Excel 머리글 (lib/fldng-predc-prst-excel.ts HEADERS.rainBeginningDateTime)	강우 시작시각	아니오(목록은 붙여 쓴 강우시작시각)

• 화면에 보이는 라벨과 목록 컬럼 이름은 이미 기준과 같다. 이름은 문구 2곳만 맞춘다.

시간 단위 입력 결론

• 현재 분석시각·강우시각 입력(renderDateTimeRange)은 datetime-local이라 분까지 고를 수 있다.
• step={3600}(1시간)을 주면 값의 분이 00일 때 브라우저가 분 칸을 고정해 바꿀 수 없다. 빈 값에서 처음 입력할 때처럼 분이 들어오는 경우는 onChange에서 분을 00으로 맞춘다. 입력 폭(w-[17rem])과 표시 형태는 그대로다.
• API는 지금처럼 yyyyMMddHHmm을 보내며 분만 항상 00이 된다. BE는 문자열 시작 이상·종료 이하로 비교하므로(FldngPredcPrstRepository.addRange) BE 변경은 없다.
• 개발 DB tb_sn_fldng_predc_anls 208건의 분석시각(obsrvn_tm)·강우시작시각(rain_bgng_tm)이 모두 정시(분 00)라서 시간 단위 조건으로 빠지는 자료는 없다.

수정 계획

번호	파일	변경
1	src/features/fldng-predc-prst/ui/fldng-predc-prst-popup-content.tsx	오류 문구 강우 시작시각의 시작은 종료보다 늦을 수 없습니다. → 강우시각의 시작은 종료보다 늦을 수 없습니다.
2	src/features/fldng-predc-prst/lib/fldng-predc-prst-excel.ts	Excel 머리글 강우 시작시각 → 강우시작시각
3	src/features/fldng-predc-prst/ui/fldng-predc-prst-popup-content.tsx	renderDateTimeRange의 시작·종료 입력 4개(분석시각·강우시각)에 step={3600} 추가, onChange에서 분을 00으로 맞춰 저장

• 바꾸지 않는 것: API 파라미터·정렬 키, 기본값(빈 값), 분석도구 메뉴의 침수예측 건수 조회 범위(model/analysis-time-range.ts, 입력란과 무관).

검증·영향·롤백

• 검증: 분석시각·강우시각 입력에서 분 칸이 00으로 고정되는지, 빈 값에서 새로 입력해도 분이 00이 되는지 확인. 시작 > 종료로 강우시각을 넣어 바뀐 오류 문구 확인, 조회 요청의 시각 파라미터 끝 두 자리가 00인지 확인, Excel 다운로드 머리글 확인. tsc --noEmit·git diff --check.
• 영향: 침수예측현황 팝업의 검색 입력 4개, 오류 문구, Excel 머리글 1칸. API·DB·지도 영향 없음.
• 롤백: 위 2개 파일을 되돌린다.

구현 결과 (2026-10-21)

• 계획 1~3을 그대로 반영했다. ui/fldng-predc-prst-popup-content.tsx: 오류 문구 강우시각의 시작은 종료보다 늦을 수 없습니다., 분석시각·강우시각 입력 4개에 step={3600}과 분 00 고정(toHourInputValue). lib/fldng-predc-prst-excel.ts: Excel 머리글 강우시작시각.
• 검증: tsc --noEmit(sn 전체) 통과, git diff --check 통과. ESLint는 수정 전과 같은 1건(기존 미사용 import createPredictionAnalysisTimeRange, 이번 범위 밖). 로그인이 필요해 실제 팝업 화면과 Excel 다운로드는 미확인.
• BE·API·DB 변경 없음.