chore: core 공유 타입 정의·계약 테스트·CI 구축

Author: KIMSEONGMIN6035

.github/pull_request_template.md

@@ -0,0 +1,36 @@
+## 제목 형식
+`[영역] 설명`
+> 영역 예: 요트-비전, 요트-FSM, 늑대-비전, 늑대-FSM, 코어, 브릿지, 문서
+
+---
+
+## 작업 요약
+<!-- 3~5줄로 무엇을 왜 했는지 설명 -->
+
+---
+
+## 변경 영역
+- [ ] core/
+- [ ] bridge/
+- [ ] vision/
+- [ ] games/
+- [ ] audio/
+- [ ] backend/
+- [ ] frontend/
+- [ ] tests/
+- [ ] docs/
+- [ ] CI / 설정
+
+---
+
+## 테스트
+- [ ] 로컬에서 직접 실행해 동작 확인
+- [ ] 관련 단위 테스트 추가 또는 업데이트
+
+---
+
+## 체크리스트
+- [ ] `ruff check` 통과
+- [ ] `black --check` 통과
+- [ ] 기존 계약 테스트(`pytest tests/test_contracts.py`) 통과
+- [ ] `core/` 수정 시 계약 테스트도 함께 업데이트

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        working-directory: boardgame-ai
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        working-directory: boardgame-ai
+        run: ruff check core/ bridge/ tests/
+
+      - name: Format check (black)
+        working-directory: boardgame-ai
+        run: black --check core/ bridge/ tests/
+
+      - name: Type check (mypy)
+        working-directory: boardgame-ai
+        run: mypy core/ bridge/
+
+      - name: Contract tests
+        working-directory: boardgame-ai
+        run: pytest tests/test_contracts.py -v

README.md

@@ -3,17 +3,19 @@
 ## 📁 디렉토리 구조
 
 ```text
-boardmaster-ai/
+boardgame-ai/
 ├── app.py                  # 전체 모듈을 조립하고 실행하는 진입점
 ├── requirements.txt        # Python 의존성 목록
+├── pyproject.toml          # 패키지 설정 및 개발 도구 설정
 ├── .gitignore              # Git 추적 제외 파일 목록
 │
-├── 📁 core/                # 게임 공통 모델과 이벤트, 식별 로직
-│   ├── models.py           # Player, Session 등 공통 데이터 모델
-│   ├── events.py           # GameEvent, FusionContext 등 공통 이벤트 스키마
-│   ├── player_identifier.py# zone + handedness 기반 플레이어 식별
-│   ├── seat_registration.py# 좌석 등록 및 제스처 확인 로직
-│   └── pointing_resolver.py# 검지 방향과 앵커를 매칭하는 로직
+├── 📁 core/                # 공유 타입·상수 (순수 Python, 외부 라이브러리 금지)
+│   ├── constants.py        # MsgType, CommonPhase, CommonEventType, DEFAULT_PARAMS 등
+│   ├── models.py           # Player, SeatZone 공통 데이터 모델
+│   ├── events.py           # GameEvent, FusionContext 이벤트 스키마
+│   ├── envelope.py         # WSMessage 공통 메시지 봉투
+│   ├── audio.py            # TTSRequest, AudioType, AudioPriority
+│   └── player_manager.py   # 플레이어 CRUD + 좌석 등록 공통 로직
 │
 ├── 📁 vision/              # 객체·제스처 인식을 수행하는 비전 파이프라인
 │   ├── pipeline.py         # 전체 비전 파이프라인 조립
@@ -27,10 +29,10 @@ boardmaster-ai/
 │   ├── yacht/              # 요트다이스 전용 FSM/상태/점수 로직
 │   └── werewolf/           # 늑대인간 전용 FSM/상태/판정 로직
 │
-├── 📁 bridge/              # 비전과 게임 로직을 연결하는 인터페이스 계층
-│   ├── interface.py        # 공통 브리지 인터페이스 정의
-│   ├── local_bridge.py     # 로컬 실행용 직접 호출 브리지
-│   └── websocket_bridge.py # 분리 배포용 WebSocket 브리지
+├── 📁 bridge/              # 비전 ↔ FSM 통신 인터페이스 계층
+│   ├── interface.py        # 추상 Bridge 인터페이스 정의
+│   ├── local_bridge.py     # 인프로세스 직접 연결 (개발/테스트용)
+│   └── websocket_bridge.py # WebSocket 브리지 (Phase 1 후반 구현 예정)
 │
 ├── 📁 audio/               # TTS, 효과음, BGM 등 오디오 관리
 │   ├── manager.py          # 오디오 재생 큐와 인터럽트 관리
@@ -49,9 +51,8 @@ boardmaster-ai/
 │   ├── package.json        # 프론트엔드 의존성 및 스크립트 설정
 │   └── vite.config.js      # Vite 빌드 설정
 │
-├── 📁 weights/             # 학습된 모델 가중치 파일 저장
-│   ├── yacht_best.pt       # 요트다이스 객체 인식 가중치
-│   └── werewolf_best.pt    # 늑대인간 객체 인식 가중치
+├── 📁 weights/             # 학습된 모델 가중치 (Git 제외, Google Drive 공유)
+│   └── README.md           # 명명 규칙 및 관리 방법
 │
 ├── 📁 training/            # 객체 인식 모델 학습 코드와 설정 파일
 │   ├── yacht/              # 요트다이스 학습 데이터 설정
@@ -64,13 +65,17 @@ boardmaster-ai/
 │   └── dice_prototype_v2.py# 주사위 인식 프로토타입 코드
 │
 ├── 📁 tests/               # 게임 로직과 규칙 검증용 테스트 코드
+│   ├── test_contracts.py   # core/ 타입 직렬화·구조 계약 테스트 (CI 필수)
 │   ├── test_yacht_fsm.py   # 요트다이스 FSM 테스트
 │   ├── test_werewolf_fsm.py# 늑대인간 FSM 테스트
 │   ├── test_scoring.py     # 점수 계산 테스트
 │   └── test_fusion_rules.py# 퓨전 규칙 테스트
 │
 └── 📁 docs/                # 설계 문서와 통신/데이터 흐름 명세
+    ├── phase1_spec.md      # 비전↔FSM 인터페이스 계약서 (Phase 1)
+    ├── team_workflow.md    # 브랜치·PR·CI·가중치 관리 규칙
     ├── FSM_설계.md         # FSM 설계 문서
     ├── WebSocket_명세.md   # WebSocket 메시지 명세
     ├── 데이터흐름_명세.md   # 시스템 데이터 흐름 문서
     └── diagrams/           # 아키텍처 및 설계 다이어그램
+```

