diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..59d7df3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,93 @@ +## 프로젝트 개요 + +초코마에(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/`를 수정할 때만 해당): +```sh +cd src/util/phaser-input-master +npm install # grunt + TypeScript 의존성 설치 +grunt # TypeScript → JS 빌드 +``` + +**데이터베이스 설정** (스키마 초기화): +```sh +mysql -u -p chocomae < src/web/sql/make_db.sql +mysql -u -p chocomae < src/web/sql/make_db_license_timer.sql +mysql -u -p chocomae < src/web/sql/insert_app.sql +mysql -u -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으로 실행됩니다. diff --git a/CLAUDE.md b/CLAUDE.md index 5029e26..eef4bd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,97 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -ChocoMae (초코마에) is a Korean/English typing and mouse practice web application. It features gamified typing exercises (using Phaser 2.6.2), classroom management for teachers (Maestros), and a ranking/record system. - -## Tech Stack - -- **Frontend:** HTML5, JavaScript (ES5), jQuery 3.3.1, Phaser 2.6.2 game engine, Bootstrap -- **Backend:** PHP 7.x with MySQLi, Python (batch scripts) -- **Database:** MariaDB/MySQL (`chocomae` database) -- **Server:** Apache HTTP Server with SSL on AWS EC2 (Docker container) - -## Development Commands - -This project has **no Node.js/npm build step** for the main application. It runs directly on Apache + PHP. - -**Phaser input plugin** (only if modifying `/src/util/phaser-input-master/`): -```sh -cd src/util/phaser-input-master -npm install # install grunt + TypeScript deps -grunt # build TypeScript → JS -``` - -**Database setup** (initialize schema): -```sh -mysql -u -p chocomae < src/web/sql/make_db.sql -mysql -u -p chocomae < src/web/sql/make_db_license_timer.sql -mysql -u -p chocomae < src/web/sql/insert_app.sql -mysql -u -p chocomae < src/web/sql/insert_active_app.sql -``` - -**Deployment** — push to `release` branch; the git post-receive hook automatically: -1. Checks out files to `/volume1/docker/chocomae/html/mouse_typing/` -2. Copies `NA_service_db_setting.php` → `service_db_setting.php` and replaces `localhost` with `mysql` (Docker hostname) - -## Architecture - -### Directory Structure - -``` -src/ -├── game/ # Phaser game modules (client-side JS) -├── web/ -│ ├── main/ # Entry point (index.html) + top-level HTML pages -│ ├── module/ # HTML fragments loaded dynamically via jQuery .load() -│ ├── js/ # Frontend JavaScript -│ ├── css/ # Stylesheets -│ ├── server/ # PHP backend endpoints -│ ├── admin/ # Admin panel HTML -│ ├── popup/ # Popup/modal HTML -│ └── sql/ # Database schema and seed files -├── php-cli/ # PHP batch scripts (run via cron) -└── util/ # Third-party utilities (phaser-input plugin source) -resources/ # Static assets: Bootstrap, jQuery, fonts, images -test/ # Manual test HTML/JS files (no automated test runner) -``` - -### Frontend Architecture - -- **Entry point:** `src/web/main/index.html` — loads header/section/footer modules dynamically -- **Module loading:** jQuery `.load()` fetches HTML fragments from `src/web/module/` -- **State:** `sessionStorage` used for `maestroID` and game session data -- **Game engine:** All interactive games live in `src/game/` and use Phaser 2.6.2; each game directory has its own `main.js` with Phaser states (Boot, Load, Game, Result) - -### Backend Architecture - -PHP endpoints in `src/web/server/` are organized by domain: -- `player/` — CRUD for player accounts -- `record/` — Save/retrieve game results and rankings -- `maestro/` — Teacher classroom management (17 endpoints) -- `admin/` — Admin operations (11 endpoints) -- `license_timer/` — Subscription/license management -- `mail/` — Email sending via PHPMailer + Gmail SMTP -- `lib/` — Shared PHP libraries (`send_reply_json.php`, `db_maestro.php`, etc.) -- `setup/connect_db.php` — Database connection; reads from `service_db_setting.php` - -All endpoints return JSON. UTF-8 encoding is set on all responses. - -### Database Configuration - -- **Development:** Edit `src/web/server/setup/NA_service_db_setting.php` (this is the template; `service_db_setting.php` is git-ignored and generated at deploy time) -- The deploy hook replaces `localhost` → `mysql` for Docker networking - -### User Roles - -| Role | Description | -|------|-------------| -| Player | End users (free or paid) who play games | -| Maestro | Teachers who manage groups of student players | -| Admin | System administrators with full access | - -### Python Batch Scripts - -Located in `src/web/server/python/chocomae/` and `src/php-cli/batch/` — handle scheduled tasks like sending expiration warning emails to unpaid/expiring Maestros. These are run via cron on the server. +@AGENTS.md \ No newline at end of file