# 로컬 검증 경로 카탈로그와 모양 자동 추천 ## HTTP v2 연동 자료의 조회 v2 후보는 `art_route_candidates.active=true`, 경로 검증 `passed`, 연결된 `lab_route_library.active=true`, 양쪽의 동일 내용 해시를 확인한 뒤 읽는다. 도안 자체의 AI 판정은 경로 승인과 별개이며, 경로 통과를 도안 승인 표시로 쓰지 않는다. 기존 출처 미상 후보는 원래 조회 정책을 유지하고 도안 판정은 `unknown`으로 보존한다. v2 행은 `[위도, 경도]`·WGS84를 명시한다. 기존 행의 순서는 기존 환경변수로 해석한다. 위치 없는 라이브러리 외곽선은 이미 XY이므로 GPS 변환기에 넣지 않는다. 라이브러리와 카탈로그에 같은 외곽선이 있을 때는 동일 좌표열을 중복 제거한다. 카탈로그 DB 결과는 요청마다 읽어 다른 프로세스의 취소를 반영한다. 라이브러리 캐시는 공유 `catalog_revision`을 확인하며 DB 장애 시 이전 외부 캐시를 재사용하지 않는다. 자동 추천도 후보 선별 전에 라이브러리 기여분을 갱신한다. 생성·점 탐색 처리 중 카탈로그 개정 번호가 바뀌면 이전 자료로 만든 결과를 반환하지 않고 `409 route_library_changed_retry`를 반환한다. `ART_ROUTE_CATALOG_DATABASE_URL`이 없으면 기존 `ROUTE_LIBRARY_DATABASE_URL`을 사용한다. Lab에는 이 연결 정보를 전달하지 않는다. `ART_ROUTE_CATALOG_JSON`은 계속 파일 우선 설정이며, 파일 스냅샷의 취소 반영은 별도 재생성이 필요하다. 기존 200행 제한과 화면별 라벨 목록은 이 변경에서 확대하지 않는다. ## 기존 조회 설정 경로 생성 화면의 기본값인 **모양 상관없음 · 자동 추천**은 내장 예시와 검증 경로 카탈로그를 같은 주변 보행망에서 비교한다. 도로 투영으로 먼저 후보 도안을 추리고, 거리별 우선 두 모양을 실제 도로망에 연결하고, 통과한 경로가 부족하면 최대 네 모양까지 탐색한다. 최종 기준 윤곽 유사도 0.82 이상만 표시한다. 이 값은 초기 운영 후보 기준이며 사람 평가로 보정되지 않았다. 통과 경로가 모자라도 일반 러닝 경로를 아트 추천에 넣어 개수를 채우지 않는다. DB 원본 GPS는 절대 새 경로로 반환하지 않는다. 경로를 평면 윤곽으로 변환해 위치와 스케일을 제거하고, 사용자가 선택한 지역의 보행 도로에 다시 맞춘다. 원본의 방향은 저장된 GPS를 북쪽이 위로 보았을 때의 방향이며, 별도 정방향 기준점이 있는 것은 아니다. 크게 열린 경로와 유효하지 않은 좌표는 현재 폐곡선 생성에서 제외한다. 기존 HGB는 지원하는 내장 모양에서만 사용하고, 새 모양의 생성·표시에 새 모델 학습은 필요하지 않다. ## DB 읽기 연결 AI 서비스 실행 환경에 `ART_ROUTE_CATALOG_DATABASE_URL`을 설정한다. 기존 두 테이블 (`art_templates`, `art_route_candidates`)의 SELECT만 허용한 DB 계정을 권장한다. 쿼리도 읽기 전용 트랜잭션으로 실행하며 `validation_status='passed'`만 읽는다. 운영 데이터 복제가 준비돼 있다면 운영 계정 대신 로컬 복제본을 지정한다. 기존 마이그레이션이나 테이블은 바꾸지 않는다. 좌표 배열이 `[경도, 위도]`이면 `ART_ROUTE_COORDINATE_ORDER=lonlat`를 설정한다. 기본값은 프로젝트 좌표 배열과 같은 `[위도, 경도]`다. 접속에 실패하거나 설정하지 않으면 내장 도안으로 동작한다. 접속 정보를 프런트엔드 환경변수에 넣지 않는다. 직접 실행하는 AI 서비스에서는 읽기 전용 JSON 내보내기 파일을 `ART_ROUTE_CATALOG_JSON`으로 지정할 수도 있다. JSON은 `[{ "template_key": "...", "name": "...", "validation_status": "passed", "coordinates": [[37.0, 127.0], ...] }]` 형태다. 이 변수가 있으면 DB 대신 파일을 사용한다. Docker Compose를 사용하는 경우 기존 `./router` 마운트를 이용할 수 있다. 내보낸 파일을 로컬 `router` 폴더에 둔 뒤 `ART_ROUTE_CATALOG_JSON=/workspace/router/<파일명>.json`을 지정한다. 실데이터 내보내기 파일은 Git에 커밋하지 않는다.