Tornado3_2026Election/INTEGRATION_NOTES_2026-04-15.md

2026-04-15 통합 작업 메모

0. 작업 요약

• SBS 선거 API를 기준으로 광역단체장(3), 기초단체장(4), 교육감(11) 실연동을 정리했다.
• 선거 종류 변경 시 실제 SBS 선거구 코드 기준으로 지역 목록과 요청 코드가 맞물리도록 보정했다.
• 기초단체장 지역 옵션 교체 중 발생하던 ArgumentNullException (key)를 ViewModel 방어 로직으로 수정했다.
• 콤보박스 변경 후 값이 그대로 남아 있던 문제를 선택 변경 즉시 재조회 흐름으로 바꿨다.
• System.Text.Json.JsonException은 region API 응답이 최상위 배열([...])인 경우를 허용하도록 수정했다.
• 미지원 조합에서는 이전 값이 계속 보이지 않도록 상태 문구와 보드 표시 규칙을 보정했다.

1. 선거종류(Sunger Types)별 점검 결과

3 시도지사 / 광역단체장

• 선거구 목록: sungerInfo/region?type=선거구&sungerType=3
• 개표 요청: gaepyo/3/sungergus?ids=<선거구 id>
• 사전 투표율 요청: tupyo/3/sidos?ids=<시도 id>
• 부산 기준 확인:
  • 개표 코드: 3260000
  • 사전 코드: 26
• 결론:
  • 개표 연동 정상
  • 사전 투표율 연동 정상

4 시군구장 / 기초단체장

• 선거구 목록: sungerInfo/region?type=선거구&sungerType=4
• 개표 요청: gaepyo/4/sungergus?ids=<선거구 id>
• 부산 해운대구 기준 확인:
  • 개표 코드: 4260900
• 결론:
  • 개표 연동 정상
  • 사전 투표율은 SBS API가 400 반환으로 미지원

11 교육감

• 선거구 목록: sungerInfo/region?type=선거구&sungerType=11
• 개표 요청: gaepyo/11/sungergus?ids=<선거구 id>
• 부산 기준 확인:
  • 개표 코드: 11260000
• 결론:
  • 개표 연동 정상
  • 사전 투표율은 SBS API가 400 반환으로 미지원

2. SBS 선거 API 실연동

• 기준 문서: https://documenter.getpostman.com/view/39408930/2sBXqCNNyS
• 기준 호스트: http://202.31.153.141:8421/
• API 응답 헤더에 charset이 없어서, 본문은 UTF-8 바이트 기준으로 직접 디코딩한다.

현재 지원 범위

• 광역단체장
  • 사전 투표율: 지원
  • 개표: 지원
• 교육감
  • 사전 투표율: 미지원
  • 개표: 지원
• 기초단체장
  • 사전 투표율: 미지원
  • 개표: 지원

확인된 API 제한사항

• tupyo/4/... 계열은 현재 기초단체장에 대해 400을 반환한다.
• tupyo/11/... 계열은 현재 교육감에 대해 400을 반환한다.
• 위 두 경우는 앱 오류가 아니라 API 제공 범위 밖으로 본다.

3. 기초단체장 지역 선택 규칙

• 기초단체장 목록은 시도 + 시군구/기초단체장명 결합 문자열로 표시한다.
  • 예: 부산광역시 해운대구
• 실제 개표 요청은 SBS API의 선거구 id를 사용한다.
  • 예: 부산광역시 해운대구 -> 4260900
• 데이터 탭의 지역 코드는 현재 선택된 요청 코드(시도 코드 또는 선거구 코드)를 표시한다.
• 기초단체장 선택 목록은 API sungerInfo/region?type=선거구&sungerType=4 기준으로 구성한다.

4. 데이터 탭 표시 기준

• 데이터 탭에는 기존 선거구명, 지역 코드 외에 다음 정보를 함께 표시한다.
  • 시도명
  • 송출 선거구명
• 데이터 탭은 원본 JSON 전문을 그대로 보여주는 용도는 아니다.
  • API 응답을 ViewModel용 값으로 정규화한 뒤 표시한다.
• DistrictName은 선택/저장용 원본 문자열로 유지한다.
• 송출용 분리 값은 별도 필드로 관리한다.
  • RegionName
  • ElectionDistrictName
• Karisma/Tornado3 송출 변수 시도명NN, 선거구명NN은 위 분리 값을 직접 사용한다.

5. Null-Key 예외 원인과 처리

• 원인:
  • 기초단체장으로 전환하면서 DistrictOptions를 교체하는 순간, ComboBox.SelectedValue가 일시적으로 null을 보낼 수 있었다.
  • 이 값이 그대로 Dictionary.TryGetValue(null, ...) 경로로 들어가며 System.ArgumentNullException (Parameter 'key')가 발생했다.

