이벤트 관리·트리거·보상 시스템을 담당하는 독서 게이미피케이션 플랫폼 Frolog의 이벤트 도메인 서비스입니다.
JSON Rules Engine 기반으로 조건부 이벤트를 정의하고, 트리거 발생 시 포인트 지급·아이템 부여·이메일 발송 등의 액션을 자동 실행하며, 이벤트 발생 이력을 기록합니다.
- 이벤트 생성·수정·삭제 (관리자)
- JSON Rules Engine 기반 조건/액션 시스템
- 트리거 기반 이벤트 발동 (CheckTriggerEvent)
- 14개 내장 Facts (포인트, 카운트, 날짜, 아이템, 이메일 등)
- 이벤트 발생 시 자동 보상 지급 (포인트, 아이템)
- 이메일 발송 (단건/대량, AWS SES 연동)
- 이벤트 레코드 추적 (발생 이력, 읽음/안 읽음 상태)
- 캐스케이딩 이벤트 (이벤트가 다른 이벤트 트리거)
- 반복 횟수 제한 (repeat)
- 매일 오전 9시 KST 자동 이벤트 트리거 (everyMorning)
- Node.js (ESM), Express 기반
@frolog/express-api-server - ORM: Sequelize (
@frolog/models) - 공통 유틸:
@frolog/common-utils(로거, HashId, SSC 토 큰 등) - API 계약:
@frolog/frolog-api - Rules Engine:
json-rules-enginev7.0.0 - Email: AWS SES (
aws-sdk) - Lint/Format: ESLint, Prettier
npm install
npm run dev # 개발 (nodemon)
npm start # 프로덕션
npm run lint # 코드 규칙 검사src/
index.js # API 서버 부트스트랩, 라우팅, 매일 오전 9시 스케줄러
common/
util.js # 유틸리티 함수
rules/
facts.js # Facts 레지스트리 및 래퍼
utils.js # 파라미터 처리 유틸 (restoreParams)
facts/ # 개별 Fact 구현체
addPoints.js # 포인트 지급
count.js # 이벤트 레코드 총 카운트
todayCount.js # 오늘 발생한 이벤트 레코드 카운트
points.js # 사용자 현재 포인트 조회
grantItem.js # 아이템 지급
maxItemCount.js # 우물 최대 아이템 수 조회
dates.js # 날짜/시간 Facts (now, midnight, morning 등)
sendEmail.js # 단건 이메일 발송
sendEmailBulk.js # 대량 이메일 발송
services/ # API 엔드포인트 핸들러
checkTriggerEvent.js # 이벤트 트리거 (코어 로직)
searchEvent.js # 이벤트 목록 검색
getEvent.js # 이벤트 단건 조회
postEvent.js # 이벤트 생성/수정 (upsert)
editEvent.js # 이벤트 수정
deleteEvent.js # 이벤트 삭제
searchEventRecord.js # 이벤트 레코드 검색 (날짜 범 위 필터)
getEventRecord.js # 이벤트 레코드 단건 조회
postEventRecord.js # 이벤트 레코드 수동 생성
deleteEventRecord.js # 이벤트 레코드 삭제
readEventRecord.js # 이벤트 레코드 읽음 처리src/index.js에서 @frolog/frolog-api 스펙과 서비스 로직을 매핑합니다.
- GET: SearchEvent (admin), GetEvent (admin), SearchEventRecord (login), GetEventRecord (admin)
- POST: PostEvent (admin), CheckTriggerEvent (admin, 코어), PostEventRecord (admin), ReadEventRecord (login)
- PATCH: EditEvent (admin)
- DELETE: DeleteEvent (admin), DeleteEventRecord (admin)
- 매일 오전 9시 KST에 "everyMorning" 트리거 자동 발동
- 자체 재스케줄링 타이머 방식 (nextMorning fact 기반 계산)
- 마스터 프로세스에서만 동작
- SearchEventRecord, ReadEventRecord: 로그인 필수 (사용자 본인 레코드 조회/읽음 처리)
- 나머지 모든 엔드포인트: 관리자 전용 (is_admin=true)
이벤트 정의
- event_key: 고유 식별자 (예: "firstWellItem", "dailyLogin")
- rule: 조건(conditions) 및 액션(actions) JSON 정의
- triggers: 이벤트를 발동시키는 트리거 키 배열
- target: 대상 지정 방식 (user, custom, request/response 필드)
- repeat: 반복 횟수 제한 (null이면 무제한)
- disabled: 비활성화 플래그
- read: 읽음 여부 (사용자 알림용)
트리거 흐름 (CheckTriggerEvent)
- 트리거 키로 활성화된 이벤트 조회
- JSON Rules Engine 인스턴스 생성
- 14개 Facts 등록
- 조건(conditions) 평가 → 충족 시 액션(actions) 실행
- EventRecord 생성 (발생 이력 기록)
- 캐스케이딩 이벤트 재귀 체크
Facts (14개 내장)
포인트/지갑:
- points(params) - 사용자 현재 포인트 조회
- addPoints(params) - 포인트 지급 (params: target, points)
아이템/우물:
- grantItem(params) - 아이템 지급 (params: key, target)
- maxItemCount(params) - 우물 최대 아이템 수 조회
이벤트 카운트:
- count(params) - 이벤트 레코드 총 카운트 (params: eventKey, target)
- todayCount(params) - 오늘 발생한 이벤트 레코드 카운트 (params: eventKey, target)
날짜/시간:
- now() - 현재 ISO 타임스탬프
- lastMidnight() / midnight() - 오늘 00:00 KST (ago 옵션: 과거 날짜)
- nextMidnight() - 내일 00:00 KST
- lastMorning() - 오늘 09:00 KST
- nextMorning() - 내일 09:00 KST
이메일:
- sendEmail(params) - 단건 이메일 발송 (params: template, subject, body, replacements, target)
- sendEmailBulk(params) - 대량 이메일 발송 (target: 'all', 'marketing', 'range', 또는 단일 ID)
파라미터 처리:
- Facts는 중첩 호출 및 동적 파라미터 해석 지원 (restoreParams() 유틸 사용)
- Wallet Service: 포인트 조회/지급 (GetWallet, AddPointsToWallet)
- Store Service: 아이템 지급 (GrantStoreItem)
- Well Service: 우물 아이템 수 조회 (SearchWell)
- User Service: 대량 이메일용 사용자 검색 (SearchUser)
- Email Service: 이메일 발송 (SendEmail, SendEmailBulk)
- SSC_TOKEN: 서비스 간 인증용 토큰 (common-utils)