# Lab 승인 GPX → DemoService 반영 ## 운영 배포와 부분 시험 확인 실제 Lab 설치본의 보호 기능을 포함한 송신기는 `tools/lab_sync/sync_lab_gpx.py`에 보존한다. 기존 상태 파일·잠금 파일을 그대로 사용하며 v2는 명시적으로 선택한다. Hugging Face 시작 스크립트는 서비스 시작 전에 서버 안에서 migration·수신·카탈로그의 실제 PostgreSQL DB와 스키마·테이블 식별자가 일치하는지 검사한다. 다르면 migration을 실행하지 않는다. 동일함을 확인한 뒤 migration 0014를 적용하고 기존 행 수 보존을 검사한다. 접속 문자열과 원본 자료는 출력하지 않는다. 같은 수신 인증을 요구하는 `GET /deployment-status`는 배포 GitHub SHA, 실제 migration revision, 세 표의 존재 및 서버의 동일 DB 사전 검사 결과만 반환한다. `GET /routes/{source_id}/storage`는 저장된 세 표를 서버의 읽기 전용 트랜잭션으로 조회하여 실제 두 art ID·내용 해시·활성 상태와 GPX/저장 좌표 일치 여부를 반환한다. 원본 GPX·좌표·도안 본문이나 DB 접속정보는 응답에 포함하지 않는다. `GET /inventory`는 같은 출처의 전체 라이브러리 ID와 실제 art 연결·활성 상태·내용 해시만 반환한다. 전체 동기화는 이를 승인 목록과 대조하여 이미 확인된 자료의 PUT을 생략하고 실제 비활성화 대상을 산출한다. v2 승인 스냅샷의 선택적 `expected_catalog_revision`, `expected_deactivation_ids`를 함께 사용하면 서버는 같은 출처 잠금 아래 개정 번호와 취소 대상이 예상과 일치할 때만 비활성화를 적용한다. 원본 GPX·좌표는 목록 응답에 포함하지 않는다. 실제 한 건 시험은 현재 accepted 자료의 `--probe-id`로 부분 세션을 사용한다. 저장 응답을 확인한 뒤 storage 조회의 실제 ID와 비교한다. 전체 승인 스냅샷을 보내지 않고 반복 실행이나 대량 전송을 자동으로 시작하지 않는다. ## v2: 도안·라이브러리·경로 후보를 함께 저장 `--contract-version 2`는 Lab에서 HTTP API만 사용한다. Lab의 읽기 전용 SQLite 승인 조회와 별도의 로컬 전송 상태 SQLite 외에는 DB에 접속하지 않는다. DemoService PostgreSQL 드라이버·접속 문자열은 Lab에 필요하지 않다. 기존 CLI와 요청은 기본적으로 v1을 유지하며, v2 전환은 명시적으로 수행한다. 서버는 기존 인증·서버 DB 설정으로 다음을 **경로 1건당 한 트랜잭션**에서 저장한다. 1. 원본 DesignSpec digest를 검증하고 `art_templates`를 확인·등록한다. 2. `lab_route_library`에 GPX와 위치 없는 XY 외곽선을 저장한다. 3. GPX에서 직접 파싱한 WGS84 `[위도, 경도]`만 `art_route_candidates.coordinates`에 저장한다. 도안 SVG는 원본 도안 점들로 생성한다. HTTP 요청에 있는 경로·파일명을 서버에서 열지 않는다. v2는 클라이언트가 직접 지정하는 후보 GPS 배열과 SVG 본문을 받지 않는다. 도안 자체의 `design_ai_status`와 경로의 AI·도로 검증을 별도로 저장한다. `ai_reject` 도안도 승인 경로의 원본 참조로 보존할 수 있지만 승인 도안으로 승격하지 않는다. `ai_pass` 도안을 주장하려면 해당 도안 자체의 두 모델 검수 근거도 필요하다. ### v2 요청 필드 기존 GPX·라벨·지역·승인 시각·검수 정책 필드에 다음을 추가한다. | 필드 | 의미 | |---|---| | `contract_version` | `2` | | `session_id`, `generation` | 서버가 발급한 현재 출처 세션·세대 | | `payload_sha256` | 아래 규칙으로 계산한 의미상 내용 해시 | | `template.design_id`, `source_version`, `design_digest` | 원본 도안 식별 | | `template.snapshot` | digest 검증에 사용할 원본 DesignSpec 전체 JSON | | `template.design_ai_status`, `design_ai_evidence` | 원본 도안의 독립 AI 판정 | | `route_ai_evidence` | 경로의 실제 두 모델 검수 근거 | | `road_verification`, `graph_sha256` | 저장된 도로 검사와 그래프 버전 근거 | | `distance_m`, `validator_version` | 원본 도로 길이의 정수 미터와 검증 정책 버전 | | `previous_payload_sha256` | 명시적 갱신의 비교·교환 조건. 기본값 없음 | | `reapprove` | 취소 후 명시적 재승인. 기본값 false | 내용 해시는 키 정렬, UTF-8, `ensure_ascii=False`, `allow_nan=False`, 구분자 `,`·`:`인 JSON의 SHA-256이다. `session_id`, `generation`, `payload_sha256`, `gpx_base64`, `previous_payload_sha256`, `reapprove`는 제외한다. GPX 바이트는 본문 대신 검증된 `sha256` 필드로 해시에 연결된다. 나머지 기본 필드는 생략하지 않고 송신기와 서버 모델의 값이 일치해야 한다. ### 세션과 승인 취소 - `GET /sync-state`: 계약 버전·현재 세대·카탈로그 개정 번호만 반환한다. - `POST /sync-sessions`: `client_request_id`, `expected_generation`, `mode`, 원본 경로 ID → 내용 해시인 `manifest`, `manifest_sha256`으로 시작한다. - `PUT /routes/{source_id}`: 세션 manifest와 내용 해시가 일치하는 자료만 저장한다. - `GET /sync-sessions/{session_id}`: 현재 세션의 저장 상태를 조회한다. - `POST /sync-sessions/{session_id}/complete?generation=...`: 부분 전송을 완료한다. 다른 자료를 비활성화하지 않는다. - 기존 `POST /approval-snapshot`: v2에서는 `session_id`, `generation`, `manifest_sha256`도 받는다. 전체 세션의 모든 art 연결이 확인된 경우에만 라이브러리와 후보 경로를 함께 비활성화한다. 새 세션은 이전 세션을 차단한다. 세션 시작 요청은 로컬 상태에 먼저 저장한 `client_request_id`로 재시도하며, 응답 유실 때문에 세대를 새로 발급하지 않는다. 이미 완료된 동일 스냅샷의 재시도도 같은 결과를 반환한다. 기존의 대량 비활성화 방지 제한을 유지하며, 부분 목록을 전체 목록으로 보내면 안 된다. ### 멱등 저장과 명시적 변경 같은 ID·같은 내용은 `result=unchanged`로 실제 저장 UUID를 돌려주고, 업무 행의 `updated_at`도 갱신하지 않는다. 다른 내용은 기본적으로 409다. `--allow-updates`는 로컬에 보존된 직전 저장 응답의 해시로 비교·교환을 요청한다. 로컬 이력이 없으면 이 옵션만으로 임의의 서버 내용을 덮어쓸 수 없다. 취소된 경로는 `--allow-reapproval`과 이전보다 늦은 원본 승인 시각이 필요하다. v2로 저장된 내용도 달라졌다면 직전 내용 해시 조건을 함께 만족해야 한다. 오래된 세션은 이 옵션들과 관계없이 거절한다. 성공 응답은 커밋 후의 `art_template_id`, `art_route_candidate_id`, `design_ai_status`, `route_validation_status`, `payload_sha256`, `contract_version`을 포함한다. 송신기는 이 응답을 확인한 뒤에만 `http_v2_sent`에 완료 기록을 남긴다. 옛 `sent` 테이블의 기록을 v2 저장 성공으로 간주하지 않는다. 중단된 같은 세션은 확인된 요청부터 이어서 처리한다. 새 세션에서는 기존 자료도 HTTP 멱등 저장으로 다시 확인하므로 반복 실행 간격을 운영 규모에 맞춰 정해야 한다. ### 호환성과 사전 조건 기존 v1 요청·응답 형식을 유지한다. 다만 한 출처가 v2 관리로 전환된 뒤에는 v1의 동일 활성 자료 확인만 허용하고, 새 쓰기·갱신·스냅샷은 409로 차단한다. v1 요청에는 세대·원본 도안 정보가 없으므로 강한 순서 보장이나 art 저장 성공을 대신 주장하지 않는다. v1에서도 취소된 경로를 재전송만으로 재활성화하지 않는다. 운영에서는 세 업무 테이블이 같은 서버 DB에 존재하고 migration 0014가 적용되어야 한다. 요청 중에는 테이블을 생성하지 않는다. 같은 도안 분류의 내부 정수 버전은 서버가 잠금 아래 배정하고, 원본 ID·버전·digest와 별도로 보존한다. 이전 Alembic 이력은 `routes`·`run_sessions` 기초 테이블의 존재를 전제로 한다. 버전 문자열이 32자를 넘으므로 버전 테이블은 128자를 사용하며 기존 짧은 컬럼은 마이그레이션 실행 시 데이터 보존 방식으로 넓힌다. 아래는 향후 검증 환경에서 사용할 형태이며, 실제 승인 자료로 실행한 명령이 아니다. ```bash python tools/sync_lab_gpx.py \ --root /path/to/synthetic-lab \ --url https://example.invalid/api/v1/ai/internal/route-library \ --token-file /path/to/existing-auth-file \ --contract-version 2 --check-only ``` `--check-only`는 인증 파일을 읽거나 HTTP 요청을 보내지 않는다. 실제 시험 전송은 별도 허용 후 `--probe-id` 또는 `--max-routes`로 범위를 제한한다. 이 두 옵션은 부분 세션을 사용하여 승인 취소를 보내지 않는다. `--new-session`은 오래된 미완료 세션 대신 현재 승인 자료로 새 세션을 시작하는 명시적 복구 옵션이다. 동시 송신기는 상태 파일별 잠금으로 차단한다. 이 저장소의 변경은 기존 Lab 실행 파일을 자동으로 교체하지 않는다. 강화 송신기를 교체할 때는 기존 상태 파일·승인 가드·운영 제한을 보존하고, 기존 프로세스와의 동시 실행을 막는 전환 절차를 별도로 확인해야 한다. ## 기존 v1 연동 Lab 전국 수집기의 `accepted JOIN items`에 있는 승인 경로만 동기화한다. Lab의 `inventory.sqlite3`와 router 일반 Worker의 `routes.sqlite3`는 서로 다른 자료다. `tools/sync_lab_gpx.py`는 전자를 읽고, DemoService의 AI 서비스가 원본 GPX와 위치를 제거한 윤곽을 외부 PostgreSQL에 저장한다. 경로 생성은 DB의 활성 윤곽을 기존 파일 도안과 합쳐 사용한다. ## 수신 서버 준비 1. Lab에서 긴 임의 토큰을 생성해 `/home/jovyan/.config/demoservice-sync/token`에 보관하고, 같은 값을 GitHub 저장소의 Actions Secret `ROUTE_LIBRARY_TOKEN`에 등록한다. 배포 워크플로가 이 값을 Hugging Face Space Secret에 동기화한다. 값이 없으면 수신 API는 `503`으로 비활성화된다. 토큰 값은 로그나 채팅에 기록하지 않는다. 2. AI 서비스의 `ROUTE_LIBRARY_DATABASE_URL`을 영구 PostgreSQL 연결 문자열로 설정한다. Hugging Face 시작 스크립트는 미설정 시 기존 `DATABASE_URL`을 사용한다. DB 계정에는 `lab_route_library` 테이블 생성·조회·수정 권한이 필요하다. 로컬 Docker Compose는 `AUTH_DATABASE_URL`을 전달한다. 3. DemoService 코드를 배포하거나 배포 워크플로를 다시 실행한다. Lab 전송은 워크플로가 Secret 반영과 Space 동기화에 성공한 뒤 시작한다. 수신 경로는 Gateway를 통과하는 `/api/v1/ai/internal/route-library/routes/{source_id}` (`PUT`)이다. `Authorization: Bearer `과 JSON 본문에 다음 필드를 보낸다. ```json { "label": "dog", "region_code": "expanded_gunsan", "region_name": "군산 수송", "sha256": "", "accepted_at": "2026-11-08T08:47:31+00:00", "review_status": "ai_pass", "ai_protocol": "national-blind-upright-v5-outline-and-silhouette", "geometry_ok": true, "seoul_ok": true, "collection_finalized": false, "gpx_base64": "<개별 GPX 파일의 Base64>" } ``` ID는 Lab의 64자리 SHA-256 형식 식별자다. 수신 측은 라벨 7개, GPX SHA-256, 파일 크기(최대 128 KiB), 단일 트랙·구간, 좌표와 닫힌 경로를 검증한다. 같은 ID의 재전송은 갱신 처리하며 라벨은 DemoService 내부 코드로 변환한다: `tree → christmas_tree_trunk`, `tshirt → t_shirt`, `pants → long_pants`, `star → symbol_star`. 전체 승인 목록을 동기화한 뒤 `POST /api/v1/ai/internal/route-library/approval-snapshot`으로 `ids`, `count`, `ids_sha256`, `collection_finalized`를 보낸다. `ids_sha256`은 ID를 사전식 정렬해 줄바꿈으로 연결한 UTF-8 문자열의 SHA-256이다. 전송되지 않은 ID가 목록에 있으면 거절한다. 목록에서 제외된 ID는 비활성화하며, 한 번에 기존 활성 데이터의 5% 또는 20개 중 큰 값보다 많이 제외되면 오류로 중단한다. 이 제한은 잘못된 부분 목록의 대량 비활성화를 막는다. ## Lab 전송 전공서버에서 저장소의 `tools/sync_lab_gpx.py`를 실행한다. 파일은 Lab 쪽 `accepted JOIN items`를 읽으며 `ai_pass`, `geometry_ok`, `seoul_ok`를 재검사한다. 토큰은 파일에서 읽고 로그에 출력하지 않는다. ```bash python tools/sync_lab_gpx.py \ --root /home/jovyan/artifacts/national-ai-seven-100-20261106 \ --url https://tkadkghdlf-cd.hf.space/api/v1/ai/internal/route-library \ --token-file /home/jovyan/.config/demoservice-sync/token ``` 위 기본 명령은 승인 목록 전체를 전송한다. 첫 시험에는 위 명령에 `--probe-id `를 추가한다. 이 옵션은 해당 GPX 한 건만 보내며 승인 목록 스냅샷과 비활성화 요청은 보내지 않는다. 수신·윤곽·경로 생성 반영을 확인한 뒤 기본 명령으로 전체 동기화를 시작한다. 이후 같은 명령에 `--interval-seconds 30`을 추가하면 계속 동기화한다. 전송 성공 기록은 `~/.local/share/demoservice-sync/state.sqlite3`에 저장되어 변경된 GPX만 다시 보낸다. 전송 오류는 다음 주기에 재시도한다. Lab 서버가 재시작된 뒤 자동으로 실행하려면 Lab 운영 환경에서 별도 시작 설정이 필요하다. 현재 `completion.json`이 없는 동안 자료는 중간 승인본으로 표시한다. 완전한 승인 목록이 확인된 경우에만 비활성화를 반영한다. 이 도안 추가는 기존 HGB 모델을 재학습하지 않는다. 새 라벨을 추가하려면 모델과 서비스 라벨 정의도 함께 갱신해야 한다.