Tornado3_2026Election/SYSTEM_SPEC.md

선거방송 송출 프로그램 요구사항 정의 (v0.2)

1. 시스템 개요

1.1 목적

• Tornado3 / Karisma를 통해 선거 방송 자막 컷을 송출한다.
• 디자인(포맷)과 데이터를 매핑한 뒤 준비/송출/아웃 흐름을 운영한다.

1.2 기본 구조

• 방송 채널: 노멀, 좌상단, 하단, 비디오월
• 데이터 모드: 사전, 개표
• 저장형 보조 데이터: 사전데이터(JSON)
• 운영 페이지: 통합 스케줄, 채널별 페이지, 사전데이터, 데이터, 컷리스트, 설정, 로그

2. 데이터 처리

2.1 데이터 수신

• Polling 기반
• 수동 수신 가능
• 수동 수신 시 polling 주기 초기화

2.2 지원 선거 범위

• 실연동 지원:
  • 광역단체장
  • 교육감
  • 기초단체장
• 광역단체장은 개표/사전 투표율을 모두 SBS API로 받는다.
• 교육감, 기초단체장은 개표만 SBS API로 받고, 사전 방송용 역사 데이터는 저장형 사전데이터로 보완한다.

2.3 데이터 기준

• 득표율: 소수점 1자리 반올림
• 득표수: 3자리 콤마
• 개표율 표기: 개표 x.x%

2.4 데이터 유효성

• 필수 필드 누락 시 송출 금지
• 사진 필수 포맷에서 이미지가 없으면 송출 금지
• 단계에 맞지 않는 컷은 목록에서 숨기고 송출 직전 검증에서도 차단

3. 포맷 / 컷 카탈로그

3.1 정의

• 포맷은 하드코딩된 템플릿 카탈로그로 관리한다.
• 각 포맷은 1개 이상의 컷을 가진다.
• 실제 Karisma 씬 파일은 .tscn 기준이다.

3.2 현재 canonical 카탈로그

• Elect2026_Bottom_민방: 15컷
• Elect2026_Normal_민방: 63컷
• Elect2026_Top_민방: 11컷
• 총 89컷

3.3 실제 디자인명 기준

• 현재 카탈로그는 실제 존재하는 .tscn 파일명 기준으로 맞춘다.
• 과거에 사용하던 _L, _END, _7680 계열 별칭은 현재 카탈로그에 노출하지 않는다.
• 저장된 큐/상태 복원을 위해 예전 컷 ID는 내부 별칭 맵으로 canonical 이름에 자동 연결한다.

3.4 루프 컷 규칙

• 같은 컷 이름에 _loop.tscn 파일이 있으면 반복 송출 컷으로 사용한다.
• 최초 송출 시에는 기본 .tscn을 우선 사용한다.
• 이미 송출 중인 상태에서 같은 컷을 다시 호출할 때 _loop.tscn이 있으면 우선 사용한다.
• _loop.tscn이 없으면 기본 .tscn 파일로 폴백한다.

3.5 단계별 사용 규칙

• 사전_역대당선자* 계열은 사전, 개표 양쪽 단계에서 사용 가능
• 사전_역대투표율* 계열은 사전 단계 전용
• 일반 후보/판세/당선/접전 계열은 주로 개표 단계에서 사용

4. 스케줄

4.1 구조

• 채널별 독립 큐 기반
• 현재, 다음, 대기 상태를 구분한다.

4.2 지역 범위

• 큐 추가 시 컷만이 아니라 지역 범위도 함께 지정한다.
• 지원 범위:
  • 전체
  • 선택권역
  • 개별 지역

4.3 제어

• 다음 지정
• 위/아래 순서 변경
• 제거
• 반복
• 빈 스케줄 시 즉시 아웃 또는 마지막 화면 유지

4.4 복원

• 저장 상태 복원 시 채널별 큐와 지역 범위를 함께 복원한다.
• 예전 컷 ID가 저장돼 있어도 복원 시 canonical 컷 ID로 정규화한다.

5. 사전데이터

5.1 저장 위치

• Tornado3_2026Election/Assets/Data/pre_election_history.json