boardgame-ai/.gitignore

@@ -50,3 +50,19 @@ audio/assets/tts_cache/*.wav
 training/*/images/
 training/*/labels/
 training/runs/
+
+# 개발 도구 캐시
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+# 모델 가중치
+weights/*.onnx
+weights/*.engine
+
+# 학습 데이터
+training/**/datasets/
+training/**/runs/
+training/**/*.zip

boardgame-ai/README.md

@@ -0,0 +1,57 @@
+# BoardGame AI
+
+오버헤드 카메라로 테이블을 비춰 물리 보드게임(요트다이스, 한밤의 늑대인간)을 AI가 자동 진행하는 시스템.
+
+## 빠른 시작
+
+```bash
+cd boardgame-ai
+pip install -e ".[dev]"
+python -c "from core import GameEvent, FusionContext, PlayerManager; print('OK')"
+pytest tests/test_contracts.py -v
+```
+
+## 팀 구성
+
+| 이름   | 담당             |
+|--------|----------------|
+| 김성민 | 요트 비전          |
+| 강병진 | 요트 FSM          |
+| 양승경 | 늑대 비전          |
+| 유형승 | 늑대 FSM          |
+
+## 앱 흐름
+
+`PLAYER_SETUP` → (좌석 등록) → `GAME_SELECT` → `게임 FSM` → `게임 종료`  
+종료 후 3선택지: 플레이어 변경 / 게임 변경 / 재시작
+
+## 레포 구조
+
+```
+boardgame-ai/
+├── core/        공유 타입 & 상수 (순수 Python, 외부 라이브러리 금지)
+├── bridge/      비전↔FSM 통신 인터페이스
+├── vision/      비전 파이프라인 (YOLO, MediaPipe, ByteTrack)
+├── games/       게임별 FSM
+├── audio/       TTS/오디오 모듈
+├── backend/     FastAPI 백엔드
+├── frontend/    태블릿 UI (React)
+├── tests/       계약 테스트
+├── docs/        설계 문서
+├── weights/     모델 가중치 (Git 제외, Drive 공유)
+└── training/    학습 스크립트
+```
+
+## 핵심 원칙
+
+1. `core/`는 순수 Python만 — numpy, cv2, torch 등 외부 라이브러리 import 금지
+2. `core/`는 게임을 몰라야 함 — 요트·늑대 전용 로직을 core에 넣지 않음
+3. 좌표는 정규화 float64 (0.0 ~ 1.0)
+4. ID는 전부 문자열
+5. `state_version`: FSM 전이마다 +1, 불일치 메시지 drop
+6. FSM은 Fusion 통과한 `GameEvent`만 수신 — raw 프레임 수신 금지
+
+## 주요 문서
+
+- [Phase 1 인터페이스 계약서](docs/phase1_spec.md)
+- [팀 워크플로우](docs/team_workflow.md)

boardgame-ai/bridge/README.md

