Agent Board 비즈니스 규칙
개요
Agent Board는 Agent Treatment Flow로부터 완성된 Board 데이터를 받아 적절한 클라이언트에게 전달하고, 사용자의 상호작용을 저장하여 치료 효과 분석에 활용하는 Message Delivery & Tracking Layer입니다. 이 문서는 Backend(NestJS)와 Mobile Client의 역할을 구분하여 핵심 규칙을 정의합니다.
중요: Agent Board는 메시지의 의미를 해석하지 않으며, 템플릿 렌더링이나 메시지 생성도 수행하지 않습니다. Agent Treatment Flow로부터 이미 렌더링된 완성된 Board 데이터(제목, 내용, 액션 등)를 받아 저장하고 전달하는 역할만 수행합니다. 모든 Board와 상호작용은 영구적으로 저장되어 Agent Treatment Flow가 사용자의 과제 수행도를 분석할 수 있도록 지원합니다.
Backend (NestJS) 비즈니스 규칙
1. Board 전달 및 저장 규칙
1.1 Board 영구 저장
- 규칙: Treatment Flow로부터 받은 완성된 Board 데이터는 PostgreSQL에 저장한다.
- 이유: Mobile 사용자의 비동기적 접속 패턴에 대응
- 저장 항목:
- Board 전체 내용 (title, content, actions - 이미 렌더링된 상태)
- Board 타입, 우선순위, 표시 시간
- 전달 상태 (QUEUED → DELIVERED → VIEWED → INTERACTED)
- 템플릿 ID는 저장하지 않음 (Agent Board는 템플릿을 관리하지 않음)
- 보관 기간: 기본 30일, displayEndTime 기준
1.2 메시지 조회 및 전달
- 규칙: 사용자 접속 시 미전달/미확인 메시지를 우선순위에 따라 전달한다.
- 조회 조건:
- status가 QUEUED 또는 DELIVERED인 메시지
- expiresAt이 현재 시간 이후인 메시지
- 우선순위(priority) 내림차순 정렬
- 전달 후 처리: status를 DELIVERED로 업데이트, deliveredAt 기록
1.3 메시지 생명주기 관리
- 규칙: 메시지 상태를 추적하고 자동으로 아카이빙한다.
- 상태 전이:
EXTERNALLY_COMPLETED
↗ ↘
QUEUED → DELIVERED → VIEWED → INTERACTED → ARCHIVED
↘ ↗
→ EXPIRED → - 자동 처리: 매일 자정에 30일 지난 메시지 아카이빙
2. 상호작용 추적 및 저장 규칙
2.1 상호작용 영구 저장
- 규칙: 모든 사용자 상호작용을 PostgreSQL에 저장한다.
- 이유: Agent Treatment Flow의 치료 효과 분석에 필수적
- 저장 항목:
- 상호작용 타입 (delivered, viewed, clicked, dismissed, action)
- 정확한 타임스탬프
- 세션 정보 (sessionId, platform, appVersion)
- 추가 컨텍스트 데이터
- 보관 기간: 원본 90일, 이후 집계 데이터만 유지
2.2 상호작용 집계
- 규칙: 일별로 사용자별 상호작용 통계를 집계한다.
- 집계 항목:
- 메시지 타입별 전달/조회/클릭/무시 건수
- 평균 응답 시간 (전달→조회, 조회→클릭)
- 시간대별 활동 패턴
- 활용: Treatment Flow가 API로 조회하여 개인화된 치료 과제 생성
2.3 실시간 분석 지원
- 규칙: Treatment Flow의 실시간 분석 요청에 즉시 응답한다.
- 제공 데이터:
- 최근 N일간 상호작용 이력
- 메시지 타입별 반응률
- 과제 수행 완료율
- 성능 요구사항: 조회 API 응답 시간 < 100ms
3. 연결 관리 규칙
3.1 SSE 연결 관리
- 규칙: 사용자당 플랫폼별로 하나의 활성 연결만 허용한다.
- 연결 시 처리:
- 기존 연결 종료
- 새 연결 등록 (Redis에 상태 저장)
- 미전달 메시지 즉시 전송
- 하트비트 시작
3.2 연결 복구 및 동기화
- 규칙: 재연결 시 놓친 메시지와 상태를 동기화한다.
- 동기화 절차:
- 클라이언트가 마지막 수신 메시지 ID 전송
- DB에서 이후 메시지 조회
- 우선순위 순으로 재전송
- 상호작용 이벤트 배치 처리
4. 데이터 정합성 규칙
4.1 트랜잭션 보장
- 규칙: 메시지 저장과 상태 변경은 트랜잭션으로 처리한다.
- 적용 대상:
- 메시지 생성 및 초기 상태 설정
- 상호작용 기록 및 메시지 상태 업데이트
- 일별 집계 생성
4.2 중복 방지
- 규칙: 동일한 상호작용 이벤트의 중복 저장을 방지한다.
- 방법:
- 클라이언트 측 이벤트 ID 활용
- 타임스탬프 + 타입 + 메시지ID 조합으로 중복 체크
- 배치 처리 시 중복 제거
5. 성능 및 확장성 규칙
5.1 쿼리 최적화
- 규칙: 모든 주요 쿼리는 인덱스를 활용한다.
- 인덱스 전략:
- userId + status (미전달 메시지 조회)
- userId + createdAt (최신 메시지 조회)
- messageId + type (상호작용 조회)
5.2 캐싱 전략
- 규칙: 자주 조회되는 데이터는 Redis에 캐싱한다.
- 캐싱 대상:
- 활성 사용자의 최근 메시지 목록
- 일별 상호작용 집계 데이터
- 사용자별 마지막 활동 시간
Mobile Client 비즈니스 규칙
6. 메시지 표시 규칙
6.1 오프라인 지원
- 규칙: 오프라인 상태에서도 캐시된 메시지를 표시한다.
- 캐싱 전략:
- 최근 7일간 메시지 로컬 저장
- 온라인 복귀 시 동기화
- 만료된 메시지 자동 정리
6.2 레이아웃 렌더링
- 규칙: displayRules.layout에 지정된 레이아웃 타입에 따라 렌더링한다.
- 지원 레이아웃:
fullscreen: 전체 화면 모달card: 카드 형태modal: 중앙 모달notification: 상단 알림
7. 상호작용 캡처 규칙
7.1 정확한 이벤트 추적
- 규칙: 모든 사용자 상호작용을 정확한 타임스탬프와 함께 기록한다.
- 추적 항목:
- 메시지 노출 시작/종료 시간
- 스크롤 깊이
- 버튼 클릭 위치
- 제스처 타입
7.2 배치 전송 및 재시도
- 규칙: 네트워크 효율성을 위해 이벤트를 배치로 전송한다.
- 전송 전략:
- 10개 이벤트 또는 5초 중 먼저 도달하는 조건
- 실패 시 로컬 SQLite에 저장
- 지수 백오프로 재시도
모니터링 메트릭
Backend 메트릭
const backendMetrics = {
// 메시지 관리
totalMessages: gauge('board_messages_total', ['status']),
messageAge: histogram('board_message_age_seconds'),
// 상호작용 추적
interactionsSaved: counter('board_interactions_saved_total', ['type']),
interactionLatency: histogram('board_interaction_save_latency_ms'),
// 집계 데이터
dailySummaryGeneration: histogram('board_summary_generation_ms'),
// 데이터베이스
dbQueryDuration: histogram('board_db_query_duration_ms', ['operation']),
dbConnectionPool: gauge('board_db_connections', ['state'])
};
에러 처리 규칙
Backend 에러 처리
- DB 저장 실패: 재시도 후 DLQ로 이동
- 집계 실패: 다음 실행 시 재처리
- 조회 타임아웃: 캐시 데이터 반환
Mobile Client 에러 처리
- 동기화 실패: 로컬 데이터 유지, 백그라운드 재시도
- 렌더링 실패: Fallback UI 표시
- 이벤트 전송 실패: 로컬 큐에 보관
변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 0.1.0 | 2025-06-27 | bok@weltcorp.com | 초기 작성 |