# PLAN Archives: B05 종단 계획선(계획고) 자동 생성

- **완료 일시**: 2026-07-20
- **이관 문서**: `docs/raw/plans/2026-07-20_plan_B05_longitudinal_grade_line.md`

---

## 1. 목표
B05 하단 종단면도에 **현황 지반선(기존)** 위에 **계획선(공사 예정 노면고)** 을 추가한다.
계획선은 `직선(일정 종단기울기) + 원곡선(종단곡선)` 만으로 구성되며, 절토량과 성토량이 균형을 이루도록(∫(계획고−지반고)ds ≈ 0) 자동 산출한다.
실행 시점은 **[최적 경로 계산] 버튼 처리 파이프라인의 마지막 단계** (종횡단 생성 직후).

## 2. 설계 기준값 — 법정 근거 및 Config 설계
출처: 「임도설치 및 관리 등에 관한 규정」 [별표 1-2] 임도의 설계 및 시설기준(제9조의19 관련).
기준은 임도등급이 아니라 `설계속도 × 지형구분(일반/특수)` 으로 규정되어 있다.

### 2-1. 종단기울기 (순기울기 상한)
| 설계속도 (km/h) | 일반지형 | 특수지형 | 역기울기 |
|---|---|---|---|
| 40 | 7% 이하 | 10% 이하 | 5% 이하 |
| 30 | 8% 이하 | 12% 이하 | 5% 이하 |
| 20 | 9% 이하 | 14% 이하 | 5% 이하 |
- 예외: 특수지형에서 기준 적용이 어려운 경우 **노면포장 시에 한하여 18% 범위 내 조정 가능**.
- 합성기울기 12% 이하 (부득이 시 간선임도 13%, 지선임도 15%).

### 2-2. 종단곡선
| 설계속도 (km/h) | 최소 반경 (m) | 최소 곡선길이 (m) |
|---|---|---|
| 40 | 450 이상 | 40 이상 |
| 30 | 250 이상 | 30 이상 |
| 20 | 100 이상 | 20 이상 |
- 예외: **비포장 도로이면서 종단기울기 대수차(A)가 5% 이하이면 종단곡선을 넣지 않는다** → 알고리즘 3단계에 조건 분기로 반영.

## 3. 구현 체크리스트 (완료)
- [x] `config_system.py` 에 `FOREST_ROAD_PROFILE_CRITERIA` 법정 기준 사전 추가 (경로찾기 값과 분리 확인)
- [x] `B05_wf2_Route_Engine_Grade.py` 계획선 엔진 신규 작성 (구역분할·PVI최적화·종단곡선·균형보정)
- [x] 종단곡선 법정 예외(비포장 & 대수차 5% 이하) 분기 구현
- [x] `run_section_generation()` 연동 및 `longitudinal.json` `design_profiles` 배열 스키마 확장
- [x] Schema / Router 옵션 6종 및 응답 필드 확장 (요청→DB→Config 3단 폴백)
- [x] `longitudinal_sections` DB 저장 확장 (`get_latest_grade_options` 헬퍼 신설)
- [x] 좌측 패널 계획선 옵션 폼 + 등급→설계속도 연동 기본값
- [x] 종단면도 SVG 계획선·절성토 음영·균형 지표 렌더링
- [x] 새로고침 복원(`GET /route/latest`) 시 계획선 재표시 확인
- [x] `ruff format` / `prettier` 실행

## 4. 구현 중 발생 편차 및 수정사항
1. **엔진 파일 분할**: `B05_wf2_Route_Engine_Grade.py` (560줄) 및 `B05_wf2_Route_Engine_Grade_Solver.py` (352줄)로 분할.
2. **역기울기 오적용 및 V/Λ자 지형 대응**: `_detect_main_direction()`을 통해 계곡 횡단/능선 통과 노선의 방향 오판 방지.
3. **스티키 기본값 버그 방지**: DB에 오버라이드값(`grade_overrides`)과 해석결과(`grade_options`)를 분리.
4. **경사 단위(%) 통일**: UI/Schema/DB 모두 `%` 단위로 일관화 및 레거시 비율 자동 환산.