fix(browser): 조회 timeout만 지역 단위 1회 재시도(재로드), 지역 이름 진단

CHANGELOG.md

@@ -9,6 +9,15 @@ OpinetClient를 native async 하나로 통합했다. 모든 조회·디버그에
 ## [Unreleased]
 
 ### Fixed
+- 지역별 화면 수집에서 한 지역(시군구)의 '조회' 검색 응답이 시간 초과되면 검색 화면을 새로 열고
+  탭·지역을 다시 고른 뒤 그 지역만 한 번 다시 조회한다(첫 시도의 늦은 응답을 쓰지 않는다). 재시도
+  요청은 `max_search_requests` 상한에서 차감하며, 여유가 없으면 재시도하지 않는다. 지역 선택 단계·결과
+  DOM 대기의 시간 초과, 인증 거부·429·차단 화면·파싱 오류는 재시도하지 않는다. 재시도로 성공한 조회는
+  경고 로그와 `OpinetBrowserSnapshot.region_retry_count`로 드러난다.
+- 지역 선택·검색 실패 진단이 한글 지역 이름을 모두 `target=non-numeric`으로 뭉개던 문제를
+  고쳤다. 숫자 코드는 그대로, 이름은 한글 음절·숫자만 남겨 12자로 자른 시도/시군구 경로와
+  `attempt`/`attempts`를 남긴다. 응답 이후 DOM 대기 시간 초과도 원 예외 문자열 없이 같은
+  형식으로 정제한다(재시도는 하지 않는다).
 - HTTP 200의 서비스 이용 불가 HTML을 정상 검색 화면으로 오인하지 않고 조기 실패시킨다.
   브라우저 응답 대기 오류는 단계와 최근 요청 종류로 진단하며 비밀 URL·본문은 기록하지 않는다.
 - 서로 다른 검색지역의 같은 주유소 ID를 전역으로 병합해 유효 가격과 주유소/충전소

docs/browser-collection.md

@@ -55,14 +55,29 @@ HTTP 오류·접근 거부·CAPTCHA 응답은 빈 결과로 바꾸지 않고 실
 현재 문서와 응답이 모두 오피넷 HTTPS의 정확한 `/searRgSelect.do` 경로와 같은 query인지
 확인한 뒤 그 HTML에서 차단 여부를 검사한다. 대기 시간은 collector의 `timeout_ms`를 따른다.
 외부 주소·다른 화면으로의 이동과 일반 네트워크 오류는 복구 대상으로 취급하지 않는다.
-기본 `timeout_ms`는 60초다. 이는 지연된 화면 갱신을 기다리는 상한일 뿐, 추가 요청이나
-차단·CAPTCHA 응답에 대한 자동 재시도를 뜻하지 않는다. 더 짧거나 긴 제한이 필요한 호출자는
+기본 `timeout_ms`는 60초다. 이는 지연된 화면 갱신을 기다리는 상한이며, 차단·CAPTCHA
+응답에 대한 자동 재시도를 뜻하지 않는다. 더 짧거나 긴 제한이 필요한 호출자는
 생성자 인자로 명시할 수 있다.
 
+한 지역(시군구 또는 읍면동)의 '조회' 검색 응답이 시간 초과되면 검색 화면을 새로 열고
+(`page.goto`, 출처·차단 검사 포함) 탭과 지역을 처음부터 다시 고른 뒤 그 지역만 **한 번** 다시
+조회한다. 같은 화면에서 다시 조회하면 첫 시도의 늦은 응답이 두 번째 조회의 결과로 쓰일 수 있기
+때문이다. 그래도 실패하면 전체 수집을 실패시킨다. 재시도 사이에도 화면 조작 간격
+(`action_min_seconds`~`action_max_seconds`)을 지키며, 재시도 요청은
+`max_search_requests` 상한에서 차감된다. 첫 조회분(`지역 수 × 2탭`)을 예약하고 남은
+여유가 없으면 재시도하지 않고 `retry=budget-exhausted`로 실패한다. 지역 선택 단계의 시간 초과
+(같은 화면에서 다시 고르면 이미 선택된 값으로 보고 응답 검증과 하위 목록 대기를 건너뛴다),
+결과 DOM 대기 시간 초과(차단·빈 화면일 수 있다), HTTP 401/403/429, 차단·서비스 불가 화면,
+파싱 오류는 재시도하지 않는다. 재시도로 성공한 조회는 `opinet.experimental.browser` 경고 로그와
+`OpinetBrowserSnapshot.region_retry_count`로 확인한다.
+
 HTTP 200이어도 `The service is not available.` 오류 HTML이면 즉시 실패한다.
-탭 전환·지역 선택·검색의 응답 대기 실패는 `OpinetServerError`에 단계·숫자 지역 코드와
-최근 8개 요청/응답/전송 실패 이벤트를 남긴다. 인증 URL의 query, 헤더, 본문, 원 예외 문자열은
-포함하지 않는다. 이 진단은 추가 요청·자동 재시도 없이 같은 화면 동작만 관찰한다.
+탭 전환·지역 선택·검색의 응답 대기 실패는 `OpinetServerError`에 단계·지역 식별자와
+최근 8개 요청/응답/전송 실패 이벤트를 남긴다. 지역 식별자는 숫자 지역 코드면 그대로,
+오피넷 화면처럼 값이 지역 이름이면 한글 음절·숫자만 남겨 최대 12자로 자른 값을 쓴다
+(예: `phase=search:station:region=경기도/용인시수지구:attempt=2`, 그 밖의 문자열은
+`redacted`). 지역 조회 실패에는 `attempts=1|2`가 붙는다. 인증 URL의 query, 헤더, 본문,
+원 예외 문자열은 포함하지 않는다. 진단 자체는 같은 화면 동작만 관찰하며 요청을 추가하지 않는다.
 HTTP 401/403/429와 취소는 기존 예외 의미를 유지한다. 오류 화면 감지가 과거 모든
 timeout 원인의 해결을 뜻하지는 않으며, 실제 수집 복구는 별도로 확인해야 한다.
 현재 이 안전 진단 범위는 응답 대기 구간이다. 초기 navigation과 응답 이후 DOM/파싱

docs/implementation-status.md

@@ -13,6 +13,10 @@
 차단 화면과 외부 이동, 관련 없는 네트워크 오류는 계속 실패로 처리한다.
 운영 수집에서 일시적으로 지연된 화면 응답을 기다릴 수 있도록 collector의 기본
 `timeout_ms`는 60초로 둔다. 이 변경은 요청 재시도나 접근 제한 우회를 추가하지 않는다.
+2026-10-12부터 지역 조회 한 건의 '조회' 검색 응답이 시간 초과되면 검색 화면을 새로 열고
+탭·지역을 다시 고른 뒤 그 지역만 한 번 다시 조회한다(지역 선택·결과 DOM 대기 시간 초과는 재시도하지
+않는다). 재시도는 화면 조작 간격을 지키고 `max_search_requests` 상한에서 차감되며,
+실패 진단에는 `target=non-numeric` 대신 정제·절단한 지역 식별자와 시도 횟수가 남는다.
 
 공식 open API와 분리된 `opinet.experimental.OpinetBrowserCollector`를 추가했습니다.
 Playwright로 지역별 공개 화면의 시도·시군구·읍면동 선택값을 읽고, 화면 조회 시