chocomae/AGENTS.md

프로젝트 개요

초코마에(ChocoMae)는 한글/영문 타이핑 및 마우스 연습용 웹 애플리케이션입니다. Phaser 2.6.2를 사용한 게임화된 타이핑 연습, 교사(마에스트로)를 위한 학급 관리 기능, 랭킹/기록 시스템을 제공합니다.

기술 스택

• 프론트엔드: HTML5, JavaScript (ES5), jQuery 3.3.1, Phaser 2.6.2 게임 엔진, Bootstrap
• 백엔드: PHP 7.x (MySQLi 사용), Python (배치 스크립트)
• 데이터베이스: MariaDB/MySQL (chocomae 데이터베이스)
• 서버: AWS EC2(Docker 컨테이너) 상의 SSL이 적용된 Apache HTTP Server

개발 명령어

이 프로젝트는 메인 애플리케이션에 대해 Node.js/npm 빌드 단계가 없습니다. Apache + PHP 위에서 직접 동작합니다.

Phaser input 플러그인 (/src/util/phaser-input-master/를 수정할 때만 해당):

cd src/util/phaser-input-master
npm install    # grunt + TypeScript 의존성 설치
grunt          # TypeScript → JS 빌드

데이터베이스 설정 (스키마 초기화):

mysql -u <user> -p chocomae < src/web/sql/make_db.sql
mysql -u <user> -p chocomae < src/web/sql/make_db_license_timer.sql
mysql -u <user> -p chocomae < src/web/sql/insert_app.sql
mysql -u <user> -p chocomae < src/web/sql/insert_active_app.sql

배포 — release 브랜치에 push하면 git post-receive 훅이 자동으로 다음을 수행합니다:

1. /volume1/docker/chocomae/html/mouse_typing/로 파일을 체크아웃
2. NA_service_db_setting.php를 service_db_setting.php로 복사하고 localhost를 mysql(Docker 호스트명)로 치환

아키텍처

디렉터리 구조

src/
├── game/          # Phaser 게임 모듈 (클라이언트 측 JS)
├── web/
│   ├── main/      # 진입점 (index.html) + 최상위 HTML 페이지
│   ├── module/    # jQuery .load()로 동적으로 불러오는 HTML 조각
│   ├── js/        # 프론트엔드 JavaScript
│   ├── css/       # 스타일시트
│   ├── server/    # PHP 백엔드 엔드포인트
│   ├── admin/     # 관리자 패널 HTML
│   ├── popup/     # 팝업/모달 HTML
│   └── sql/       # 데이터베이스 스키마 및 시드 파일
├── php-cli/       # PHP 배치 스크립트 (cron으로 실행)
└── util/          # 서드파티 유틸리티 (phaser-input 플러그인 소스)
resources/         # 정적 자산: Bootstrap, jQuery, 폰트, 이미지
test/              # 수동 테스트용 HTML/JS 파일 (자동화된 테스트 러너 없음)

프론트엔드 아키텍처

• 진입점: src/web/main/index.html — 헤더/섹션/푸터 모듈을 동적으로 로드
• 모듈 로딩: jQuery .load()로 src/web/module/에서 HTML 조각을 가져옴
• 상태: maestroID와 게임 세션 데이터에 sessionStorage 사용
• 게임 엔진: 모든 인터랙티브 게임은 src/game/에 위치하며 Phaser 2.6.2 사용, 각 게임 디렉터리는 Phaser 상태(Boot, Load, Game, Result)를 가진 자체 main.js를 보유

백엔드 아키텍처

src/web/server/의 PHP 엔드포인트는 도메인별로 구성되어 있습니다:

• player/ — 플레이어 계정 CRUD
• record/ — 게임 결과 및 랭킹 저장/조회
• maestro/ — 교사 학급 관리 (17개 엔드포인트)
• admin/ — 관리자 운영 (11개 엔드포인트)
• license_timer/ — 구독/라이선스 관리
• mail/ — PHPMailer + Gmail SMTP를 통한 이메일 발송
• lib/ — 공용 PHP 라이브러리 (send_reply_json.php, db_maestro.php 등)
• setup/connect_db.php — 데이터베이스 연결; service_db_setting.php에서 설정을 읽음

모든 엔드포인트는 JSON을 반환합니다. 모든 응답에는 UTF-8 인코딩이 설정되어 있습니다.

데이터베이스 설정

• 개발 환경: src/web/server/setup/NA_service_db_setting.php를 수정 (이 파일이 템플릿이며, service_db_setting.php는 git-ignore 대상으로 배포 시 생성됨)
• 배포 훅이 Docker 네트워킹을 위해 localhost → mysql로 치환

사용자 역할

역할	설명
Player	게임을 플레이하는 최종 사용자 (무료 또는 유료)
Maestro	학생 플레이어 그룹을 관리하는 교사
Admin	전체 권한을 가진 시스템 관리자

Python 배치 스크립트

src/web/server/python/chocomae/와 src/php-cli/batch/에 위치 — 미결제/만료 예정 마에스트로에게 만료 경고 이메일을 발송하는 등의 예약 작업을 처리합니다. 서버에서 cron으로 실행됩니다.