File size: 14,169 Bytes
599b124
 
e516bd2
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
b84c523
 
 
 
 
 
 
e516bd2
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
599b124
 
 
 
 
 
 
 
9a65a94
 
 
 
 
599b124
 
 
 
9a65a94
 
599b124
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
# 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 ๋ชจ๋ธ์„ ์žฌํ•™์Šตํ•˜์ง€ ์•Š๋Š”๋‹ค. ์ƒˆ ๋ผ๋ฒจ์„ ์ถ”๊ฐ€ํ•˜๋ ค๋ฉด ๋ชจ๋ธ๊ณผ ์„œ๋น„์Šค
๋ผ๋ฒจ ์ •์˜๋„ ํ•จ๊ป˜ ๊ฐฑ์‹ ํ•ด์•ผ ํ•œ๋‹ค.