# 러닝 환경 점수 추천 결과와 AI 샘플은 점수가 높은 순으로 정렬한다. 원래 순서는 추천 점수 동률에, 지도 중심까지의 거리는 샘플 점수 동률에 사용한다. 점수와 추천 순위는 경로 ID를 바꾸지 않는다. - 보행로 구조 25%, 지역 인구 혼잡도 45%, 앱 활동 30%. 경로를 거리 기준으로 샘플링한다. - 비어 있는 신호는 중립값이며 한산하다는 증거가 아니다. 전부 비어 있으면 `자료 부족`. - 활동 집계가 정상 응답했을 때의 0명은 서비스 이용자 활동에만 반영하며 일반 보행 인구에는 반영하지 않는다. - 실시간 인구는 공식 POI 영역과 교차하는 부분만 사용한다. 서울시 API가 20분 넘게 오래됐거나, 대체값이거나, 실패하면 반영하지 않는다. 시간대별 자료가 있는 구간은 별도로 추정한다. - 앱 활동은 최근 2분 이내에 저장되고 GPS 경로가 있는 진행 중 실제 러닝만 포함한다. 시뮬레이션, 일시정지, 종료는 제외한다. 주변 구역에 소수 인원이 있으면 존재 여부만 표시하고, 인원수는 구역당 3명 이상인 집계만 합산한다. 브라우저에는 위치나 구역 목록을 반환하지 않는다. - 이 점수는 추천 순위용이며 통행 가능 여부나 안전을 인증하지 않는다. ## Hugging Face 배포 GitHub의 `DemoService` 브랜치 푸시는 Space 동기화를 시작한다. Docker 빌드는 Geofabrik의 대한민국 OSM에서 도로 인덱스를 만든다. 기본값은 `/app/running-environment`이며 `RUN_ENV_DATA_DIR`로 다른 인덱스를 지정할 수 있다. 혼잡도 프로필은 암호화된 묶음으로만 배포하며 GitHub Secrets의 `RUN_ENV_PROFILE_KEY`, `RUN_ENV_SEOUL_API_KEY`는 Space Secret으로 전달된다. 내부 활동 집계 키는 컨테이너 시작 시 생성하며 인증 서버와 Next가 공유한다. 인덱스나 키가 없으면 해당 신호만 자료 부족으로 처리한다. ## 가져오기 1. [대한민국 OSM PBF](https://tiles.osm.kr/download/)를 다운로드한다. 2. [국토정보플랫폼](https://map.ngii.go.kr/)에서 수치지형도 도엽을 받아 필요한 레이어를 SHP 또는 WGS84 GeoJSON으로 준비한다. `sidewalk-1000`, `sidewalk-5000`, `road-width`, `carriageway`에 각각 대응한다. 아래 필드명은 예시다. 도엽의 조사연도와 이용조건을 확인한 후 넣고, 같은 지역의 구버전과 신버전은 중복 투입하지 않는다. 3. [서울 실시간 도시데이터](https://data.seoul.go.kr/dataList/OA-21285/A/1/datasetView.do)의 주요 121장소 영역 ZIP을 풀고 SHP의 `AREA_CD` 필드를 사용한다. ```powershell python -m pip install osmium geopandas python tools/import_running_environment.py --out D:/data/run-env-v1 --osm D:/data/south-korea.osm.pbf --roads sidewalk-1000 D:/data/sidewalk.shp WIDTH SURFACE --seoul-areas D:/data/seoul-areas.shp AREA_CD ``` `--roads`는 여러 번 지정할 수 있고 `--seoul-areas`도 선택 사항이다. OSM만 먼저 가져올 수 있다. 차도나 도로 전체의 폭을 보도 폭으로 읽지 않는다. 새 버전을 빈 폴더에 생성한 뒤 경로를 바꿔 Next 서버를 재시작한다. ## 로컬 실행 Next 프로세스에 다음 변수를 설정한 후 `main`에서 `npm run dev`를 실행한다. - `RUN_ENV_DATA_DIR`: 생성된 인덱스의 절대 경로. - `RUN_ENV_SEOUL_API_KEY`: 발급받은 서버용 서울시 API 키. `sample`은 광화문·덕수궁 한 곳만 검증 가능. - `RUN_ENV_INTERNAL_KEY`: Next와 로컬 auth-service에 같은 임의의 긴 비밀값을 설정한다. Docker Compose로 auth-service를 띄우는 경우 Compose 실행 환경에도 같은 값을 제공한다. - `NEXT_INTERNAL_API_PROXY_TARGET`: 로컬 API Gateway 주소 (기본 `http://localhost:8000`). 비밀값과 원본 인덱스는 저장소에 커밋하지 않는다. 서울시 API는 공식 예제와 같은 HTTP 포트 8088을 사용한다. 키는 서버에서만 사용하며, 이 외부 연결에는 TLS가 적용되지 않는다. 전국 OSM을 쓴다는 것은 전국에 동일한 폭/보도 데이터가 있다는 뜻이 아니다. OpenStreetMap © OpenStreetMap contributors (ODbL). ## 지역별 과거 혼잡도 실시간 값이 없는 경로 지점은 한국 시간 기준 평일/주말 시간대 패턴을 사용한다. 각 장소의 자체 일평균 대비 비율이며, 다른 도시와 인구수를 직접 비교하지 않는다. 실시간과 과거 값을 같은 지점에 중복 반영하지 않고, 과거 자료의 반영 강도는 실시간의 65%다. - [서울 250m 격자 생활인구](https://data.seoul.go.kr/dataList/OA-22784/S/1/datasetView.do): 내국인 추정치, 시간별. [공식 격자 SHP](https://data.seoul.go.kr/dataVisual/seoul/seoulLivingPopulation.do)와 결합한다. - [인천 부평구 주요지역 유동인구](https://www.data.go.kr/data/15167608/fileData.do): 4시간 단위. [인천관광협의회 시장·문화의거리 좌표](https://www.incheontour.or.kr/place-bupyeong_market) 주변 150m만 근사 적용한다. 이는 조사 경계가 아니다. 공간 범위를 확인하지 못한 축제지역과 부평4동은 제외한다. ```powershell python tools/import_regional_crowd.py --seoul 서울생활인구.zip 격자.shp --bupyeong 부평구.csv --out D:/data/run-env-v1/regional-crowd.json ``` 인덱스 생성 후 Next 서버를 다시 시작한다. 부산 API는 키와 원본 응답 확인, 경기 데이터는 원본 및 경계·이용 조건 확인, 제주 실시간은 공식 연동 경로 확인 후 추가한다. ### 보행자 센서 및 경기 격자 - [서울 열린데이터광장 S-DoT](https://data.seoul.go.kr/dataList/OA-22832/S/1/datasetView.do)의 카메라 식별 범위 4001~4050만 사용한다. [분류 근거](https://kpaj.or.kr/_PR/view/?aidx=34568&bidx=3103). 45m는 추천 적용 반경이며 관측 시야가 아니다. 실시간 장소 관측이 없을 때 센서의 과거 시간대 패턴을 기존 광역 추정보다 우선한다. 최신 관측일이 90일을 넘으면 반영하지 않는다. - `--gyeonggi-verified-grid HOURLY_CSV GRID_FILE`로 경기도 50m 격자 자료를 추가할 수 있다. CSV는 `grid_id,date,hour,count` (날짜 YYYY-MM-DD), 경계 파일은 같은 `grid_id`를 가진 좌표계가 명시된 격자여야 한다. 무료 서비스 이용이 확인된 시간별 원본만 사용한다. 8월 행정동 유입 ZIP과 평일/주말 주간 평균만 있는 데이터는 이 입력으로 쓰지 않는다. ```powershell python -m pip install openpyxl python tools/import_regional_crowd.py --sdot 위치.xlsx 첫주.csv 둘째주.csv --out D:/data/run-env-v1/pedestrian-crowd.json python tools/import_regional_crowd.py --gyeonggi-verified-grid 시간별.csv 격자.shp --out D:/data/run-env-v1/gyeonggi-crowd.json ```