@@ -0,0 +1,24 @@
+# bridge/
+
+비전 파이프라인 ↔ FSM 통신 인터페이스.
+
+- **`LocalBridge`** (현재 사용): 인프로세스 직접 연결. 개발·테스트용.
+- **`WebSocketBridge`** (Phase 1 후반): 태블릿 UI 연동용 WebSocket 브릿지. 미구현.
+
+## 사용 예시
+
+```python
+from bridge import LocalBridge
+
+bridge = LocalBridge()
+bridge.on_game_event(lambda event, ver: print(event, ver))
+bridge.start()
+
+# 비전 파이프라인에서
+bridge.send_game_event(event, state_version=1)
+
+bridge.stop()
+```
+
+`LocalBridge`와 `WebSocketBridge`는 동일한 `Bridge` 인터페이스를 구현하므로
+FSM/비전 코드 변경 없이 교체 가능하다.

boardgame-ai/bridge/__init__.py

@@ -0,0 +1,4 @@
+from bridge.interface import Bridge
+from bridge.local_bridge import LocalBridge
+
+__all__ = ["Bridge", "LocalBridge"]

boardgame-ai/bridge/interface.py

@@ -0,0 +1,28 @@
+"""비전 ↔ FSM 통신 추상 인터페이스."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+from core.events import FusionContext, GameEvent
+
+
+class Bridge(ABC):
+    @abstractmethod
+    def send_game_event(self, event: GameEvent, state_version: int) -> None: ...
+
+    @abstractmethod
+    def send_fusion_context(self, context: FusionContext, state_version: int) -> None: ...
+
+    @abstractmethod
+    def on_game_event(self, handler: Callable[[GameEvent, int], None]) -> None: ...
+
+    @abstractmethod
+    def on_fusion_context(self, handler: Callable[[FusionContext, int], None]) -> None: ...
+
+    @abstractmethod
+    def start(self) -> None: ...
+
+    @abstractmethod
+    def stop(self) -> None: ...

boardgame-ai/bridge/local_bridge.py

@@ -0,0 +1,40 @@
+"""인프로세스 브릿지 구현. 개발/테스트용."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from bridge.interface import Bridge
+from core.events import FusionContext, GameEvent
+
+
+class LocalBridge(Bridge):
+    """같은 프로세스 내에서 비전과 FSM을 직접 연결하는 브릿지.
+
+    핸들러 리스트를 유지하고 send 시 등록된 모든 핸들러를 순차 호출한다.
+    """
+
+    def __init__(self) -> None:
+        self._game_event_handlers: list[Callable[[GameEvent, int], None]] = []
+        self._fusion_context_handlers: list[Callable[[FusionContext, int], None]] = []
+        self._running = False
+
+    def send_game_event(self, event: GameEvent, state_version: int) -> None:
+        for handler in self._game_event_handlers:
+            handler(event, state_version)
+
+    def send_fusion_context(self, context: FusionContext, state_version: int) -> None:
+        for handler in self._fusion_context_handlers:
+            handler(context, state_version)
+
+    def on_game_event(self, handler: Callable[[GameEvent, int], None]) -> None:
+        self._game_event_handlers.append(handler)
+
+    def on_fusion_context(self, handler: Callable[[FusionContext, int], None]) -> None:
+        self._fusion_context_handlers.append(handler)
+
+    def start(self) -> None:
+        self._running = True
+
+    def stop(self) -> None:
+        self._running = False

boardgame-ai/bridge/websocket_bridge.py

@@ -0,0 +1,39 @@
+"""WebSocket 브릿지. Phase 1 후반 구현 예정.
+
+태블릿 UI와 연동하는 WebSocket 기반 브릿지.
+LocalBridge와 동일한 Bridge 인터페이스를 구현하므로 FSM/비전 코드 변경 없이 교체 가능.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from bridge.interface import Bridge
+from core.events import FusionContext, GameEvent
+
+
+class WebSocketBridge(Bridge):
+    """WebSocket 기반 비전 ↔ FSM 브릿지. Phase 1 후반 구현 예정."""
+
+    def __init__(self, host: str = "localhost", port: int = 8765) -> None:
+        raise NotImplementedError(
+            "WebSocketBridge is not yet implemented. " "Use LocalBridge for Phase 0/1 development."
+        )
+
+    def send_game_event(self, event: GameEvent, state_version: int) -> None:
+        raise NotImplementedError
+
+    def send_fusion_context(self, context: FusionContext, state_version: int) -> None:
+        raise NotImplementedError
+
+    def on_game_event(self, handler: Callable[[GameEvent, int], None]) -> None:
+        raise NotImplementedError
+
+    def on_fusion_context(self, handler: Callable[[FusionContext, int], None]) -> None:
+        raise NotImplementedError
+
+    def start(self) -> None:
+        raise NotImplementedError
+
+    def stop(self) -> None:
+        raise NotImplementedError