Aislo/docs/raw/plans/2026-07-19_plan_half_width_persistence.md

완료 이력 아카이브: 반폭 DB 단일 소스화 및 영속화 (2026-07-19)

본 문서는 docs/raw/PLAN.md에서 완료되어 검증이 끝난 계획 항목들을 이관 보관한 파일입니다.

---

1. 🎯 횡단 반폭 DB 단일 소스화 (2026-07-19 협의, 완료)

배경 및 합의 사항

• 횡단 반폭 값의 단일 소스는 DB로 한다.
• 최초 solve 시(사용자 업로드 직후 DB에 값이 없는 경우): config 기본값으로 계산하고, 사용한 반폭을 DB에 저장한다.
• B06에서 반폭 변경 + [재계산] 시: DB와 영구저장소(섹션 JSON 파일)를 함께 업데이트한다.
• B05로 돌아와 경로를 재계산(solve)하면: DB에 저장된 반폭을 읽어 그 값으로 섹션을 재생성하고 파일·DB를 갱신한다.
• 단계 진입을 막는 개념 대신 자연 전파 구조를 지향한다: 사용자가 결정한 값들이 단계 진행에 따라 DB에 채워지고, 전 단계에서 변경이 생기면 후속 단계 산출물이 자연스럽게 갱신된다.

완료 체크리스트

• 반폭 저장 위치: longitudinal_sections.data JSON에 생성 옵션 스냅샷(options: station_interval_m, cross_half_width_m, cross_sample_interval_m, long_sample_interval_m) 포함 — 테이블 스키마 변경 없음 (run_section_generation의 long_summary에 options 추가)
• B05 solve: 섹션 생성 전 프로젝트 최신 longitudinal_sections.data.options 조회 → 요청 값 → DB 값 → config 순 우선 (B05_wf2_Route_Router._section_options + get_latest_section_options() 신설)
• B06 regenerate: 나머지 3개 측점 옵션도 stage 2 params 대신 저장된 data.options 우선 사용 (fallback: stage params → config)
• B06 프론트: 반폭 필드 초기값을 DB data.options 값 우선으로 표시 — options 스냅샷이 없는 과거 데이터만 샘플 max offset 추정으로 폴백, 측점 간격 라벨도 options 값 우선
• 검증 시나리오: ① 최초 solve → DB options 저장 확인 ② B06 반폭 변경 재계산 → DB·파일 갱신 확인 ③ B05 재solve → 변경한 반폭 유지 확인

추가 구현 (백로그 승격)

• B05 등고선 간격 영속화: PUT /{project_id}/route/contour-interval 신설 — 재적용 성공 시 stage 1 params(단일 소스)의 contour_interval_m 갱신 (update_contour_interval_param() 공용 유틸 신설), 재진입 복원은 기존 surface_params.contour_interval_m 경로 그대로 동작
• 표시 설정류(B04 포인트 크기·밀도·표시 토글, B06 연직 과장) 영속화는 불필요 확정 — 백로그에서 제거
• 구현 정적 검증: tsc --noEmit·py_compile 통과, ruff format·prettier 적용

---

2. 📋 사용자 선택값 영속화 현황 점검 (2026-07-19, 완료)

점검 배경

• B04B06(향후 B07B09 동일 흐름)은 단방향이 아니라 단계를 왔다갔다 하며 데이터를 반복 수정하는 작업흐름이다.
• 원칙: 사용자가 선택한 값은 DB에 저장하고, 값이 없으면 config 기본값으로 계산 후 그 값을 DB에 채운다.
• 아래는 페이지별 저장 현황 전수 점검 결과이다.

B04 (지표면 분석)

항목	현재 저장 여부	위치/비고
지면 필터 선택 (source_filter)	✅ 저장	stage 1 params (확정 시), get_surface_confirmation_params로 후속 단계가 조회
지표면 표현 선택 (method)	✅ 저장	stage 1 params (확정 시)
스무딩 여부 (smooth)	✅ 저장	stage 1 params (B04_wf1_Surface_Router.py:236)
모델 표시 옵션의 등고선 간격 (contour_interval_m)	✅ 저장	stage 1 params (B04_wf1_Surface_Router.py:239, 확정 시점 값)
포인트 표시옵션 (포인트 크기)	❌ 미저장	B04_wf1_Surface_UI_Viewer.ts 뷰어 로컬 상태, 서버 미전송
밀도 (density 슬라이더)	❌ 미저장	B04_wf1_Surface_UI_Viewer.ts:74-83 뷰어 로컬 상태
모델 표시 토글 (축/지표면/등고선 표시 여부)	❌ 미저장	B04_wf1_Surface_UI_TerrainViewer.ts 뷰어 로컬 상태

B05 (경로 설계)

항목	현재 저장 여부	위치/비고
포인트 팔레트 사용 이력 (BP/EP/CP/AP/FP)	✅ 저장	stage 2 params(points) + route_points 테이블 — 사용자 추정대로 필수값이라 기존 저장
임도 기준·옵션 컨테이너 전체 (등급, 포장, 곡선반경, 경사 상·하한, 가중치, 회피 통과)	✅ 저장	stage 2 params(options) — RouteSolveRequest.options(), 재진입 시 폼 복원됨
측점·횡단 옵션 (station/cross_sample/long_sample interval)	✅ 저장	stage 2 params — 단 cross_half_width_m은 현재 항상 null 전송 (반폭 DB 단일 소스화 작업에서 해소)
등고선 간격	✅ 저장	PUT /{project_id}/route/contour-interval로 저장 성공 확인

B06 (종횡단)

항목	현재 저장 여부	위치/비고
횡단 반폭	✅ 저장	longitudinal_sections.data.options로 저장 완료
연직 과장 (vertical_exaggeration)	❌ 미저장	프론트 로컬 즉시 재렌더 전용, 재진입 시 config 기본값 복귀

결론

• 계산에 영향을 주는 입력값은 stage params·전용 테이블 및 options 필드로 완전하게 영속화되었습니다.