지반침하 좌표 실패 이슈 및 잔여 케이스 문서 반영

2026-07-02 15:38:45 +09:00
parent 516d93d6fa
commit f4eae0d33e
3 changed files with 59 additions and 1 deletions
@@ -244,3 +244,19 @@
 - FE/BE 코드 반영 완료
 - 로그인 가능한 FE/BE 실행 환경 준비
 - 관리자/일반 사용자 테스트 계정 준비
+
+### 2.24 2026-07-02 잔여 159건 좌표 실패 원인 분류 결과
+
+- 원천 좌표 null 사고 `159건`을 기준으로 실제 JIS와 기존 주소기반 geocoder를 다시 대조했다.
+- JIS 확인 결과
+  - 최신 성공 예시 `20260040`은 `selectInfo.do` 성공 응답과 `mapMainAdmin.do`의 `poly_lonlat=POINT(...)`를 확인했다.
+  - 대표 구 사고번호 `20200232`, `20200018`, `20200093`, `20200068`, `20200063`는 `selectInfo.do` 응답이 `{"result":"fail","reason":null}`였다.
+- 따라서 JIS 브라우저 콘솔의 `mapNew.js ... clone` 오류는 잔여 159건 실패의 공통 원인이 아니라, 성공 케이스에서도 발생 가능한 별도 프론트 스크립트 오류로 분리했다.
+- 주소 기반 geocoder 재측정 결과
+  - 총 159건 중 `49건 성공`, `110건 실패`
+  - 실패 110건은 설명형/비정형 주소 비중이 높고, `위경도 값이 없는 반환값 수신`도 20건 있었다.
+- `정제주소안`으로 110건을 재시도했지만 `추가 성공 0건`이었다.
+- 현 시점 판정
+  - JIS 우선 구현은 최신 사고번호 대응에는 유효하다.
+  - 구 사고번호 공백을 줄이려면 주소 fallback을 함께 유지해야 한다.
+  - 남는 110건은 단순 주소 정제로 해결되지 않아 별도 데이터 보강 또는 수기 좌표 보정 대상으로 분류한다.
@@ -191,3 +191,18 @@
 - 목록 팝업을 기존 popup 창으로 열지, `/map` 내부 모달로 열지
 - 최근 동기화 일시 위치와 노출 범위
 - 좌표 캐시를 메모리 캐시로만 둘지 DB 영속화까지 포함할지
+
+## 11-2. 2026-07-02 유지보수 분석: 사고번호 기반 좌표 원천화 전환
+
+- 현재 FE는 이미 `지반침하정보` 레이어 on/off, 별도 윈도우 팝업 기반 목록, 우측 상세 패널, 반경 적용, 우측 상세 패널 공통 탭까지 구현돼 있다.
+- 따라서 기존 작업카드의 `실구현 없음` 전제는 현행 코드와 맞지 않으며, 이번 유지보수의 FE 역할은 신규 화면 설계보다 “현행 BE 계약 변경 시 FE 회귀 범위를 좁게 유지하는 것”에 가깝다.
+- 현행 FE가 소비하는 핵심 계약은 아래와 같다.
+  - 목록/상세 응답의 `coordStatus`, `geocodeStatus`, `latitude`, `longitude`, `x`, `y`
+  - 반경 조회 응답의 `items[]`
+  - 동기화 완료 후 `SINKHOLE_SYNC_COMPLETED_MESSAGE` payload
+- 이번 사용자 요구처럼 좌표 원천을 주소 geocoding에서 사고번호 기반 JIS 조회 + 원천 DB update로 바꾸더라도, BE가 위 응답 필드를 그대로 유지하면 FE 코드는 1차 구현에서 변경하지 않아도 된다.
+- FE 후속 변경이 필요한 경우는 아래로 한정한다.
+  - `coordStatus` 상태값이 추가되거나 의미가 바뀌는 경우
+  - 관리자용 동기화 버튼/최근 동기화 요약이 “JIS backfill 결과” 중심 문구로 재정의되는 경우
+  - 상세 실패 메시지를 주소 geocoding 실패가 아니라 사고번호 기반 조회 실패 문구로 바꾸는 경우
+- 결론적으로 이번 라운드의 FE 기본 입장은 `계약 유지 시 무코드 대응`, `표시 문구/운영성만 후속 점검`이다.
@@ -396,4 +396,31 @@
 - 이로써 현재 `sn`에서 공통코드 확장 영향은 지반침하 상세 패널 내부에만 한정되고, 기존 다른 화면의 공통코드/하드코딩 코드표 흐름은 건드리지 않는다.
 - 표 컬럼 폭도 함께 조정해 `관로 ID`는 소폭 줄이고 `용도`는 한 줄로 보이도록 미세 보정했다.
 - 변경 파일은 `FE_APP_ROOT/app/(map-layout)/map/components/sinkhole/SinkholeDetailPanel.tsx`, `FE_APP_ROOT/app/components/lib/common/apiHelpers.ts` 2개이며, 공통 헬퍼는 원래 계약으로 복구했다.
