ai999.kr 시스템 아키텍처 및 운영 매뉴얼 (v2.0)

이 문서는 ai999.kr 시스템의 전체 구조, 각 구성 요소의 역할, 그리고 시스템이 어떻게 자동으로 작동하는지를 설명합니다.

1. 시스템 개요: "미리 요리해서 서빙하는 효율적인 식당"

우리 시스템은 크게 세 부분으로 나뉩니다. 각 부분은 독립적으로 작동하며 서로에게 영향을 주지 않습니다.

데이터 수집기 (크롤러): 30초마다 새로운 '재료'(배당률 JSON)를 '창고'(data 폴더)에 가져다 놓는 역할.

데이터 분석기 (전담 요리사): 10초마다 '창고'를 확인하여, '완성된 요리'(최종 분석 결과 캐시)를 만들어 '배식대'(cache 폴더)에 미리 준비해두는 역할.

웹 애플리케이션 (서빙 직원): 손님(사용자)의 요청을 받아 '배식대'에 있는 '완성된 요리'를 즉시 가져다주는 역할.

이 구조 덕분에, 수백 명의 손님이 동시에 몰려와도 서버는 절대 과부하에 걸리지 않습니다.

2. 핵심 구성 요소 상세 설명
2.1. 데이터 수집 시스템 (크롤러)

위치: /opt/crawler/

역할: 외부 사이트에서 원본 배당률 데이터를 수집하여, 가공하지 않은 날것 그대로의 .json 파일로 저장합니다.

파일/폴더	역할
main.py	크롤러의 심장. 외부 사이트에 로그인하고 30초마다 배당률 데이터를 .json 파일로 만들어 아래 data 폴더에 저장합니다.
/data/	재료 창고. main.py가 생성한 원본 .json 파일들이 임시로 쌓이는 곳입니다.
/processed/	재료 보관소. '전담 요리사'(analyzer.php)가 처리를 완료한 원본 .json 파일들이 백업을 위해 이동되는 곳입니다.
2.2. 데이터 분석 및 알림 시스템 (백그라운드)

위치: /var/www/html/

역할: 웹사이트와 독립적으로, 서버 백그라운드에서 조용히 실행되며 모든 무거운 작업을 미리 처리합니다.

파일/프로세스	역할
analyzer.php	전담 요리사. 10초마다 data 폴더를 확인하여 모든 .json 파일을 분석하고, 최종 결과물 2개(ranking_A.json, recommendations_C.json)를 만들어 writable/cache/ 폴더에 저장합니다.
worker.php	알림 전담 직원. 항상 실행 상태로 대기하다가, jobs 테이블에 '알림 발송' 작업 지시서가 들어오면 즉시 수십 명에게 동시에 병렬로 푸시 알림을 발송합니다.
writable/cache/	배식대. '전담 요리사'가 만들어 둔 최종 분석 결과 파일(ranking_A.json 등)이 보관되는 곳입니다.
writable/logs/	작업 일지. analyzer.php와 worker.php가 언제 어떤 작업을 했고, 어떤 오류가 발생했는지 모든 기록을 남기는 곳입니다.
2.3. 웹 애플리케이션 (ai999.kr)

위치: /var/www/html/

역할: 사용자 및 관리자에게 화면을 보여주고, 가벼운 요청만 처리합니다.

파일/폴더	역할
/app/routes.php	웹사이트의 '교통 경찰관'. 사용자의 모든 요청(URL)을 받아, 어떤 페이지를 보여줄지, 어떤 API를 실행할지 결정합니다. 최적화 후, 이 파일은 더 이상 무거운 계산을 하지 않습니다.
/templates/	웹사이트의 '얼굴'. dashboard.phtml, admin.phtml 등 모든 HTML 화면 디자인이 들어있습니다.
/app/Controllers/	기능별 담당자. NotificationController.php처럼, 특정 기능(예: 알림 센터)과 관련된 복잡한 로직을 모아놓은 파일들이 있습니다.
/vendor/	우리 웹사이트가 동작하기 위해 필요한 모든 외부 부품(라이브러리)들이 설치된 폴더입니다.
3. 자동화 시스템 (Crontab & Systemd)

이 시스템은 사람의 개입 없이 모든 것이 자동으로 돌아가게 만드는 핵심입니다.

3.1. Crontab (리눅스 스케줄러)

확인 명령어: crontab -l

주요 작업:

크롤러 출/퇴근: 매주 금,토,일 오전 10시에 main.py를 실행시키고, 오후 6시 20분에 강제 종료시킵니다.

분석기(요리사) 실행: 1분마다 analyzer.php를 10초 간격으로 6번 반복 실행시켜, 실질적으로 10초마다 데이터 분석이 이루어지게 합니다.

3.2. Systemd (서비스 관리자)

확인 명령어: sudo systemctl status notification-worker.service

주요 작업:

알림 직원(워커) 관리: worker.php를 24시간 365일 항상 실행 상태로 유지합니다. 만약 프로그램이 오류로 멈추면, 자동으로 즉시 재시작시켜 서비스가 중단되지 않도록 합니다. 서버가 재부팅되어도 알아서 다시 실행됩니다.

4. 데이터베이스 (MySQL)

데이터베이스 이름: php_login

주요 테이블:

users: 회원 정보 (이용권 만료일 포함)

races: 경주 정보 및 알림 발송 결과(push_sent_count, push_success_count) 기록

jobs: 작업 지시서 보관함. '추천 마권 알림 발송'과 같은 시간이 걸리는 작업들이 여기에 기록됩니다.

notification_history: '알림 센터'에서 보낸 전체 공지/홍보 메시지 내역

5. 문제 발생 시 점검 순서 (Troubleshooting)

대시보드 데이터가 갱신되지 않을 때:

1순위: ps -ef | grep main.py 명령어로 크롤러가 잘 돌고 있는지 확인합니다.

2순위: ls -l /opt/crawler/data 명령어로 data 폴더에 .json 파일이 잘 쌓이고 있는지 확인합니다.

3순위: cat /var/www/html/writable/logs/analyzer.log 명령어로 '전담 요리사'의 작업 일지에 오류가 없는지 확인합니다.

'추천 마권' 알림이 발송되지 않을 때:

1순위: sudo systemctl status notification-worker.service 명령어로 '알림 전담 직원'이 active (running) 상태인지 확인합니다.

2순위: cat /var/www/html/writable/logs/worker.log 명령어로 '알림 전담 직원'의 작업 일지에 오류 메시지가 없는지 확인합니다.

3순위: MySQL에 접속하여 SELECT * FROM jobs; 명령어로 '작업 지시서'가 쌓여만 있고 처리되지 않는지 확인합니다.

이 매뉴얼을 /var/www/html/manual.txt 파일에 덮어쓰기 하시면, 언제든지 시스템의 전체 구조를 다시 확인하실 수 있습니다.