본문으로 건너뛰기

Agent Board Bounded Context

⚠️ agentz-studio 플랫폼 통합 (2025-12-24)

이 도메인은 dha-sleep-api에 유지되며, agentz-studio와 병행 운영됩니다.

┌─────────────────────────────────────────────────────────────────┐
│ agentz-studio                          dha-sleep-api           │
│                                                                 │
│   Chat UI (실시간 대화)                  Agent Board (비동기)   │
│         ↓                                      ↑               │
│   Agent Team → LLM                    Treatment Flow           │
│         ↓                                      ↓               │
│   SSE Stream → App                    Board Message → App      │
│                                                                 │
│   [실시간 대화 채널]                   [비동기 메시지 채널]     │
└─────────────────────────────────────────────────────────────────┘

채널 분리 원칙:

  • agentz-studio Chat: 실시간 대화, Agent 직접 응답, SSE 스트리밍
  • Agent Board: 비동기 메시지, 치료 과제, 푸시 알림, 상호작용 추적

dha-sleep-api에 유지되는 기능 (전체 유지):

  • Message Persistence & Delivery: 메시지 영구 저장 및 전달
  • Interaction Tracking: 사용자 상호작용 추적 및 분석
  • Real-time Connection: SSE 연결 관리
  • Treatment Flow 연동: 치료 콘텐츠 수신 및 표시

agentz-studio 연동 범위:

  • Config Sync: Pattern/Rule 정의를 agentz-studio에서 받아 런타임에 적용
  • Metrics 집계: 상호작용 통계를 agentz-studio Analytics Dashboard로 전송 (집계 데이터만)

dha-sleep-api 전담 (변경 없음):

  • CTA 메시지 생성 및 발송 (Treatment Flow → Agent Board)
  • 사용자 상호작용 추적 및 저장
  • 모든 런타임 실행 로직

관련 문서:

개요​

Agent Board는 불면증 치료 서비스의 Message Delivery & Tracking Layer로서, Agent Treatment Flow로부터 완성된 Board 데이터를 받아 적절한 클라이언트에게 실시간으로 전달하고, 사용자의 모든 상호작용을 저장하여 치료 효과 분석을 지원하는 도메인입니다.

중요한 책임 분리:

  • Agent Board는 템플릿 렌더링이나 메시지 생성을 수행하지 않습니다
  • Agent Treatment Flow가 모든 템플릿 렌더링과 메시지 생성을 담당합니다
  • Agent Board는 이미 완성된 Board 데이터(제목, 내용, 액션 등)를 받아 저장하고 전달만 합니다
  • 이 도메인은 메시지의 비즈니스 의미를 해석하지 않지만, 모든 데이터를 영구적으로 저장하여 Mobile 사용자의 비동기적 접속과 Treatment Flow의 분석 요구에 대응합니다

Backend (NestJS) 핵심 책임​

1. Message Persistence & Delivery​

  • Agent Treatment Flow로부터 받은 모든 메시지를 PostgreSQL에 영구 저장
  • Mobile 사용자 접속 시 미전달/미확인 메시지를 우선순위에 따라 전달
  • 메시지 생명주기 관리 (PENDING → DELIVERED → VIEWED → INTERACTED → ARCHIVED)
  • TTL 기반 자동 만료 및 아카이빙

2. Interaction Tracking & Analytics​

  • 모든 사용자 상호작용(view, click, dismiss 등)을 타임스탬프와 함께 저장
  • 일별/주별 상호작용 통계 자동 집계
  • Treatment Flow의 실시간 분석 요청에 대한 빠른 응답 (< 100ms)
  • 사용자별 과제 수행도 및 참여율 데이터 제공

3. Real-time Connection Management​

  • SSE(Server-Sent Events) 연결 관리
  • 사용자별, 플랫폼별 연결 상태 추적
  • 하트비트를 통한 연결 상태 모니터링
  • 재연결 시 놓친 메시지 및 상태 동기화

4. Data Integrity & Performance​

  • 트랜잭션을 통한 데이터 정합성 보장
  • 효율적인 쿼리를 위한 인덱스 전략
  • Redis 캐싱을 통한 성능 최적화
  • 중복 이벤트 방지 메커니즘

5. Security & Scalability​

  • JWT 기반 인증 및 권한 검증
  • 사용자별 Rate Limiting
  • 수평 확장 지원 (Sticky Session)
  • 메트릭 수집 및 모니터링