5.2 지원 범위

• 광역단체장: 전국 17개 시도
• 교육감: 전국 17개 시도
• 기초단체장: 전국 262개 선거구

5.3 기능

• 선거 종류/지역 선택
• 역대 투표율 카드 표시
• 역대 당선자 카드 표시
• 엑셀형 편집 그리드
• JSON 저장

5.4 색상 포맷 분리

• 사전_역대당선자* 편집 행에는 ColorParty 콤보박스를 제공한다.
• 표기 정당명과 송출 색상 정당을 분리할 수 있다.
• 송출 시에는 ColorParty가 있으면 이를 우선 사용하고, 없으면 표기 정당명을 사용한다.

6. 썸네일 / 컷리스트

6.1 저장 규칙

• 썸네일은 Assets/Thumbnail/<template.Id>.png 규칙으로 저장한다.

6.2 프리뷰

• 채널 제어 패널의 컷 선택 콤보박스는 선택한 컷의 썸네일 프리뷰를 표시한다.
• 프로젝트 썸네일이 없으면 번들 썸네일, 그것도 없으면 기본 아이콘을 사용한다.

6.3 생성

• 썸네일 생성 기능은 Karisma에 씬을 로드하고 320x180 PNG를 저장한다.
• 씬은 KarismaSceneResolver가 실제 .tscn/_loop.tscn 규칙으로 해석한다.

6.4 컷리스트 페이지

• 전체 컷 목록
• 채널 필터
• 컷별 재생 시간 편집
• 썸네일 현황 요약

7. 직함 표기

• 광역단체장, 교육감, 기초단체장은 전 컷 공통으로 지역명 대신 직함을 사용한다.
• 예:
  • 서울특별시 -> 서울시장
  • 전라남도 -> 전라남도지사
  • 부산광역시 -> 부산광역시교육감
  • 창원시 -> 창원시장

8. RGB / 정당 색상

• RGB txt 기준으로 정당색을 해석한다.
• RGB txt에 style color 지정이 있으면 SetStyleColor(...)를 우선 사용한다.
• style color가 없을 때만 이미지 자산 경로를 사용한다.
• 역사 정당명은 한나라당 -> 국민의힘, 열린우리당 -> 더불어민주당 등 별칭 정규화를 함께 지원한다.

9. Tornado3 / Karisma 연동

9.1 방식

• TCP + Interop.KAsyncEngineLib.dll

9.2 기본 연결

• 기본 대상: 127.0.0.1:30001
• 환경변수:
  • TORNADO_KARISMA_HOST
  • TORNADO_KARISMA_PORT

9.3 채널 바인딩

• 기본:
  • 노멀=0:0
  • 좌상단=0:1
  • 하단=0:2
  • 비디오월=1:0
• 환경변수:
  • TORNADO_KARISMA_BIND_NORMAL
  • TORNADO_KARISMA_BIND_TOPLEFT
  • TORNADO_KARISMA_BIND_BOTTOM
  • TORNADO_KARISMA_BIND_VIDEOWALL

9.4 T3_Cut 탐색

• TORNADO_T3CUT_PATH
• 문서\\Tornado3 Data\\T3_Cut\\T3_Cut
• 문서\\Tornado3 Data\\T3_Cut
• 다운로드\\T3_Cut

9.5 폴백

• 시작 시 T3_Cut 경로가 유효하지 않으면 Mock Adapter로 폴백한다.

10. 상태 저장 / 자동 저장

• 주요 설정 변경 시 자동 저장
• 저장 대상:
  • API 자동 갱신 여부
  • API 갱신 주기
  • 데이터 선택 상태
  • 채널 큐
  • 컷별 재생 시간
  • 방송사 지역 필터

11. 인코딩 규칙

• 텍스트 파일은 UTF-8 기준으로 관리한다.
• 한글 문자열 수정 후에는 ?, U+FFFD, 모지바케가 없는지 반드시 확인한다.

12. 현재 확인된 빌드 경고

• WindowsBase 참조 충돌 경고
• MSIX 인증서 경고
• MockTornado3Adapter.ConnectionChanged 미사용 경고