CD / docs /LAB_GPX_SYNC.md
tkadkghdlf's picture
Sync DemoService d71528e975556bf10477c2e7a4be03651ec823a1
b84c523 verified
|
Raw History Blame Contribute Delete
14.2 kB

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์ž๋ฅผ ์‚ฌ์šฉํ•˜๋ฉฐ ๊ธฐ์กด ์งง์€ ์ปฌ๋Ÿผ์€ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์‹คํ–‰ ์‹œ ๋ฐ์ดํ„ฐ ๋ณด์กด ๋ฐฉ์‹์œผ๋กœ ๋„“ํžŒ๋‹ค.

์•„๋ž˜๋Š” ํ–ฅํ›„ ๊ฒ€์ฆ ํ™˜๊ฒฝ์—์„œ ์‚ฌ์šฉํ•  ํ˜•ํƒœ์ด๋ฉฐ, ์‹ค์ œ ์Šน์ธ ์ž๋ฃŒ๋กœ ์‹คํ–‰ํ•œ ๋ช…๋ น์ด ์•„๋‹ˆ๋‹ค.

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 <ROUTE_LIBRARY_TOKEN>๊ณผ JSON ๋ณธ๋ฌธ์— ๋‹ค์Œ ํ•„๋“œ๋ฅผ ๋ณด๋‚ธ๋‹ค.

{
  "label": "dog", "region_code": "expanded_gunsan", "region_name": "๊ตฐ์‚ฐ ์ˆ˜์†ก",
  "sha256": "<GPX ํŒŒ์ผ SHA-256>", "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๋ฅผ ์žฌ๊ฒ€์‚ฌํ•œ๋‹ค. ํ† ํฐ์€ ํŒŒ์ผ์—์„œ ์ฝ๊ณ  ๋กœ๊ทธ์— ์ถœ๋ ฅํ•˜์ง€ ์•Š๋Š”๋‹ค.

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 <accepted์— ์žˆ๋Š” GPX ID>๋ฅผ ์ถ”๊ฐ€ํ•œ๋‹ค. ์ด ์˜ต์…˜์€ ํ•ด๋‹น GPX ํ•œ ๊ฑด๋งŒ ๋ณด๋‚ด๋ฉฐ ์Šน์ธ ๋ชฉ๋ก ์Šค๋ƒ…์ƒท๊ณผ ๋น„ํ™œ์„ฑํ™” ์š”์ฒญ์€ ๋ณด๋‚ด์ง€ ์•Š๋Š”๋‹ค. ์ˆ˜์‹ ยท์œค๊ณฝยท๊ฒฝ๋กœ ์ƒ์„ฑ ๋ฐ˜์˜์„ ํ™•์ธํ•œ ๋’ค ๊ธฐ๋ณธ ๋ช…๋ น์œผ๋กœ ์ „์ฒด ๋™๊ธฐํ™”๋ฅผ ์‹œ์ž‘ํ•œ๋‹ค. ์ดํ›„ ๊ฐ™์€ ๋ช…๋ น์— --interval-seconds 30์„ ์ถ”๊ฐ€ํ•˜๋ฉด ๊ณ„์† ๋™๊ธฐํ™”ํ•œ๋‹ค. ์ „์†ก ์„ฑ๊ณต ๊ธฐ๋ก์€ ~/.local/share/demoservice-sync/state.sqlite3์— ์ €์žฅ๋˜์–ด ๋ณ€๊ฒฝ๋œ GPX๋งŒ ๋‹ค์‹œ ๋ณด๋‚ธ๋‹ค. ์ „์†ก ์˜ค๋ฅ˜๋Š” ๋‹ค์Œ ์ฃผ๊ธฐ์— ์žฌ์‹œ๋„ํ•œ๋‹ค. Lab ์„œ๋ฒ„๊ฐ€ ์žฌ์‹œ์ž‘๋œ ๋’ค ์ž๋™์œผ๋กœ ์‹คํ–‰ํ•˜๋ ค๋ฉด Lab ์šด์˜ ํ™˜๊ฒฝ์—์„œ ๋ณ„๋„ ์‹œ์ž‘ ์„ค์ •์ด ํ•„์š”ํ•˜๋‹ค.

ํ˜„์žฌ completion.json์ด ์—†๋Š” ๋™์•ˆ ์ž๋ฃŒ๋Š” ์ค‘๊ฐ„ ์Šน์ธ๋ณธ์œผ๋กœ ํ‘œ์‹œํ•œ๋‹ค. ์™„์ „ํ•œ ์Šน์ธ ๋ชฉ๋ก์ด ํ™•์ธ๋œ ๊ฒฝ์šฐ์—๋งŒ ๋น„ํ™œ์„ฑํ™”๋ฅผ ๋ฐ˜์˜ํ•œ๋‹ค. ์ด ๋„์•ˆ ์ถ”๊ฐ€๋Š” ๊ธฐ์กด HGB ๋ชจ๋ธ์„ ์žฌํ•™์Šตํ•˜์ง€ ์•Š๋Š”๋‹ค. ์ƒˆ ๋ผ๋ฒจ์„ ์ถ”๊ฐ€ํ•˜๋ ค๋ฉด ๋ชจ๋ธ๊ณผ ์„œ๋น„์Šค ๋ผ๋ฒจ ์ •์˜๋„ ํ•จ๊ป˜ ๊ฐฑ์‹ ํ•ด์•ผ ํ•œ๋‹ค.