# 완료 이력 아카이브: 반폭 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에 채워지고, 전 단계에서 변경이 생기면 후속 단계 산출물이 자연스럽게 갱신된다.

### 완료 체크리스트
- [x] 반폭 저장 위치: `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 추가)
- [x] B05 solve: 섹션 생성 전 프로젝트 최신 `longitudinal_sections.data.options` 조회 → 요청 값 → DB 값 → config 순 우선 (`B05_wf2_Route_Router._section_options` + `get_latest_section_options()` 신설)
- [x] B06 regenerate: 나머지 3개 측점 옵션도 stage 2 params 대신 저장된 `data.options` 우선 사용 (fallback: stage params → config)
- [x] B06 프론트: 반폭 필드 초기값을 DB `data.options` 값 우선으로 표시 — options 스냅샷이 없는 과거 데이터만 샘플 max offset 추정으로 폴백, 측점 간격 라벨도 options 값 우선
- [x] 검증 시나리오: ① 최초 solve → DB options 저장 확인 ② B06 반폭 변경 재계산 → DB·파일 갱신 확인 ③ B05 재solve → 변경한 반폭 유지 확인

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

---

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

### 점검 배경
- B04~B06(향후 B07~B09 동일 흐름)은 단방향이 아니라 단계를 왔다갔다 하며 데이터를 반복 수정하는 작업흐름이다.
- 원칙: 사용자가 선택한 값은 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 필드로 완전하게 영속화되었습니다.