frontend/apps/sn/docs/작업계획/SFR-011-007-통수위험분석/002-fe-SFR-011-007-통수위험분석-실API연동및검증.md

SFR-011-007 통수위험분석 FE 실 API 연동 및 검증

1. 목적

• 기존 FE mock 결과를 /api/v1/waterRisk/** 실제 응답으로 교체한다.
• 부모 지도와 popup의 기존 sn 글꼴·조회조건 디자인을 유지한다.
• 사용자 결정에 따라 설정 버튼·설정 화면·설정 API는 제공하지 않는다.

2. 구현 내용

• WaterRiskPopupPage.tsx
  • 현재 위험/과거 이력 탭, 날짜·시도·시군구·중점관리지역·위험상태 조회
  • 서버 페이지네이션, 로딩·오류·빈 결과 처리
  • 현재누적강우량 원천이 없으면 - 표기
  • 현재 탭은 예측강우량, 과거 탭은 최대강우강도 컬럼 사용
  • 결과 행 선택 시 mapView 조회 후 부모창에 결과와 geometry 전달
• waterRiskClient.ts
  • 중점관리지역, 결과 목록, mapView 실제 API 호출
• waterRiskTypes.ts
  • 실제 API 계약, nullable 강우 필드, RATIONAL_MANNING, 관로별 위험상태 정의
• map/page.tsx
  • EPSG:5179 MultiPolygon/MultiLineString 강조
  • 선택 지역 fit/정보 카드 표시
  • 유출유량·통수량 단위를 ㎥/s로 통일

3. 검증 결과

• URL: http://localhost:3002/popup/flowRiskPopup
• 실제 API로 위험/정상 행, 현재/과거 탭, 위험상태 필터, 시도→시군구→중점관리지역 cascade 확인
• 결과 행 클릭 후 mapView 요청 성공과 부모 지도 강조 메시지 확인
• popup 콘솔 오류 없음
• 화면 증적: COMMON_DOCS_ROOT/작업내용/SFR-011-007-통수위험분석/검증/001-통수위험-현재위험-실API.png
• 앱 TypeScript 전체 검사는 통수위험 변경 파일 오류가 없었으나, 기존 타 기능의 타입 오류 때문에 전체 명령은 실패했다.
  • 실행: apps/sn/node_modules/.bin/tsc.CMD -p apps/sn/tsconfig.json --noEmit --pretty false --incremental false --ignoreDeprecations 5.0
  • 잔여 오류: fldngHstry, GIS 관리, exmn, 메뉴 alias, map/page.tsx의 기존 storageNm 등 이번 범위 밖 baseline
• 사용자 소유 Next 개발 서버는 중단하거나 빌드하지 않았다.

4. 영향·롤백·잔여 위험

• 영향: components/waterRisk/**, 부모 지도에서 통수위험 결과 메시지와 geometry 표시 부분
• 롤백: waterRiskClient.ts를 제거하고 popup의 실제 조회/부모 메시지 변경 및 map/page.tsx 통수위험 mapView 처리를 되돌린다.
• 자동화 도구가 새 창 popup을 부모 탭과 동시에 제어하는 데 제한이 있어, popup의 실제 mapView 요청과 부모 메시지 처리 코드를 각각 확인했다. 최종 사용자 회귀 시 부모 지도에서 popup을 열고 한 행을 선택하는 시나리오를 한 번 더 수행할 수 있다.
• 현재누적강우량은 백엔드 원천 미확보로 -이며, 예측강우 격자 overlay는 이번 합리식 결과 범위에 포함하지 않는다.

5. 2026-10-20 위험(매핑관로없음)·분석시각 컬럼·분석시각 기간 검색

• 근거: COMMON_DOCS_ROOT/작업계획/SFR-011-007-통수위험분석/004-de-...-매핑관로없음위험-분석시각-작업계획.md 1~8 승인. 원본 화면설계서 19·21쪽(SN_MN010201·010202), 요구사항 SFR-011-007.
• components/water-risk/water-risk-types.ts: WaterRiskStatus에 DANGER_UNMAPPED 추가, 라벨 위험(매핑관로없음), 위험 색 판별 isWaterRiskDanger().
• components/water-risk/water-risk-popup-page.tsx
  • 목록: 중점관리지역 다음 분석시각 컬럼(정렬 가능, 컬럼 id = BE 정렬 키 analysisBaseAt), 컬럼 폭 재배분, 최소 폭 124rem → 136rem, 위험 배지 줄바꿈 방지.
  • 과거이력 검색패널: 분석시각 기간(시작 날짜·시 ~ 종료 날짜·시, 선택). 기본·초기화는 빈 값이며 적용 시 validateWaterRiskAnalysisPeriod로 검증한다. 위험상태 필터에 위험(매핑관로없음) 추가. 하단 판정 안내 문구 갱신.
  • 현재 탭은 기존처럼 현재 정시 analysisBaseAt만 보낸다.
• components/water-risk/water-risk-client.ts: analysisBaseFrom·analysisBaseTo를 둘 다 있을 때만 쿼리스트링에 넣는다.
• components/water-risk/water-risk-date-range.ts: buildWaterRiskAnalysisDateTime, validateWaterRiskAnalysisPeriod(짝 입력, 시작 ≤ 종료, 종료 ≤ 현재 정시, 366일) 추가.
• lib/water-risk-styles.ts, ui/map-page-client.tsx: 지도 구역 색·정보카드 배지를 isWaterRiskDanger()로 판정해 위험(매핑관로없음)도 빨강으로 표시한다.
• 검증: git diff --check 통과, tsc --noEmit(sn 전체) 통과, 변경 6개 파일 ESLint 문제 수가 수정 전(HEAD)과 동일(기존 map-page-client.tsx 46 errors 등은 baseline). 개발 서버가 꺼져 있어 화면 확인은 미실행, next build 미실행.
• 롤백: 위 6개 파일을 되돌린다.
• 2026-10-20 추가: BE mapView 위험상태가 목록과 같은 대표결과 판정값으로 바뀌어, lib/use-water-risk-layer.ts의 정보카드 상태 우선순위 주석만 갱신했다(동작 변경 없음).

6. 2026-10-21 지도 조회 키를 SWMM 실행 ID로 변경

• 근거: COMMON_DOCS_ROOT/작업계획/SFR-011-007-통수위험분석/004-de-...-작업계획.md 15절 9~13 승인.
• components/water-risk/water-risk-types.ts: WaterRiskResultRow.executionId, WaterRiskMapView.executionId·analysisBaseAt·rainStartedAt, WaterRiskSessionSnapshot.selectedExecutionId 추가.
• components/water-risk/water-risk-client.ts: 지도 조회를 v1/waterRisk/executions/{executionId}/mapView로 변경(날짜·지역 경로 미사용).
• components/water-risk/water-risk-popup-page.tsx: 행 식별 키를 executionId로 변경(없으면 기존 조합), 부모 동기화 메시지에 selectedExecutionId가 있으면 그 행만 선택 표시.
• lib/use-water-risk-layer.ts: 지도 응답과 행의 실행 ID가 다르면 무시, 세션에 selectedExecutionId 저장.
• 검증: tsc --noEmit 통과, 변경 4개 파일 ESLint 문제 수 수정 전과 동일, git diff --check 통과. 화면 확인은 BE 재기동 후 필요(현재 BE는 이전 코드라 새 지도 API 없음).
• 롤백: 위 4개 파일 복원. BE의 구 지도 API가 유지되는 동안은 FE만 되돌려도 기존 동작으로 복귀한다.

7. 2026-10-21 과거이력 검색조건 순서·명칭·시간 단위 입력

• 근거: COMMON_DOCS_ROOT/작업계획/SFR-011-007-통수위험분석/004-de-...-작업계획.md 16절 결정 14~17 승인. 원본 화면설계서 19쪽 SN_MN010201, 요구사항 SFR-011-007.
• components/water-risk/water-risk-popup-page.tsx
  • 과거이력 검색조건 순서를 시도 → 시군구 → 중점관리지역 → 분석시각 → 강우시각 → 위험상태로 바꿨다(현재 탭은 중점관리지역만).
  • 명칭: 검색란 강우 발생기간 → 강우시각, 목록 컬럼 강우시작시간 → 강우시작시각(컬럼 id·정렬 키 rainStartedAt 유지).
  • 분석시각·강우시각 입력을 침수예측현황과 같은 datetime-local 시작 ~ 종료(w-[17rem])로 바꾸고 step={3600}을 줬다. 분은 00으로 고정되고, 분이 들어오면 저장 전에 00으로 내린다. 현재 정시 이후는 max로 막는다.
  • 검색조건 상태를 rainStartedFrom·rainStartedTo(필수, 기본 365일 전 00시 ~ 현재 정시), analysisFrom·analysisTo(선택)로 정리했다. 조회 시 yyyy-MM-ddTHH:00:00으로 보내고, startDate·endDate는 강우시각 날짜로 맞춘다. 현재 탭은 기존처럼 최근 1년 날짜와 현재 정시 analysisBaseAt만 보낸다.
• components/water-risk/water-risk-date-range.ts: 시간 단위 값 변환(toWaterRiskHourValue·formatWaterRiskHourValue·toWaterRiskApiDateTime)과 기간 검증(validateWaterRiskRainStartedPeriod 필수, validateWaterRiskAnalysisPeriod 선택: 짝 입력·정시·시작 ≤ 종료·종료 ≤ 현재 정시·366일)으로 정리. 오류 문구는 강우시각…/분석시각….
• components/water-risk/water-risk-client.ts: rainStartedFrom·rainStartedTo를 둘 다 있을 때만 전달.
• 검증: tsc --noEmit(sn 전체) 통과, 변경 3개 파일 ESLint 0건(수정 전과 같음), git diff --check 통과. step=3600 입력의 분 고정은 앱 내장 브라우저(Chromium 152)에서 따로 확인했다. 로그인이 필요해 실제 팝업 화면은 미확인, next build 미실행.
• 롤백: 위 3개 파일을 되돌린다. BE의 새 파라미터는 선택값이라 FE만 되돌려도 동작한다.