Mobile Client 핵심 책임​

1. Message Display & Caching​

  • Backend로부터 받은 메시지를 displayRules에 따라 표시
  • 오프라인 지원을 위한 로컬 메시지 캐싱
  • 레이아웃별 렌더링 (fullscreen, card, modal 등)
  • 만료된 메시지 자동 정리

2. Precise Interaction Capture​

  • 정확한 타임스탬프와 함께 모든 사용자 액션 기록
  • 메시지 노출 시간, 스크롤 깊이, 클릭 위치 추적
  • 세션 컨텍스트 정보 수집 (platform, appVersion 등)
  • 오프라인 시 로컬 SQLite에 저장

3. Efficient Data Synchronization​

  • 배치 처리를 통한 효율적인 이벤트 전송
  • 실패 시 지수 백오프 재시도
  • 온라인 복귀 시 자동 동기화
  • 중복 이벤트 방지

도메인 경계​

Backend가 포함하는 것​

  • 메시지 영구 저장소 (PostgreSQL)
  • 상호작용 이력 저장소
  • 일별 통계 집계 서비스
  • SSE 연결 관리 서비스
  • 분석 API 서비스
  • 캐싱 레이어 (Redis)

Backend가 포함하지 않는 것​

  • 템플릿 관리 및 렌더링 (→ Agent Treatment Flow)
  • 메시지 내용 생성 (→ Agent Treatment Flow)
  • 치료 로직 및 개인화 (→ Agent Treatment Flow)
  • Board 추천 로직 (→ Agent Treatment Flow)
  • 사용자 인증 토큰 발급 (→ Auth 도메인)
  • 실제 UI 렌더링 (→ Mobile Client)
  • 비즈니스 규칙 해석 (→ Agent Treatment Flow)

주요 개념 (Backend)​

BoardMessage (Entity)​

  • 정의: 영구 저장되는 메시지
  • 속성: ID, userId, content, displayRules, status, timestamps
  • 책임: 메시지 생명주기 추적, 상태 관리

BoardInteraction (Entity)​

  • 정의: 사용자 상호작용 기록
  • 속성: messageId, userId, type, timestamp, sessionContext
  • 책임: 정확한 상호작용 이력 보존

BoardInteractionSummary (Aggregate)​

  • 정의: 일별 집계된 상호작용 통계
  • 속성: userId, date, 타입별 통계, 평균 응답 시간
  • 책임: 효율적인 분석 데이터 제공

SSEConnection (Value Object)​

  • 정의: 활성 클라이언트 연결
  • 속성: connectionId, userId, state, lastHeartbeat
  • 책임: 실시간 메시지 전달 채널 관리

의존 관계​

Inbound Dependencies (이 도메인을 사용하는 도메인)​

  • Agent Treatment Flow:
    • 메시지 전달 요청
    • 상호작용 데이터 조회
    • 사용자 참여도 분석

Outbound Dependencies (이 도메인이 사용하는 도메인)​

  • Auth 도메인: JWT 토큰 검증

External Dependencies​

  • PostgreSQL: 메시지 및 상호작용 영구 저장
  • Redis: 연결 상태 및 캐시 관리
  • HTTP/SSE: 실시간 통신

Backend 인터페이스​

제공하는 인터페이스​

1. Board Management Service​

interface BoardManagementService {
  // Treatment Flow로부터 완성된 Board 데이터 수신 및 저장
  createUserBoard(command: CreateUserBoardCommand): Promise<BoardMessage>;
  
  // 사용자의 활성 Board 조회
  getActiveBoards(userId: string): Promise<BoardMessage[]>;
  
  // Board 상태 업데이트
  updateBoardStatus(boardId: string, status: MessageStatus): Promise<void>;
  
  // 만료된 Board 아카이빙
  archiveExpiredBoards(): Promise<number>;
}

interface CreateUserBoardCommand {
  userId: string;
  userCycleId: string;
  boardData: {
    boardType: AgentBoardType;
    priority: AgentBoardPriority;
    status: AgentBoardStatus;
    title: string;           // 이미 렌더링된 제목
    content: string;         // 이미 렌더링된 내용
    actions?: ActionButton[]; // 이미 정의된 액션들
    displayStartTime: Date;
    displayEndTime: Date;
    displayOrder: number;
    metadata?: any;
  };
}

2. Interaction Analytics Service​

