frontend/apps/sn/docs/작업내용/SFR-012-002-하수관망도 업로드/001-fe-SFR-012-002-하수관망도 업로드-통합구현기록.md

SFR-012-002 하수관망도 업로드 통합 구현 기록

1. 문서 목적

• SFR-012-002 하수관망도 업로드의 FE 구현 이력, 결정사항, BE 연동 경계, 남은 리스크를 기능당 1개 문서로 누적 관리한다.
• 구현 전 단계에서는 설계 기준과 착수 조건을 먼저 기록한다.
• 이후 라운드부터는 새 파일을 추가하지 않고 이 문서 내부 헤더만 추가한다.

2. 입력 근거

• COMMON_DOCS_ROOT/작업계획/SFR-012-002-하수관망도 업로드/001-de-SFR-012-002-하수관망도 업로드-설계.md
• FE_APP_DOCS_ROOT/작업계획/SFR-012-002-하수관망도 업로드/001-fe-SFR-012-002-하수관망도 업로드-작업카드.md

3. 공통 계약

• GIS 관리는 지도 화면 내부 로컬 편집 모드가 아니라 window popup 업무 흐름으로 구현한다.
• 업로드 대상 GIS는 원본과 분리된 업로드본으로 저장된다는 업무 규칙을 FE 문구와 payload 구조에 모두 반영한다.
• 승인 전에는 코드 구현을 시작하지 않는다.
• FE는 승인 후에도 실제 업로드/다운로드 API 연결 전까지는 mock 이력과 payload 준비 상태까지만 구현한다.

4. 라운드 요약

4.1 2026-05-15 설계 착수

