Spaces:
Running
Running
|
Download docs/LAB_GPX_SYNC.md from tkadkghdlf/CD: direct link, hf CLI and curl.
- Browser
- Download file 14.2 kB
-
https://huggingface.co/spaces/tkadkghdlf/CD/resolve/main/docs/LAB_GPX_SYNC.md
- Command line
-
hf download hf://spaces/tkadkghdlf/CD/docs/LAB_GPX_SYNC.md
-
curl -L -o LAB_GPX_SYNC.md https://huggingface.co/spaces/tkadkghdlf/CD/resolve/main/docs/LAB_GPX_SYNC.md
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์๋ฅผ ์ฌ์ฉํ๋ฉฐ ๊ธฐ์กด ์งง์ ์ปฌ๋ผ์ | |
| ๋ง์ด๊ทธ๋ ์ด์ ์คํ ์ ๋ฐ์ดํฐ ๋ณด์กด ๋ฐฉ์์ผ๋ก ๋ํ๋ค. | |
| ์๋๋ ํฅํ ๊ฒ์ฆ ํ๊ฒฝ์์ ์ฌ์ฉํ ํํ์ด๋ฉฐ, ์ค์ ์น์ธ ์๋ฃ๋ก ์คํํ ๋ช ๋ น์ด ์๋๋ค. | |
| ```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 <ROUTE_LIBRARY_TOKEN>`๊ณผ JSON ๋ณธ๋ฌธ์ ๋ค์ ํ๋๋ฅผ ๋ณด๋ธ๋ค. | |
| ```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`๋ฅผ | |
| ์ฌ๊ฒ์ฌํ๋ค. ํ ํฐ์ ํ์ผ์์ ์ฝ๊ณ ๋ก๊ทธ์ ์ถ๋ ฅํ์ง ์๋๋ค. | |
| ```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 <accepted์ ์๋ GPX ID>`๋ฅผ ์ถ๊ฐํ๋ค. ์ด ์ต์ ์ ํด๋น GPX | |
| ํ ๊ฑด๋ง ๋ณด๋ด๋ฉฐ ์น์ธ ๋ชฉ๋ก ์ค๋ ์ท๊ณผ ๋นํ์ฑํ ์์ฒญ์ ๋ณด๋ด์ง ์๋๋ค. | |
| ์์ ยท์ค๊ณฝยท๊ฒฝ๋ก ์์ฑ ๋ฐ์์ ํ์ธํ ๋ค ๊ธฐ๋ณธ ๋ช ๋ น์ผ๋ก ์ ์ฒด ๋๊ธฐํ๋ฅผ ์์ํ๋ค. | |
| ์ดํ ๊ฐ์ ๋ช ๋ น์ | |
| `--interval-seconds 30`์ ์ถ๊ฐํ๋ฉด ๊ณ์ ๋๊ธฐํํ๋ค. ์ ์ก ์ฑ๊ณต ๊ธฐ๋ก์ | |
| `~/.local/share/demoservice-sync/state.sqlite3`์ ์ ์ฅ๋์ด ๋ณ๊ฒฝ๋ GPX๋ง ๋ค์ | |
| ๋ณด๋ธ๋ค. ์ ์ก ์ค๋ฅ๋ ๋ค์ ์ฃผ๊ธฐ์ ์ฌ์๋ํ๋ค. Lab ์๋ฒ๊ฐ ์ฌ์์๋ ๋ค ์๋์ผ๋ก | |
| ์คํํ๋ ค๋ฉด Lab ์ด์ ํ๊ฒฝ์์ ๋ณ๋ ์์ ์ค์ ์ด ํ์ํ๋ค. | |
| ํ์ฌ `completion.json`์ด ์๋ ๋์ ์๋ฃ๋ ์ค๊ฐ ์น์ธ๋ณธ์ผ๋ก ํ์ํ๋ค. | |
| ์์ ํ ์น์ธ ๋ชฉ๋ก์ด ํ์ธ๋ ๊ฒฝ์ฐ์๋ง ๋นํ์ฑํ๋ฅผ ๋ฐ์ํ๋ค. ์ด ๋์ ์ถ๊ฐ๋ | |
| ๊ธฐ์กด HGB ๋ชจ๋ธ์ ์ฌํ์ตํ์ง ์๋๋ค. ์ ๋ผ๋ฒจ์ ์ถ๊ฐํ๋ ค๋ฉด ๋ชจ๋ธ๊ณผ ์๋น์ค | |
| ๋ผ๋ฒจ ์ ์๋ ํจ๊ป ๊ฐฑ์ ํด์ผ ํ๋ค. | |