interface InteractionAnalyticsService {
  // 상호작용 저장
  saveInteraction(interaction: CreateInteractionDto): Promise<void>;
  
  // 배치 상호작용 처리
  processBatch(batch: InteractionBatchDto): Promise<void>;
  
  // 사용자 참여도 분석
  getUserEngagement(userId: string, period: DateRange): Promise<EngagementMetrics>;
  
  // 메시지 타입별 반응률
  getResponseRateByType(userId: string, messageType: string): Promise<ResponseRate>;
  
  // 일별 통계 생성
  generateDailySummary(date: Date): Promise<void>;
}

3. Real-time Delivery Service​

interface RealtimeDeliveryService {
  // SSE 연결 등록
  registerConnection(userId: string, connectionInfo: ConnectionInfo): Promise<void>;
  
  // 실시간 메시지 전송
  sendToUser(userId: string, message: BoardMessage): Promise<void>;
  
  // 연결 상태 조회
  getConnectionStatus(userId: string): Promise<ConnectionStatus>;
  
  // 놓친 메시지 동기화
  syncMissedMessages(userId: string, lastMessageId: string): Promise<BoardMessage[]>;
}

사용하는 인터페이스​

Auth Service (from Auth Domain)​

interface AuthService {
  // JWT 토큰 검증
  verifyToken(token: string): Promise<TokenPayload>;
  
  // 사용자 권한 확인
  hasPermission(userId: string, permission: string): Promise<boolean>;
}

도메인 이벤트​

발행하는 이벤트​

  • MessageCreated: 새 메시지가 저장됨
  • MessageDelivered: 메시지가 클라이언트에 전달됨
  • MessageViewed: 사용자가 메시지를 확인함
  • InteractionRecorded: 상호작용이 기록됨
  • DailySummaryGenerated: 일별 통계가 생성됨
  • MessageArchived: 메시지가 아카이빙됨

구독하는 이벤트​

없음 - Agent Board는 이벤트를 구독하지 않습니다. 모든 작업은 직접 API 호출을 통해 시작됩니다.

비즈니스 규칙 (Backend)​

데이터 저장 규칙​

  1. 모든 메시지는 최소 30일간 보관
  2. 상호작용 원본은 90일, 집계 데이터는 영구 보관
  3. 사용자당 활성 메시지는 최대 1000개

메시지 전달 규칙​

  1. 우선순위가 높은 메시지부터 전달
  2. 만료된 메시지는 자동으로 상태 변경
  3. 동일 사용자의 중복 메시지 방지

분석 데이터 제공 규칙​

  1. 실시간 쿼리는 100ms 이내 응답
  2. 일별 집계는 매일 자정에 자동 실행
  3. 개인정보는 익명화하여 제공

보안 고려사항​

데이터 보호​

  • 모든 통신은 HTTPS 필수
  • 민감한 사용자 데이터는 암호화 저장
  • 로그에는 개인정보 제외

접근 제어​

  • JWT 토큰 기반 인증
  • 사용자는 자신의 데이터만 접근 가능
  • Treatment Flow는 분석용 집계 데이터만 접근

확장 고려사항​

데이터 증가 대응​

  1. 테이블 파티셔닝 (월별)
  2. 오래된 데이터 아카이빙
  3. 읽기 전용 복제본 활용

트래픽 증가 대응​

  1. 수평 확장 (로드 밸런싱)
  2. 캐시 레이어 강화
  3. 비동기 처리 확대

핵심 원칙​

Agent Board는 신뢰할 수 있는 메시지 전달과 정확한 상호작용 추적을 보장합니다.

  • 모든 메시지는 반드시 전달되어야 함
  • 모든 상호작용은 정확히 기록되어야 함
  • Treatment Flow의 분석 요구에 즉시 응답해야 함
  • Mobile 사용자의 비동기적 접속 패턴을 완벽히 지원해야 함

이러한 설계는 Agent Board를 다음과 같이 만듭니다:

  • 신뢰성: 메시지 유실 없음, 상호작용 누락 없음
  • 분석 가능: 풍부한 데이터로 치료 효과 측정 가능
  • 확장 가능: 사용자와 데이터 증가에 대응 가능
  • 독립성: 다른 도메인의 변경에 영향받지 않음

변경 이력​

버전날짜작성자변경 내용
0.1.02025-06-27bok@weltcorp.com최초 작성