matcha-alert

Matcha Restock Alert은 Marukyu-Koyamaen 국제 스토어의 모든 말차 제품을 감시하다가 품절 상태였던 제품이 다시 재입고되면 이메일을 보내는 작은 자동화 프로젝트입니다. 스토어가 일정 공지 없이 무작위로 재입고하기 때문에 프로젝트는 클라우드에서 24시간 실행되며 사용자 본인 컴퓨터는 꺼져 있어도 됩니다. 작동 방식: 무료 외부 핑거 서비스인 cron-job.org가 5분마다 workflow_dispatch API를 통해 GitHub Actions 워크플로를 호출합니다. 워크플로는 matcha_monitor.py를 실행하고, 스크립트는 각 제품 페이지를 방문해 스토어 자체 메시지인 "currently out of stock and unavailable"이 있는지 확인합니다. 메시지가 없으면 구매 가능한 상태로 간주합니다. 스크립트는 각 제품의 마지막 상태를 state.json에 저장하고 매 실행 후 리포지토리에 다시 커밋하며, 새롭게 재입고한 경우에만 이메일을 보내 반복 알림 스팸을 방지합니다. 이메일 전송에 실패하면 다음 실행 시 알림을 재시도합니다. 스토어에 부담을 주지 않도록 5분마다 실행되는 작업에서는 현재 품절된 항목만 다시 확인하고, 새로운 품절을 잡기 위해 1시간에 한 번 전체 조회를 합니다. 요청은 2초 간격으로 나뉘어 있고 일반 브라우저 신원을 사용합니다. 스크립트는 카탈로그에서 신규 말차 제품도 스캔해 자동으로 감시 대상에 추가하고, 해당 제품이 나타나면 이메일로 알립니다. 워크플로 자체의 */30 cron 일정은 백업 용도로만 유지됩니다. GitHub cron은 실제로 크게 제한되기 때문입니다. 설정에는 Gmail 앱 비밀번호, SMTP 사용자·비밀번호·수신자에 대한 리포지토리 시크릿, 리포지토리 범위의 세분화된 GitHub 토큰이 필요하며, cron-job.org에서는 JSON 본문을 사용하는 POST 작업으로 Actions 읽기/쓰기 권한을 구성해야 합니다. 테스트 실행이 204를 반환하면 정상 작동이 확인되고, test-email 워크플로 디스패치로 실제 전달을 검증합니다. 감시 목록은 약 50개의 말차 제품이 담긴 products.json에 있으며, 항목을 추가하거나 제거하거나 "watch": false로 일시정지할 수 있습니다. 자동 발견된 제품은 state.json에 저장되며 같은 방식으로 일시정지할 수 있습니다. 주요 파일은 검사와 이메일 전송을 담당하고 --force로 로컬에서도 실행할 수 있는 matcha_monitor.py, products.json, state.json, GitHub Actions 워크플로 파일입니다. 참고: 스토어는 과도한 스크래핑을 권장하지 않으며 봇 보호가 요청을 차단할 수 있습니다. 스크립트는 차단 또는 챌린지 페이지를 감지하고 이를 재고 있음 상태로 잘못 판단하지 않으며, 차단된 확인은 다음 실행에서 재시도합니다. 말차는 주문당 5개로 제한되며, 스토어는 재판매용이라고 판단한 주문을 거절합니다.