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 경로

- 앱, 송출 어댑터, 썸네일 생성기, Karisma 디버깅 도구는 `D:\\Elect2026\\T3_Cut`를 고정 기준 경로로 사용한다.
- 사용자 설정값, 저장된 상태값, `TORNADO_T3CUT_PATH`, 디버깅 도구의 `--image-root`/`--root` 입력은 T3_Cut 기준 경로를 바꾸지 않는다.

### 9.5 폴백

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

## 10. 상태 저장 / 자동 저장

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

## 11. 인코딩 규칙

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

## 12. 현재 확인된 빌드 경고

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