적용한 방어 규칙

• DistrictName, DistrictCode, ElectionType는 내부적으로 null이 아닌 문자열 상태를 유지한다.
• 지역 옵션 교체 중에는 _isUpdatingDistrictOptions 플래그로 transient UI 값을 무시한다.
• 옵션 교체 전의 preferredName, preferredCode를 캡처해 마지막 유효 선택값 기준으로 복원한다.

6. 변수 매핑 관련 기록

• Karisma 장면 변수 지원 범위 로깅을 추가했다.
  • 현재 컷에 없는 변수명은 경고로 확인 가능하다.
• 다음 alias 매핑을 보강했다.
  • 기준시, 기준시01, 기준시02
  • 유권자수, 유권자수01
  • 투표자수, 투표자수01
  • 득표수바NN
  • 정당원NN
  • 정당색NN

아직 주의가 필요한 변수군

• 의석수 계열
• 판세 지도/그래프 계열
• 경력/공약 계열
• 일부 사진/차트 전용 컷 변수

7. 콤보박스 변경 즉시 갱신

• 선거 종류, 선거구명, 지역 코드, 방송 단계가 바뀌면 짧은 debounce 후 자동으로 RefreshAsync(...)를 다시 호출한다.
• 지역 옵션 재구성 중(_isUpdatingDistrictOptions)이나 API 결과 반영 중(_isApplyingRefreshResult)에는 내부 setter 연쇄로 인한 재조회는 막는다.
• 이 변경으로 콤보박스만 바뀌고 후보현황, 정보값이 이전 조회 결과에 머물러 있던 문제를 줄인다.

8. JSON 응답 파싱 보정

• sungerInfo/region... 계열은 { value: [...] }가 아니라 최상위 배열([...])로 오는 경우가 있다.
• 클라이언트는 이제 value envelope와 최상위 배열을 모두 허용한다.
• 광역단체장/교육감/기초단체장 지역 옵션도 SBS 선거구 목록 기준으로 읽어서 실제 요청 코드와 맞춘다.
• 선택 변경 debounce는 CancellationTokenSource 취소 대신 revision 비교로 바꿔 디버그 출력에 반복 TaskCanceledException이 쌓이는 흐름을 줄였다.
• 선거 종류 전환/상태 복원 도중 비동기 선거구 목록 갱신이 늦게 끝나더라도, 마지막 현재 선택값 기준으로 다시 매칭하도록 보정했다.
• 미지원 단계나 API 오류가 나면 StatusText에 마지막 경고 메시지를 남겨 화면에서 이유를 바로 확인할 수 있게 했다.
• 데이터 탭 상단에 StatusText를 노출해 마지막 갱신 상태/미지원 사유를 바로 볼 수 있게 했다.
• 미지원 조합에서는 투표율/후보 보드를 숨기고 상태 문구만 보이도록 해 이전 수신값을 현재 데이터로 오해하는 흐름을 줄였다.

9. 주요 변경 파일

• Tornado3_2026Election/Services/SbsElectionApiClient.cs
  • SBS API 요청/응답 처리
  • 선거 종류별 지역 옵션 구성
  • JSON 파싱 보정
• Tornado3_2026Election/ViewModels/DataViewModel.cs
  • null-safe 지역 선택 처리
  • 선택 변경 즉시 갱신
  • 상태 문구 및 미지원 조합 표시
• Tornado3_2026Election/MainWindow.xaml
  • 데이터 탭에 시도명, 송출 선거구명, StatusText 표시
• Tornado3_2026Election/Services/KarismaTornado3Adapter.cs
  • RegionName, ElectionDistrictName 기반 송출 변수 매핑
• Tornado3_2026Election/Domain/ElectionDataSnapshot.cs
  • 송출용 분리 지역 필드 추가
• Tornado3_2026Election/Persistence/AppState.cs
  • 실제 연동 기준 기본값 정리

10. 현재 상태 및 남은 체크포인트

• dotnet build Tornado3_2026Election.slnx 통과
• 기존 경고는 유지
  • WindowsBase 참조 충돌 경고
  • MSIX 인증서 경고
  • MockTornado3Adapter.ConnectionChanged 미사용 경고
• 코드상 연동/파싱/표시 흐름은 정리 완료
• 남은 실운영 체크:
  • 앱 실행 상태에서 광역단체장 -> 교육감 -> 기초단체장 전환 확인
  • 개표 <-> 사전 전환 시 상태 문구와 보드 표시 확인
  • 실제 송출 컷에서 시도명NN, 선거구명NN 반영 확인