침수흔적도 목록/지도 상세 팝업 mock 구현 및 md 업데이트

2026-06-15 16:28:37 +09:00
parent 83a3810301
commit e47c00f0b6
13 changed files with 1602 additions and 17 deletions
@@ -0,0 +1,79 @@
+# SFR-011-009 침수발생이력 통합 검증 계획
+
+## 1. 문서 목적
+
+- `SFR-011-009 침수발생이력`의 FE 검증 계획을 기능당 1개 문서로 누적 관리한다.
+- 현재 문서는 docs-first 설계 완료 직후 기준으로, FE-only 범위 검증 항목과 후속 통합 검증 항목을 분리한다.
+
+## 2. 검증 기준 요약
+
+- 레이어 트리 `침수흔적도` 목록 popup이 정상적으로 열린다.
+- `침수흔적도` on/off가 지도 표시와 맞게 동작한다.
+- 조회조건 유효성 검증이 동작한다.
+- `침수발생년도` 선택이 동작한다.
+- 목록이 조건에 따라 필터링된다.
+- 목록 다운로드가 현재 조회 결과 기준으로 동작한다.
+- 행 클릭 시 메인 지도 preview가 뜬다.
+- 지도 위 큰 침수흔적 레이어 클릭 시 작은 상세 팝업이 열린다.
+
+## 3. FE-only 검증 계획
+
+### 3.1 popup 진입
+
+- 레이어 트리 `침수흔적도` 체크
+- 레이어 트리 `침수흔적도`의 목록 버튼 클릭
+- popup open 여부
+- popup 제목, 조회조건 영역, 목록 그리드 노출 여부
+
+### 3.2 조회조건 검증
+
+- 시도 미선택 상태에서 시군구 선택 후 조회 시 차단되는지 확인
+- 침수발생년도 선택 시 목록 필터가 반영되는지 확인
+- 침수재해명 키워드 입력 시 목록 필터가 적용되는지 확인
+
+### 3.3 목록/다운로드
+
+- 조회 결과 총 건수 표시
+- `강우 분석정보` 묶음 헤더와 하위 4개 컬럼 표시
+- 나머지 상세 필드가 가로 스크롤로 모두 노출되는지 확인
+- 10건 초과 시 페이지네이션 노출
+- 다운로드 버튼 클릭 시 현재 필터링 결과 기준 파일이 생성되는지 확인
+- 결과 없음 상태에서 다운로드가 차단되는지 확인
+
+### 3.4 지도 연동
+
+- 행 클릭 시 지도 preview 표시 여부
+- 행 더블클릭 시 popup close 여부
+- 메인 지도 영역으로 fit 이동되는지 확인
+- `침수흔적도` 체크 시 mock polygon과 침수심 overlay가 함께 표시되는지 확인
+- `침수흔적도`를 끄면 관련 표시가 함께 숨겨지는지 확인
+- 큰 침수흔적 polygon 클릭 시 상세 팝업이 뜨는지 확인
+
+### 3.5 지도 상세 팝업
+
+- `침수년도탭`, `재해명탭`, `침수발생강우탭` 전환
+- 기술 컬럼 제외 후 한글 업무 항목만 보이는지 확인
+- 각 탭의 테이블 구조와 값 표시
+- 닫기 시 팝업만 닫히는지 확인
+
+## 4. BE 연동 후 검증 계획
+
+- 실제 목록 조회 API 필드 매핑
+- 실제 geometry 및 지도 위치 정합성
+- 지도 click 상세조회
+- 실제 레이어 트리 `침수흔적도` 토글 연계
+- 다운로드 권한 및 파일 포맷 검증
+
+## 5. 차단 사유 분류 기준
+
+- `기능 결함`
+- `인증 차단`
+- `환경 차단`
+- `데이터 차단`
+- `자동화 한계`
+
+## 6. 현재 상태
+
+- 공통 설계서 작성 완료
+- FE 작업카드 작성 완료
+- 구현은 진행 중이며, 검증은 FE-only 기준으로 먼저 수행한다.
@@ -0,0 +1,52 @@
+# SFR-011-009 침수발생이력 통합 검증 결과
+
+## 1. 문서 목적
+
+- `SFR-011-009 침수발생이력`의 현재 검증 결과와 남은 수동 확인 항목을 누적 관리한다.
+- 현재 문서는 FE draft 구현 직후 기준의 로컬 응답 확인과 자동화 한계 항목을 기록한다.
+
+## 2. 이번 라운드 결과 요약
+
+- 상태: 부분 확인
+- 확인 완료
+  - `localhost:3002` 기본 응답 200 확인
+  - `localhost:3002/map` 응답 200 확인
+  - 공통 설계서, FE 작업카드, FE 검증계획 작성 완료
+- 미완료
+  - popup 실제 진입 확인
+  - 목록 조회/행 클릭 preview/메인 지도 플로팅 상세팝업 수동 확인
+  - 다운로드 파일 수동 확인
+
+## 3. 세부 결과
+
+### 3.1 환경 확인
+
+- `pnpm --filter sn run dev`는 샌드박스 내에서 `spawn EPERM`으로 실패했다.
+- 권한 상승 후 로컬 서버를 열어 `http://127.0.0.1:3002`, `http://127.0.0.1:3002/map` 응답 200을 확인했다.
+
+### 3.2 자동/간접 확인
+
+| 항목 | 결과 | 메모 |
+| --- | --- | --- |
+| 로컬 서버 기본 응답 | 통과 | `/` 200 |
+| 지도 메인 경로 응답 | 통과 | `/map` 200 |
+| popup 경로 직접 요청 | 보류 | 초기 컴파일 지연 또는 자동 요청 timeout 가능성 |
+| 실제 popup 클릭 | 보류 | 사용자가 로컬 수동 검증 예정 |
+| 행 클릭 preview | 보류 | 사용자가 로컬 수동 검증 예정 |
+| 더블클릭 후 지도 이동 | 보류 | 사용자가 로컬 수동 검증 예정 |
+| 지도 클릭 플로팅 팝업 | 보류 | 사용자가 로컬 수동 검증 예정 |
+
+## 4. 남은 수동 검증 항목
+
+1. 레이어 트리 `침수흔적도` 목록 버튼으로 popup이 정상적으로 열리는지 확인
+2. 조회조건 입력과 목록 필터가 기대대로 동작하는지 확인
+3. 목록 행 클릭 시 메인 지도에 테스트 레이어가 보이는지 확인
+4. 목록 행 더블클릭 시 popup이 닫히고 메인 지도 이동이 유지되는지 확인
+5. 큰 침수흔적 polygon 클릭 시 작은 상세 팝업이 뜨는지 확인
+6. `침수흔적도` on/off에 따라 영역/침수심 overlay가 메인 지도에 맞게 보이는지 확인
+7. 상세 팝업 탭과 표 구성이 자연스러운지 확인
+
+## 5. 결론
+
+- FE draft 구현과 문서 선행 정리는 완료됐다.
+- 최종 상태는 사용자 로컬 수동 검증 결과를 반영한 뒤 `검증 통과` 또는 `추가 보완 필요`로 갱신한다.
@@ -0,0 +1,117 @@
+# SFR-011-009 침수발생이력 작업카드
+
+## 1. 작업 개요
+
+- 작업 ID: `SFR-011-009-FE`
+- 작업명: 침수발생이력 프론트엔드 구현
+- 상태: 검증
+- 작성일: 2026-06-15
+- 담당 역할: FE
+- 관련 역할: DE, QA
+- 담당 범위: `apps/sn` 지도 화면에서 레이어 트리 `침수흔적도` 목록 popup, 목록 조회, 지도 preview, 지도 클릭 플로팅 상세 팝업, mock 침수심 overlay 구현
+- 근거 문서
+  - `COMMON_DOCS_ROOT/작업계획/SFR-011-009-침수발생이력/001-de-SFR-011-009-침수발생이력-설계.md`
+  - `COMMON_DOCS_ROOT/작업지시/SFR-011-009-침수발생이력/0.침수발생이력_요구사항명세서_v2.0.docx`
+  - `COMMON_DOCS_ROOT/작업지시/SFR-011-009-침수발생이력/5.침수발생이력_화면시나리오_V2.0.md.docx`
+  - `COMMON_DOCS_ROOT/작업지시/SFR-011-009-침수발생이력/침수발생이력 목록화면설계서.png`
+  - `COMMON_DOCS_ROOT/작업지시/SFR-011-009-침수발생이력/침수발생이력 지도상세정보화면설계서.png`
+  - `COMMON_DOCS_ROOT/작업지시/SFR-011-009-침수발생이력/침수발생이력_화면.html`
+
+## 1-1. 공통 동기화 확인
+
+- 공통 작업현황판 확인 여부: 확인
+- 파일점유현황 확인 여부: 확인
+- 결정로그 확인 여부: 확인
+- 기존 진행 중 작업과의 관계: `map/page.tsx`, `windowPopup/**`는 다른 지도형 기능과 최근 수정 이력이 있어 충돌 주의가 필요하다.
+
+## 2. 작업 목적
+
+- 레이어 트리 `침수흔적도` 목록 진입을 placeholder가 아닌 실제 popup UI로 연결한다.
+- popup 조회 결과를 메인 지도와 연동해 사용자가 선택한 침수발생이력을 즉시 확인할 수 있게 한다.
+- 설계 이미지의 `침수흔적도 on/off + 목록 popup + 지도 강조 + 지도 위 상세 팝업` 흐름을 현재 `sn` 지도형 구조 안에서 자연스럽게 재현한다.
+
+## 3. 수정 대상 파일
+
+| 구분 | 파일 경로 | 수정 여부 | 비고 |
+| --- | --- | --- | --- |
+| 메인 지도 | `FE_APP_ROOT/app/(map-layout)/map/page.tsx` | 진행 | popup 선택 결과 수신, 지도 overlay, 우측 상세패널 연결 |
+| popup 정의 | `FE_APP_ROOT/src/features/windowPopup/model/popupDefinitions.ts` | 진행 | tree 목록 진입 popup 키/크기 정의 |
+| popup 등록 | `FE_APP_ROOT/src/features/windowPopup/registry.tsx` | 진행 | placeholder에서 실제 popup content로 교체 |
+| 분석도구 메뉴 | `FE_APP_ROOT/app/(map-layout)/map/components/analysisMenu/AnalysisPopupMenu.tsx` | 진행 | 분석도구에서 `침수발생이력` 제거 |
+| popup content | `FE_APP_ROOT/src/features/windowPopup/ui/FloodHistoryPopupContent.tsx` | 진행 | popup 본문 연결 |
+| 신규 popup 페이지 | `FE_APP_ROOT/app/(map-layout)/map/components/floodHistory/FloodHistoryPopupPage.tsx` | 진행 | 조회조건/목록/다운로드 |
+| 신규 상세패널 | `FE_APP_ROOT/app/(map-layout)/map/components/floodHistory/FloodHistoryDetailPanel.tsx` | 진행 | 기본정보/발생일시/원인·피해 탭 |
+| 신규 타입/샘플데이터 | `FE_APP_ROOT/app/(map-layout)/map/components/floodHistory/floodHistoryTypes.ts` | 진행 | mock 데이터, postMessage 타입, legend 정의 |
+
+## 4. 구현 범위
+
+### 4.1 이번 라운드 포함
+
+- 레이어 트리 `침수흔적도` 목록 popup 진입
+- 레이어 트리 `침수흔적도` on/off
+- 시도/시군구/침수발생년도 선택/침수재해명 조회조건
+- mock 목록 조회/페이징
+- 목록 다운로드
+- 목록 행 클릭 preview + 더블클릭 후 메인 지도 이동
+- 메인 지도 mock polygon/침수심 overlay
+- 지도 클릭 플로팅 상세 팝업
+- `강우 분석정보` 묶음 헤더 유지 + 상세 필드 가로 스크롤 그리드
+
+### 4.2 이번 라운드 제외
+
+- 실제 백엔드 API 연동
+- 실제 레이어 트리 토글 연계
+- 지도 click 상세조회
+- 실제 기준데이터 기반 GIS layer 렌더링
+
+## 5. 화면 흐름
+
+1. 사용자가 레이어 트리에서 `침수흔적도`를 체크한다.
+2. 사용자가 `침수흔적도` 목록 버튼을 클릭한다.
+3. popup이 열린다.
+4. 사용자가 조회조건을 입력하고 `조회`를 클릭한다.
+5. 목록이 popup 그리드에 표시된다.
+6. 사용자가 행을 클릭하면 메인 지도에 테스트 레이어가 먼저 표시된다.
+7. 사용자가 행을 더블클릭하면 popup이 닫히고 메인 지도는 해당 침수 이력 영역으로 이동한다.
+8. `침수흔적도` 체크 상태에 따라 영역/침수심 표현이 함께 보인다.
+9. 메인 지도 위 큰 침수흔적 영역을 클릭하면 작은 상세 팝업이 열린다.
+
+## 6. 구현 메모
+
+- popup은 기존 `windowPopup` 체계를 그대로 사용하되, 분석도구가 아니라 레이어 트리 `침수흔적도` 목록 버튼으로 연다.
+- 목록 선택 결과는 `window.opener.postMessage`로 메인 지도에 전달한다.
+- popup의 `침수발생년도`는 같은 필터 줄 안의 선택 컴포넌트로 처리한다.
+- 메인 지도는 `VectorLayer` 두 개를 사용해
+  - 침수발생이력상세 영역
+  - 침수심 표현 영역
+  을 임시 렌더링한다.
+- 두 overlay는 `침수흔적도` 체크 상태를 따르도록 맞춘다.
+- 상세정보는 우측 패널이 아니라 지도 위 플로팅 팝업으로 노출하고, 탭은 `침수년도탭`, `재해명탭`, `침수발생강우탭` 기준으로 보여준다.
+
+## 7. 검증 방법
+
+- 레이어 트리 `침수흔적도` 목록 popup이 열린다.
+- `침수흔적도` 체크 on/off에 따라 영역/침수심 overlay가 함께 바뀐다.
+- 시도 없이 시군구를 선택하면 조회가 차단된다.
+- 침수발생년도 선택이 동작한다.
+- 조건 변경 시 목록 필터가 바뀐다.
+- 행 클릭 시 지도 preview가 표시된다.
+- 지도 위 큰 polygon 클릭 시 작은 상세 팝업이 열린다.
+- 상세 팝업 탭 전환이 동작한다.
+
+## 8. 현재 메모
+
+- 문서 우선 원칙에 맞춰 이번 라운드는 설계서/작업카드/검증계획을 먼저 정리한 뒤 구현을 이어간다.
+- 현재 코드에는 일부 draft 구현이 이미 들어가 있으므로, 이후 단계에서 이 작업카드 기준으로 정합성을 다시 맞춘다.
+
+## 9. 롤백 방법
+
+- 레이어 트리 목록 진입 연결 해제
+- `floodHistory` 신규 컴포넌트 삭제
+- `map/page.tsx`의 floodHistory overlay/상세패널 분기 제거
+
+## 10. 남은 리스크
+
+- 실제 API 필드명이 mock 데이터와 다를 수 있다.
+- 실제 지도 레이어 기준데이터가 준비되면 현재 mock overlay 방식과 상태 관리가 달라질 수 있다.
+- popup 상세정보를 우측 패널로 둘지 지도 내부 floating popup으로 둘지는 실제 사용성 피드백 후 재조정 가능성이 있다.
@@ -0,0 +1,73 @@
+# SFR-011-009 침수발생이력 통합 구현 기록
+
+## 1. 문서 목적
+
+- `SFR-011-009 침수발생이력`의 FE 구현 이력과 남은 리스크를 기능당 1개 문서로 누적 관리한다.
+- 현재 문서는 docs-first 재정렬 이후의 1차 FE draft 구현 상태를 기록한다.
+
+## 2. 입력 근거
+
+- `COMMON_DOCS_ROOT/작업계획/SFR-011-009-침수발생이력/001-de-SFR-011-009-침수발생이력-설계.md`
+- `COMMON_DOCS_ROOT/작업내용/SFR-011-009-침수발생이력/001-fe-SFR-011-009-침수발생이력-통합공유기록.md`
+- `FE_APP_DOCS_ROOT/작업계획/SFR-011-009-침수발생이력/001-fe-SFR-011-009-침수발생이력-작업카드.md`
+
+## 3. 구현 라운드 요약
+
+### 3.1 2026-06-15 docs-first 재정렬
+
+- 수행 내용
+  - 작업지시 DOCX, 시나리오 DOCX, 설계 PNG, HTML 시안을 먼저 읽고 기능 범위를 재정리했다.
+  - 공통 설계서, FE 작업카드, FE 통합검증계획을 먼저 작성했다.
+  - 공통 작업현황판/파일점유현황에 `SFR-011-009-DE-FE-PLAN` 진행 상태를 등록했다.
+
+### 3.2 2026-06-15 FE draft 구현
+
+- 반영 파일
+  - `FE_APP_ROOT/app/(map-layout)/map/page.tsx`
+  - `FE_APP_ROOT/app/(map-layout)/map/components/analysisMenu/AnalysisPopupMenu.tsx`
+  - `FE_APP_ROOT/src/features/windowPopup/model/popupDefinitions.ts`
+  - `FE_APP_ROOT/src/features/windowPopup/registry.tsx`
+  - `FE_APP_ROOT/src/features/windowPopup/ui/FloodHistoryPopupContent.tsx`
+  - `FE_APP_ROOT/app/(map-layout)/map/components/floodHistory/FloodHistoryPopupPage.tsx`
+  - `FE_APP_ROOT/app/(map-layout)/map/components/floodHistory/FloodHistoryDetailPanel.tsx`
+  - `FE_APP_ROOT/app/(map-layout)/map/components/floodHistory/floodHistoryTypes.ts`
+- 구현 내용
+  - 분석도구의 `침수발생이력` 항목은 제거하고, 레이어 트리 `침수흔적도` 목록 진입으로 popup을 열도록 바꿨다.
+  - `침수발생이력` popup placeholder를 실제 popup 페이지로 교체했다.
+  - 시도/시군구/침수발생년도 선택/침수재해명 조회조건과 mock 목록 조회/다운로드를 연결했다.
+  - 그리드는 현재 파란 톤을 유지하되, 사용안함 항목을 제외한 상세 필드를 모두 노출하도록 바꾸고 가로 스크롤을 허용했다. `강우 분석정보` 묶음은 유지하면서 뒤쪽 컬럼을 재배치했다.
+  - 행 클릭 시 popup을 유지한 채 `postMessage`로 메인 지도에 mock preview를 보내고, 더블클릭 시 popup을 닫도록 구성했다.
+  - 메인 지도는 mock polygon layer와 침수심 표현 layer를 임시 `VectorLayer`로 그리도록 구성했고, 표시 여부는 `침수흔적도` 체크 상태를 따르도록 보정했다.
+  - 메인 지도 우측 상세패널은 제거하고, 지도 위 큰 침수흔적 영역 클릭 시 작은 플로팅 팝업이 열리도록 바꿨다.
+  - 상세 팝업 탭은 `침수년도탭`, `재해명탭`, `침수발생강우탭` 구조에 맞춰 재배치했고, 탭별 표 항목도 캡처 기준에 가깝게 맞췄다.
+
+## 4. 기능별 현재 상태
+
+### 4.1 popup 조회
+
+- FE-only draft 구현 완료
+- 레이어 트리 `침수흔적도` 목록 진입 기준
+- 시도/시군구/년도/재해명 조건과 목록 필터, 페이지네이션, 다운로드를 포함한다.
+
+### 4.2 지도 이동 및 강조
+
+- FE-only draft 구현 완료
+- 더블클릭 시 popup close 후 메인 지도 fit 이동과 mock polygon/침수심 표현 overlay를 수행한다.
+- `침수흔적도` 체크 상태에 따라 영역과 침수심 overlay를 함께 표시/숨김한다.
+
+### 4.3 지도 상세 팝업
+
+- FE-only draft 구현 완료
+- 선택 이력 기준 3탭 플로팅 팝업을 제공한다.
+
+## 5. 현재 검증 메모
+
+- 로컬 `localhost:3002` 응답은 확인했다.
+- `next dev`는 샌드박스 내에서 `spawn EPERM`이 발생해 권한 상승 후 로컬 서버를 띄웠다.
+- 사용자가 직접 로컬 화면을 수동 검증할 예정이므로, popup 실제 진입/더블클릭/상세패널 체감 확인은 후속 결과를 받아 갱신한다.
+
+## 6. 남은 리스크
+
+- popup 라우트의 초기 컴파일 시간이 길어 자동 요청에서 timeout이 발생할 수 있다.
+- `침수흔적도` 기준데이터 이름/구조와 FE 판별식이 다를 수 있다.
+- 실제 API 필드가 확정되면 상세패널 항목명/정렬이 일부 바뀔 수 있다.