- BE API, DTO, DB 변경은 없다.
+- BE API, DTO, DB 변경은 없다.
+
+### 4.47 2026-07-02 사고번호 기반 좌표 원천화 설계 분석
+
+- 사용자 요구사항은 현재 주소 기반 실시간 좌표보정 대신, 사고번호 기반 외부 조회 결과를 원천 `ocrn_txcrd`, `ocrn_tycrd`에 영속화하는 구조로 바꾸자는 것이다.
+- 현재 FE 구현은 목록/상세/반경 조회 모두 백엔드가 내려주는 `coordStatus`, `latitude`, `longitude`, `x`, `y` 계약만 소비하므로, 좌표 원천 전략이 바뀌어도 같은 DTO를 유지하면 FE 코드는 1차 변경이 필요하지 않다.
+- 이번 분석에서 확인한 현행 FE 포인트는 아래와 같다.
+  - 목록은 별도 윈도우 팝업 `SinkholePopupPage.tsx`에서 `/api/v1/sinkholes`를 호출한다.
+  - 지도 레이어도 `page.tsx`에서 같은 목록 API 응답을 GeoJSON feature로 재조립해 사용한다.
+  - 상세/반경 조회는 상세 API와 `nearbyPipesByPoint` 우선 fallback 구조를 사용한다.
+- 따라서 이번 설계 변경의 FE 리스크는 “새 좌표 취득 방식” 그 자체보다 “BE가 응답 필드와 상태값을 바꾸는지 여부”에 집중된다.
+- FE 후속 구현은 다음 조건이 생길 때만 고려한다.
+  - `coordStatus` 값 정의 변경
+  - 관리자 동기화 결과 문구/요약 구조 변경
+  - 좌표 실패 안내문을 JIS 사고번호 조회 기준으로 재정비해야 하는 경우
+
+### 4.48 2026-07-02 사고번호 기반 좌표 원천화 구현 라운드 FE 영향 재확인
+
+- 이번 구현 라운드에서는 FE 코드 수정 없이 대응했다.
+- 백엔드가 기존 계약인 `coordStatus`, `latitude`, `longitude`, `x`, `y`를 유지하도록 구현했기 때문에, 현행 `SinkholePopupPage`, `SinkholeDetailPanel`, `page.tsx`는 그대로 동작해야 한다는 판단을 유지한다.
+- 따라서 이번 라운드의 FE 검증 포인트는 “화면 코드 변경”이 아니라 “기존 화면이 새 백엔드 응답 경로에서도 회귀 없이 동작하는지”에 집중한다.
+
+### 4.49 2026-07-02 잔여 실패 건에 대한 FE 관점 이슈 메모
+
+- 사용자 확인 기준 JIS 성공 케이스 `20260040`은 상세 페이지 HTML에 `poly_lonlat=POINT(...)`가 존재하는데도, 홈페이지 `위치 확인` 버튼 클릭 시 `mapNew.js:524 ... clone` 오류가 발생할 수 있었다.
+- 이 오류는 JIS 프론트 지도 이동 스크립트 문제로 보이며, 우리 FE가 받는 백엔드 DTO 실패와는 직접 원인이 다르다.
+- 실제 잔여 실패 159건은 대부분 JIS 구 사고번호 응답 자체가 `fail`이거나 주소 fallback도 실패하는 케이스로 확인됐기 때문에, 현재 FE 수정 포인트는 없다.
+- FE 후속 액션은 백엔드가 `JIS 우선 + 주소 fallback`을 최종 운영안으로 채택할 때도 기존 `coordStatus`, `geocodeErrorMessage` 표시만 회귀 없이 유지되는지 확인하는 정도다.