Tornado3_2026Election/INTEGRATION_NOTES_2026-04-15.md

# 2026-04-15 통합 작업 메모

이 문서는 2026-04-15에 시작한 연동 점검 메모를 2026-04-18 기준으로 현행화한 기록이다.

## 0. 작업 요약

- SBS 선거 API 기준 실연동 범위를 `광역단체장(3)`, `기초단체장(4)`, `교육감(11)`으로 정리했다.
- 선거 종류 변경 시 실제 SBS `선거구` 코드 기준으로 지역 목록과 요청 코드가 맞물리도록 보정했다.
- `기초단체장` 지역 옵션 교체 중 발생하던 `ArgumentNullException (key)` 및 `ObservableCollection during CollectionChanged` 계열 UI 전환 이슈를 방어 로직으로 정리했다.
- `교육감`, `기초단체장` 사전 방송용 데이터 공백은 저장형 사전데이터(JSON)로 보완했다.
- 사전데이터는 `사전데이터` 페이지에서 조회/수정/저장 가능하게 만들었다.
- `사전_역대당선자*` 계열은 표기 정당과 색상 포맷 정당을 분리해 저장할 수 있게 했다.
- 직함 표기는 광역단체장만이 아니라 `광역단체장`, `교육감`, `기초단체장` 전 컷으로 확대했다.
- 컷 카탈로그는 실제 `.tscn` 이름 기준으로 정리했고, 과거 별칭은 호환용 alias로만 유지한다.
- 컷 썸네일은 `Assets/Thumbnail`에 저장하고, 제어 패널과 컷리스트에서 프리뷰를 표시하도록 정리했다.

## 1. 선거 종류별 연동 결과

### `3` 광역단체장

- 선거구 목록: `sungerInfo/region?type=선거구&sungerType=3`
- 개표 요청: `gaepyo/3/sungergus?ids=<선거구 id>`
- 사전 투표율 요청: `tupyo/3/sidos?ids=<시도 id>`
- 결론:
  - 개표 연동 정상
  - 사전 투표율 연동 정상

### `4` 기초단체장

- 선거구 목록: `sungerInfo/region?type=선거구&sungerType=4`
- 개표 요청: `gaepyo/4/sungergus?ids=<선거구 id>`
- 결론:
  - 개표 연동 정상
  - SBS API 사전 투표율은 미지원
  - 사전 방송용 역사 데이터는 저장형 사전데이터에서 제공

### `11` 교육감

- 선거구 목록: `sungerInfo/region?type=선거구&sungerType=11`
- 개표 요청: `gaepyo/11/sungergus?ids=<선거구 id>`
- 결론:
  - 개표 연동 정상
  - SBS API 사전 투표율은 미지원
  - 사전 방송용 역사 데이터는 저장형 사전데이터에서 제공

## 2. SBS API 제한 사항

- `tupyo/4/...` 계열은 현재 `기초단체장`에 대해 `400`을 반환한다.
- `tupyo/11/...` 계열은 현재 `교육감`에 대해 `400`을 반환한다.
- 위 두 경우는 앱 오류가 아니라 API 제공 범위 밖으로 본다.
- 실제 운영에서는 저장형 사전데이터로 공백을 메운다.

## 3. 저장형 사전데이터 운영

- 저장 위치: `Tornado3_2026Election/Assets/Data/pre_election_history.json`
- 2026-04-18 기준 저장 건수:
  - `광역단체장` 17건
  - `교육감` 17건
  - `기초단체장` 262건
- 페이지 기능:
  - 선거 종류/지역 선택
  - 역대 투표율 카드
  - 역대 당선자 카드
  - 엑셀형 편집
  - 저장
- `사전_역대당선자`, `사전_역대당선자_교육감`, `사전_역대당선자_기초단체장`은 `ColorParty`를 저장할 수 있다.

## 4. 지역 선택 / 전환 안정화

- `DistrictName`, `DistrictCode`, `ElectionType`는 내부적으로 null이 아닌 문자열 상태를 유지한다.
- 지역 옵션 교체 중에는 `_isUpdatingDistrictOptions` 플래그로 transient UI 값을 무시한다.
- 사전데이터용 지역 콤보박스도 별도 `_isUpdatingPreElectionHistoryDistrictOptions` 플래그로 같은 문제를 피한다.
- 선택 변경 뒤에는 debounce 후 자동 재조회한다.

## 5. 직함 표기 확대

- 현재 직함 표기는 `광역단체장`, `교육감`, `기초단체장` 전부에 적용한다.
- 적용 대상 변수:
  - `선거구명`
  - `시도명`
  - `RegionName`
  - `ElectionDistrictName`
  - `DistrictName`
- 예:
  - `서울특별시` -> `서울시장`
  - `전라남도` -> `전라남도지사`
  - `부산광역시` -> `부산광역시교육감`
  - `창원시` -> `창원시장`

## 6. 컷 카탈로그 / 실제 씬 파일

- 현재 카탈로그는 실제 존재하는 `.tscn` 파일명 기준으로 정리했다.
- 2026-04-18 기준 canonical 카탈로그:
  - Bottom 15컷
  - Normal 63컷
  - Top 11컷
  - 총 89컷
- 기존에 사용되던 `_L`, `_END`, `_7680` 계열은 현재 카탈로그에서 제거했다.
- 다만 저장된 큐/상태 복원을 위해 legacy format alias는 유지한다.
- 전수 감사 기준 실제 씬 누락은 `0건`이다.

## 7. 썸네일

- 저장 위치: `Assets/Thumbnail/<template.Id>.png`
- 제어 패널의 컷 선택 콤보박스에서 프리뷰 표시
- `컷리스트` 페이지에서 전체 현황 확인
- `썸네일 생성` 기능은 Karisma에 씬을 로드해 320x180 PNG로 저장

## 8. 변수 매핑 관련 기록

- Karisma 장면 변수 지원 범위 로깅을 유지한다.
- 다음 alias 매핑을 보강했다.
  - `기준시`, `기준시01`, `기준시02`
  - `유권자수`, `유권자수01`
  - `투표자수`, `투표자수01`
  - `득표수바NN`
  - `정당원NN`
  - `정당색NN`
- 역사 당선자 컷은 저장형 사전데이터의 `ColorParty`와 정당 별칭 정규화를 함께 사용한다.

## 9. 주요 변경 파일

- `Tornado3_2026Election/Services/SbsElectionApiClient.cs`
- `Tornado3_2026Election/ViewModels/DataViewModel.cs`
- `Tornado3_2026Election/ViewModels/MainViewModel.cs`
- `Tornado3_2026Election/ViewModels/ChannelScheduleViewModel.cs`
- `Tornado3_2026Election/Services/PreElectionHistoryService.cs`
- `Tornado3_2026Election/Services/CutThumbnailAssetCatalog.cs`
- `Tornado3_2026Election/Services/KarismaThumbnailGeneratorService.cs`
- `Tornado3_2026Election/Services/FormatCatalogService.cs`
- `Tornado3_2026Election/Services/KarismaTornado3Adapter.cs`

## 10. 현재 체크 결과

- `dotnet build .\\Tornado3_2026Election\\Tornado3_2026Election.csproj` 통과
- 기존 경고는 유지
  - `WindowsBase` 참조 충돌
  - MSIX 인증서 경고
  - `MockTornado3Adapter.ConnectionChanged` 미사용 경고
- 컷 카탈로그 감사 결과 실제 씬 누락 `0건`