• 작업지시의 요구사항 명세서, 시나리오, HTML, PNG를 읽고 SFR-012-003과 비교했다.
• SFR-012-003이 지도 위 직접 편집 중심이었다면, SFR-012-002는 popup 기반 업로드 관리라는 점을 핵심 차이로 확정했다.
• canonical 문서 구조는 그대로 재사용하되, 이번 기능의 구현 후보를 src/features/windowPopup/** 중심으로 재설계했다.

4.2 2026-05-15 FE-only popup 구현

• gisManagementPopup placeholder를 실제 popup content로 교체했다.
• 구현 범위
  • 시설구분 select
  • 파일 찾기 input
  • 파일 확장자/크기 1차 검증
  • mock 업로드 이력 갱신
  • 다운로드 대상 선택
  • 업로드/다운로드 요청 미리보기
• 구현 원칙
  • 실제 API 호출 없이도 백엔드 계약과 payload 구조를 검토할 수 있어야 한다.
  • 업로드 성공 시 같은 시설구분의 기존 최신 참조 행은 이력 상태로 내리고, 신규 행을 최신 참조로 올리는 mock 규칙을 둔다.
  • 미지원 시설구분은 select에서 비활성 처리해 예외 흐름을 먼저 노출한다.
• 실제 수정 파일
  • FE_APP_ROOT/src/features/windowPopup/ui/GisManagementPopupContent.tsx
  • FE_APP_ROOT/src/features/windowPopup/registry.tsx
  • FE_APP_ROOT/src/features/windowPopup/model/popupDefinitions.ts

4.3 2026-05-18 popup 구조/스타일 재정리

• windowPopup 내부에서 직접 화면을 모두 그리던 방식을 걷어내고, GisManagementPopupContent는 얇은 wrapper로 두고 실제 화면은 GisManagementPopupPage로 분리했다.
• 분석도구 popup과 비슷한 타이포/버튼/테이블 톤으로 재정리했다.
• 팝업 초기 폭과 높이를 조정하고, 내부 컨텐츠는 창 크기에 맞춰 유동적으로 늘어나도록 변경했다.
• 업로드 현황은 10건 단위 페이징을 적용했고, 기본적으로 5행 수준이 편하게 보이도록 높이를 조정했다.
• GIS 관리 window popup을 닫으면 분석도구 메뉴 active가 같이 해제되도록 보완했다.
• 찾기, 업로드 버튼은 상황판/검색영역 조회 버튼 계열 색으로 통일했다.
• 다운로드 버튼은 운영정보 파일 다운로드와 같은 green 계열 버튼으로 분리했다.
• 업로드 row는 좌측 입력 그룹과 우측 버튼 그룹을 분리 정렬하고, 버튼 간격을 별도로 조정했다.

4.4 현재 FE 구현 범위 확정

• 구현 완료 범위
  • GIS 관리 popup 진입
  • 하수관로 단일 시설구분 표시/사용
  • 파일 찾기
  • 확장자/크기 1차 검증
  • mock 업로드 이력 누적
  • 업로드 현황 10건 페이징
  • 다운로드 대상 선택
  • popup close 시 분석도구 active 해제
  • 버튼 색/정렬/간격 정리
• 미완료 범위
  • 실제 업로드 API 호출
  • 실제 다운로드 바이너리 응답
  • 업로드 성공 후 서버 이력 재조회
  • 실제 시설물 레이어 기반 시설구분 동기화

4.5 2026-05-21 업로드 대상 하수관로 단일화

• 운영 제약 기준으로 GIS 관리 업로드 대상은 하수관로만 사용한다.
• 이에 따라 UPLOAD_FACILITY_TYPES mock 상수에서 하수맨홀, 하수처리시설 항목을 제거했다.
• 업로드 현황 mock 목록도 하수관로 이력만 남기고 정리했다.
• FE 문서와 공통 공유 기록에서도 다른 GIS 테이블은 타회사 소유 범위라 업로드 대상에서 제외한다는 근거를 함께 남긴다.
• 현재 구조는 /map 진입 시 전체 레이어 트리를 읽더라도 GIS 관리 popup 소비 단계에서는 하수관로만 노출하는 방식으로 유지한다.

5. BE 공유 초안

5.1 FE가 기대하는 메타 정보

• 업로드 가능 시설구분 목록
• 시설구분별 허용 확장자
• 시설구분별 최대 파일 크기
• 시설구분별 업로드 가능 여부

5.2 FE가 기대하는 업로드 응답 정보

• uploadId
• facilityTypeCode
• facilityTypeName
• fileName
• registeredAt
• registeredBy
• activeYn
• 최신 참조 갱신 여부

5.3 FE가 기대하는 다운로드 조건

• 선택 업로드 ID 기준 다운로드
• 권한 없음 / 파일 없음 / 다운로드 실패 메시지 구분

6. 남은 리스크

• popup UI를 어느 수준까지 기존 공용 폼 패턴으로 맞출지 구현 직전에 다시 확인이 필요하다.
• 업로드 후 지도 레이어를 즉시 새 업로드본 기준으로 refresh할지 여부는 서버 계약 없이는 확정하기 어렵다.
• 실제 upload history 스키마가 설계 초안과 달라질 수 있다.
• 현재 업로드/다운로드는 요청 미리보기와 mock 목록 갱신만 수행하므로, 실제 파일 바이너리 흐름은 백엔드 구현 후 재검증이 필요하다.
• 시설구분 목록은 현재 UPLOAD_FACILITY_TYPES mock 상수에 고정돼 있어 실제 좌측 시설물 레이어와 다를 수 있다.

7. 2026-07-31 가평군 다운로드 안정화

7.1 작업 배경

• 실제 FE-BE 연동이 완료된 GIS 관리 화면에서 가평군 최신 GPKG 다운로드가 간헐적으로 실패했다.
• Chrome 콘솔의 실패 기록은 HTTP 업무 오류가 아닌 TypeError: Failed to fetch였다.
• 같은 요청의 다음 실행은 정상 파일을 반환해 대용량 응답 전송 구간의 일시적 연결 단절로 판단했다.

7.2 구현 내용

• GisManagementPopupPage.tsx에 GIS 다운로드 전용 호출 함수를 추가했다.
• 네트워크 단절로 식별되는 TypeError만 500ms 후 한 번 재시도한다.
• 현재 다운로드와 업로드 이력 선택 다운로드가 같은 안정화 로직을 사용한다.
• HTTP 오류와 서버 업무 오류는 재시도 대상에서 제외한다.
• Blob object URL은 다운로드 클릭 직후가 아닌 1초 뒤 해제한다.

7.3 영향 범위

• 변경 파일: apps/sn/app/(map-layout)/map/components/gisManagement/GisManagementPopupPage.tsx
• 변경 API 계약: 없음
• 백엔드 및 DB 변경: 없음
• 다른 다운로드 화면과 공통 API 유틸리티 영향: 없음

7.4 검증 요약

• 가평군 최신 GPKG 다운로드 성공
• 가평군 업로드 이력 선택 다운로드 성공
• 두 파일 모두 16,670건, EPSG:5179, SQLite 무결성 ok
• fid INTEGER PRIMARY KEY 단일 컬럼과 공간 인덱스 확인
• 최종 브라우저 콘솔 오류 및 경고 없음

8. 2026-08-28 GIS 관리 관리기관 목록 초기화 보완

8.1 추적 근거

• 화면설계서 슬라이드 35 SN_MN010302, 요구사항 SFR-012-002의 GIS 관리 팝업·시설정보 선택·업로드 흐름을 기준으로 확인했다.
• 요구사항정의서 3. (기능)요구사항정의 및 추적표의 SFR-012-002를 대조했다.

8.2 원인

• 팝업 초기화가 시설유형 API와 관리기관 API를 하나의 Promise.all 및 단일 try/catch로 처리했다.
• 어느 한 API라도 일시 실패하면 관리기관 API가 정상이어도 setMngInstOptions가 실행되지 않아 콤보박스에는 선택만 남았다.

8.3 변경 내용

• 시설유형과 관리기관 조회를 독립 비동기 함수로 분리했다.
• 시설유형 조회 실패 시 기본 하수관로 설정을 유지하고, 관리기관 조회 결과는 별도로 정렬·반영한다.
• 관리기관 조회 실패와 정상 빈 결과를 구분한 사용자 안내를 추가했다.
• BE API·DB·업로드/다운로드 계약은 변경하지 않았다.

8.4 GIS 업로드 목록 이동 버튼 문구

• 업로드 이력을 다시 조회하고 목록 화면으로 전환하는 버튼명을 조회에서 목록으로 변경했다.
• 기본 업로드 이력 화면과 오류·미리보기 화면의 동일 액션 문구를 함께 통일했다.
• 버튼 이벤트와 API 요청은 변경하지 않았다.