본문으로 건너뛰기

Agent Treatment Flow 도메인 요구사항

1. 기능 요구사항​

1.1 UserCycle과 TreatmentProcess 관계​

Agent Treatment Flow 도메인은 User 도메인의 UserCycle과 긴밀히 연동되어 작동한다.

  • ATF-FR-001: TreatmentProcess는 UserCycle이 시작된 후 충분한 데이터가 수집되면(보통 Day 8) 자동으로 생성되어야 한다.
  • ATF-FR-002: 하나의 UserCycle에는 하나의 TreatmentProcess만 존재해야 한다 (1:1 매핑).
  • ATF-FR-003: UserCycle의 상태 변화(일시정지, 재개, 종료)는 TreatmentProcess에 자동으로 반영되어야 한다.
  • ATF-FR-004: TreatmentProcess는 UserCycle 없이 독립적으로 존재할 수 없다.

타임라인:

  • Day 1: UserCycle 시작 → 기본 시스템 메시지 제공 시작
  • Day 2-7: 수면 데이터 수집 → 기본 시스템 메시지 지속
  • Day 8: TreatmentProcess 시작 → P1 진입 및 A-H-I-R 순환 시작

1.2 Agent 메시지 생성 및 관리​

Agent Treatment Flow는 불면증 치료를 위한 모든 Agent 메시지를 생성하고 관리하는 Business Logic Layer 역할을 수행한다. 이 도메인은 "무엇을 보여줄 것인가?"에 대한 모든 의사결정을 담당한다.

  • ATF-FR-005: LLM 기반 개인화 메시지 생성 엔진을 구현해야 한다.
  • ATF-FR-006: 메시지 우선순위 결정 시스템을 구현해야 한다 (Critical > High > Medium > Low).
  • ATF-FR-007: 메시지 라이프사이클 관리 시스템을 구축해야 한다 (생성→전달→추적→평가→폐기).
  • ATF-FR-008: 야간 시간대(23:00-06:00) 메시지는 즉시 전달 대신 큐에 저장해야 한다.
  • ATF-FR-009: 다국어 메시지 생성을 지원해야 한다 (한국어, 영어, 독일어).

1.2.1 MAO CTA 연동​

  • ATF-FR-009a: Agent Treatment Flow는 MAO Proactive Engagement(능동 개입)에서 전달된 CTA를 입력으로 받아야 한다.
  • ATF-FR-009b: CTA 메타데이터(targetChannel=agent-treatment-flow, actionType)에 따라 메시지 템플릿, 우선순위, 출력 채널(Agent Board, Chat Launch)을 결정해야 한다.
  • ATF-FR-009c: actionType='chat_launch' 또는 유사 메타데이터가 포함된 CTA는 Agent Board 카드에 Chat 도메인으로 연결되는 버튼을 포함해야 하며, 클릭 시 Chat API를 호출해 해당 CTA 컨텍스트를 전달해야 한다.
  • ATF-FR-009d: MAO가 요청한 CTA 상태(accepted/completed 등)를 회신하고, Agent Board/Chat에서 발생한 상호작용 이벤트를 MAO로 전달해야 한다.

1.3 메시지 유형 구분​

  • 기본 시스템 메시지: 모든 사용자에게 제공되는 9가지 필수 메시지 타입
    • 메시지 타입과 노출 규칙은 표준화되어 있음
    • 메시지 내용은 사용자 데이터 기반으로 개인화됨 (취침/기상 시각, 설문 결과, 진행 상황 등)
    • A-H-I-R 모델과 독립적으로 사전 정의된 트리거에 따라 작동
  • 치료적 개입 메시지: P1-P5 프로세스를 통해 생성되는 심화 메시지
    • A-H-I-R 순환 모델을 따라 가설 기반으로 동적 생성
    • 치료적 Task, 맞춤형 질문, 주간 평가 피드백 등 포함
    • 핵심 서사(Core Narrative)와 개인별 가설에 따라 완전 개인화

1.4 9가지 기본 시스템 메시지 요구사항​

  • ATF-FR-010: 슬립큐 소개

    • 첫 가입 후 Home 화면 진입 시 최우선 노출
    • 사용자가 반드시 확인해야 하며, 건너뛸 수 없음
    • 다른 메시지 처리 후에도 미확인 시 자동 재노출
    • 온보딩 설문 결과를 바탕으로 개인화된 메시지 포함 (이름, 주요 고민, ISI 점수 및 해석)

  • ATF-FR-011: 수면기록 작성하기

    • 슬립큐 소개 완료 후 당일 수면기록 미작성 시 자동 노출
    • Action Button은 수면기록 UI로 직접 이동

  • ATF-FR-013: 기상 시각 안내

    • 사용자가 설정한 기상 시각에 푸시 알림과 함께 Agent Board 노출
    • 개인별 설정된 취침/기상 시각 정보 표시
    • Action Button은 수면기록 UI로 이동

  • ATF-FR-014: 취침 준비 안내

    • 사용자가 설정한 취침 시각 1시간 전에 푸시 알림과 함께 노출
    • 개인별 설정된 취침/기상 시각 정보 표시
    • Action Button은 이완요법 UI로 이동

  • ATF-FR-015: 오늘의 치료 프로그램 안내

    • 수면기록 작성 완료 시 자동 생성 및 노출
    • 권장 취침시간 처방 전까지 지속 노출
    • Action Button은 프로그램 UI로 이동
    • 사용자의 현재 치료 단계와 진행 상황 반영

  • ATF-FR-016: 나의 치료 현황

    • 2주차부터 수면기록 작성 시 노출
    • 현재까지의 치료 진행 상황 요약 제공 (개인별 수면 효율, 개선도 등)
    • 개선 추세 및 주요 성과 포함

  • ATF-FR-018: 서비스 사용 만료 예정 안내

    • 치료 주기 만료 당일 오후 8시에 노출
    • 연장 옵션 또는 종료 절차 안내 포함

  • ATF-FR-017: 최종 설문 분석 결과 안내

    • 4회차 설문 응답 제출 즉시 분석 및 생성
    • 개인별 치료 주기의 전체 결과 및 향후 권고사항 포함
    • 시작 시점 대비 개선 정도를 구체적 수치로 제시

  • ATF-FR-019: 서비스 사용 만료 안내

    • 최종 설문 분석 결과 확인 후 생성
    • 일부 기능이 제한됨을 안내하고 더이상 Agent Board는 업데이트 되지 않음

1.5 5단계 치료 프로세스 (P1-P5)​

초기 평가부터 주간 재평가까지 체계적인 치료 프로세스를 관리한다. 각 단계는 명확한 입력과 출력을 가지며, 단계 간 전환은 자동화되어야 한다.

P1 (초기 평가)​

  • ATF-FR-019: 최소 1주일의 수면기록 수집 후 시작해야 한다.
  • ATF-FR-020: 3가지 출력 생성: 의료진용 보고서, 시스템용 데이터, 환자용 질문
  • ATF-FR-021: 수면 패턴 분석 및 초기 가설 수립
  • ATF-FR-022: 1주일 데이터 수집 완료 시 P2로 자동 전환

P2 (가설 정교화)​

  • ATF-FR-023: P1 결과 기반으로 24시간 이내 시작해야 한다.
  • ATF-FR-024: 3가지 이상의 가설 생성 및 검증
  • ATF-FR-025: 문제 메커니즘 규명 및 강점 파악
  • ATF-FR-026: 가설 확정 후 즉시 P3로 전환

P3 (치료 로드맵)​

  • ATF-FR-027: 개인화된 치료 계획을 수립해야 한다.
  • ATF-FR-028: 최소 3개 Phase, Phase당 3-5개 Task 구성
  • ATF-FR-029: 핵심 서사(Core Narrative) 설계
  • ATF-FR-030: 로드맵 생성 완료 즉시 P4로 전환

P4 (일일 코칭)​

  • ATF-FR-031: 매일 개인화된 Task를 제공해야 한다.
  • ATF-FR-032: 매일 오전 6시 자동 Task 생성
  • ATF-FR-033: 4가지 Task 유형 중 선택 (인지/행동/감정/피드백)
  • ATF-FR-034: 난이도 자동 조절 (Mini/Standard/Advanced)

P5 (주간 평가)​

  • ATF-FR-035: 매주 일요일 자정에 자동 실행되어야 한다.
  • ATF-FR-036: 3축 평가: 수면 개선도, Task 수행률, 심리적 웰빙
  • ATF-FR-037: 4가지 의사결정 경로: SUCCESS, BARRIER, MISMATCH, CRITICAL_ISSUE
  • ATF-FR-038: 의사결정에 따른 자동 전환 처리

1.6 A-H-I-R 순환 모델​

치료적 개입 메시지(P1-P5) 생성 과정에서 지속적인 평가와 개선을 수행한다.

  • ATF-FR-039: P1-P5 치료 프로세스에 A-H-I-R (Assess → Hypothesize → Intervene → Re-evaluate) 순환 모델을 적용해야 한다.
  • ATF-FR-040: 각 순환의 결과를 다음 순환의 입력으로 활용해야 한다.
  • ATF-FR-041: 순환 이력을 기반으로 패턴 인식 및 장기 추세를 분석해야 한다.
  • ATF-FR-042: 치료 목표 달성 또는 치료 기간 종료까지 순환을 지속해야 한다.
  • ATF-FR-043: 기본 시스템 메시지는 A-H-I-R 모델과 독립적으로 운영되어야 한다.

1.7 치료 Task 시스템​

P4 일일 코칭 단계에서 개인화된 치료적 개입 메시지인 Task를 생성하고 관리하여 불면증 치료를 지원한다.

  • ATF-FR-044: 4가지 Task 유형을 지원해야 한다.
    • 인지 접근형: 사고 패턴 수정
    • 행동 유도형: 습관 형성 지원
    • 감정 탐색형: 정서적 장벽 해소
    • 피드백 루프형: 성찰과 평가
  • ATF-FR-045: P2에서 수립된 가설과 P3의 치료 로드맵을 기반으로 Task를 개인화해야 한다.
  • ATF-FR-046: 3단계 난이도 조절 시스템을 구축해야 한다 (Mini/Standard/Advanced).
  • ATF-FR-047: Task 수행률 30% 미만 시 난이도를 자동으로 하향 조정해야 한다.
  • ATF-FR-048: 연속 3일 미수행 시 동기부여 메시지를 추가 생성해야 한다.
  • ATF-FR-049: 핵심 서사(Core Narrative) 테마를 일관되게 적용해야 한다.

1.8 이벤트 기반 메시지 관리​

도메인 이벤트에 반응하여 적시에 적절한 Agent 메시지를 생성한다.

  • ATF-FR-050: 크로스 도메인 이벤트를 구독하고 처리해야 한다.
  • ATF-FR-051: 이벤트별 메시지 생성 규칙을 구현해야 한다.
    • 수면기록 작성 → 즉각적 피드백 생성
    • 학습 모듈 완료 → 축하 메시지 및 다음 단계 안내
    • 설문 응답 제출 → 분석 결과 및 통찰 제공
  • ATF-FR-052: 동시 다발적 이벤트 처리 시 메시지 중복을 방지해야 한다.
  • ATF-FR-053: 메시지 간 시간적 분산을 통해 사용자 피로를 최소화해야 한다.

1.9 임상 지능 및 안전성​

임상적 의사결정을 지원하고 치료 품질을 보장한다.

  • ATF-FR-054: CBT-I 표준 프로토콜을 준수해야 한다.
  • ATF-FR-055: Critical Issue 실시간 감지 시스템을 구축해야 한다.
    • 자살 사고, 극심한 우울감, 심각한 신체 증상 키워드 모니터링
    • 감지 시 24시간 이내 의료진 알림 및 이중 채널 대응
  • ATF-FR-056: 치료 경계를 명확히 해야 한다.
    • 의학적 조언 금지
    • 약물 치료 권유/중단 지시 금지
    • 필요시 전문의 상담 권유로 한정
  • ATF-FR-057: 3주 연속 개선 없음 시 의료진 검토를 자동 권유해야 한다.

2. 비기능 요구사항​

2.1 성능​

  • ATF-NFR-001: LLM 기반 메시지 생성은 30초 이내 완료되어야 한다.
  • ATF-NFR-002: 일일 Task 생성은 매일 오전 6시까지 완료되어야 한다.
  • ATF-NFR-003: 긴급 메시지는 이벤트 발생 후 5초 이내 생성되어야 한다.
  • ATF-NFR-004: P1 초기 평가는 10분 이내, P5 주간 평가는 5분 이내 완료되어야 한다.

2.2 확장성​

  • ATF-NFR-005: 동시 처리 가능 사용자 수 1,000명 이상을 지원해야 한다.
  • ATF-NFR-006: 일일 메시지 생성량 100,000건 이상을 처리할 수 있어야 한다.
  • ATF-NFR-007: 수평적 확장이 가능한 마이크로서비스 아키텍처를 적용해야 한다.

2.3 신뢰성​

  • ATF-NFR-008: 메시지 생성 성공률 99.5% 이상을 유지해야 한다.
  • ATF-NFR-009: LLM API 장애 시 사전 생성된 템플릿으로 폴백해야 한다.
  • ATF-NFR-010: Critical Issue 감지는 100% 신뢰성을 보장해야 한다.

2.4 보안​

  • ATF-NFR-011: (공통 정책 참조) 환자 데이터 암호화는 Platform 표준을 따른다 - PLT-SEC-001, PLT-SEC-003
  • ATF-NFR-012: HIPAA/GDPR 규정을 준수해야 한다.
  • ATF-NFR-013: 모든 Critical Issue 처리 과정을 감사 로그에 기록해야 한다.

2.5 운영 품질 속성(Platform 연계)​

2.6 규제 준수(감사 추적)​

3. 제약사항​

3.1 기술적 제약​

  • ATF-CR-001: LLM API 토큰 제한 내에서 메시지를 생성해야 한다.
  • ATF-CR-002: 치료 단계 전환은 State Machine 패턴을 적용해야 한다.
  • ATF-CR-003: 모든 치료 이벤트는 Event Sourcing으로 관리해야 한다.

3.2 임상적 제약​

  • ATF-CR-004: CBT-I 가이드라인을 엄격히 준수해야 한다.
  • ATF-CR-005: Critical Issue 발생 시 의료진 검토 프로세스를 거쳐야 한다.
  • ATF-CR-006: 치료 중단 시 안전한 종료 절차를 따라야 한다.

3.3 비즈니스 제약​

  • ATF-CR-007: 치료 기간은 최소 4주, 최대 12주로 제한한다.
  • ATF-CR-008: 일일 Task는 최대 3개까지만 생성할 수 있다.
  • ATF-CR-009: 주간 평가는 필수이며, 생략할 수 없다.

4. 가정사항​

4.1 시스템 환경​

  • ATF-AR-001: LLM API(OpenAI GPT-4)가 안정적으로 운영된다고 가정한다.
  • ATF-AR-002: 클라우드 인프라가 충분한 컴퓨팅 리소스를 제공한다고 가정한다. (공통 정책 참조: PLT-NFR-002)
  • ATF-AR-003: Agent Board 도메인이 항상 메시지를 수신할 준비가 되어있다고 가정한다.

4.2 사용자 환경​

  • ATF-AR-004: 사용자가 주 5회 이상 수면기록을 작성한다고 가정한다.
  • ATF-AR-005: 사용자가 Task에 대해 솔직한 피드백을 제공한다고 가정한다.
  • ATF-AR-006: 사용자가 치료에 대한 기본적인 동기를 가지고 있다고 가정한다.

5. 의존성​

5.1 내부 의존성​

  • ATF-DR-001: Agent Board 도메인: 생성된 메시지 전달 및 상호작용 피드백 수신
  • ATF-DR-002: Sleep 도메인: 수면기록 데이터 수집 및 패턴 분석
  • ATF-DR-003: Questionnaire 도메인: ISI, PHQ-9 등 표준 설문 결과 활용
  • ATF-DR-004: Learning 도메인: CBT-I 교육 진도와 Task 연계
  • ATF-DR-005: User 도메인: 사용자 프로필 및 선호도 정보
  • ATF-DR-006: Mobile 도메인: 알림 설정 및 디바이스 정보

5.2 외부 의존성​

  • ATF-DR-007: LLM API: OpenAI GPT-4 기반 메시지 생성
  • ATF-DR-008: Analytics Platform: 치료 효과성 분석 및 예측 모델링
  • ATF-DR-009: Notification Service: 긴급 알림 발송
  • ATF-DR-010: Monitoring System: 시스템 상태 및 성능 모니터링

6. 인터페이스 명세​

6.1 Agent Treatment Flow → Agent Board​

  • ATF-IR-001: 다음 인터페이스를 통해 Agent Board로 메시지를 전달해야 한다.
interface AgentMessage {
  id: string;
  userId: string;
  type: 'task' | 'message' | 'question' | 'insight' | 'alert';
  priority: 'critical' | 'high' | 'medium' | 'low';

  content: {
    title: string;
    body: string;
    actions?: {
      id: string;
      label: string;
      type: 'navigate' | 'submit' | 'dismiss' | 'external';
      payload?: any;
      validation?: ValidationRule[];
    }[];
  };

  metadata: {
    phase: 'P1' | 'P2' | 'P3' | 'P4' | 'P5';
    clinicalIntent: string;
    expectedOutcome: string;
    taskType?: 'cognitive' | 'behavioral' | 'emotional' | 'feedback';
    difficulty?: 'mini' | 'standard' | 'advanced';
    style?: 'empathetic' | 'suggestive' | 'directive' | 'exploratory';
  };

  displayRules: {
    startTime: Date;
    endTime: Date;
    maxDisplayCount: number;
    displayDuration?: number;
    conditions?: DisplayCondition[];
  };

  tracking: {
    generatedAt: Date;
    source: string;
    version: string;
    correlationId?: string;
  };
}

6.2 Agent Board → Agent Treatment Flow​

  • ATF-IR-002: 다음 인터페이스를 통해 Agent Board로부터 상호작용 피드백을 수신해야 한다.
interface InteractionFeedback {
  messageId: string;
  userId: string;

  interaction: {
    type: 'viewed' | 'clicked' | 'completed' | 'dismissed' | 'skipped';
    timestamp: Date;
    duration?: number;
    sequence: number; // 상호작용 순서
  };

  response?: {
    actionId: string;
    value: any;
    completedAt: Date;
    validationPassed: boolean;
  };

  context: {
    deviceInfo: {
      platform: 'ios' | 'android';
      version: string;
      model: string;
    };
    appState: {
      screenName: string;
      sessionId: string;
      backgroundTime?: number;
    };
    userState: {
      lastSleepRecordAt?: Date;
      currentPhase: string;
      activeTaskCount: number;
    };
  };

  analytics: {
    engagementScore: number;
    completionTime?: number;
    retryCount?: number;
  };
}

7. GDPR 컴플라이언스 (개인정보 보호)​

7.1 치료 프로세스 데이터​

백엔드 요구사항​

  • ATF-FR-063: (공통 정책 참조) 치료 프로세스 데이터 보호는 Platform 표준을 따른다:
    • PLT-SEC-001, PLT-SEC-003 임상 데이터 암호화
    • 치료 단계별 데이터 분리
    • 가설 및 로드맵 익명화 옵션
    • 진행 상황 추적 최소화
  • ATF-FR-064: 시스템은 치료 기록 보관을 관리해야 한다.
    • 임상 기록: 15년 보관
    • 일반 치료 기록: 5년 보관
    • 코칭 메시지: 치료 종료 후 1년
    • 위기 프로토콜 기록: 영구 보관

7.2 AI 기반 의사결정​

백엔드 요구사항​

  • ATF-FR-065: 시스템은 AI 의사결정 투명성을 보장해야 한다.
    • 자동화된 결정에 대한 설명
    • 인간 검토 옵션 제공
    • 알고리즘 편향 모니터링
    • 의사결정 로그 기록

8. ISO27001 정보보호 관리​

8.1 치료 데이터 무결성​

백엔드 요구사항​

  • ATF-FR-066: 시스템은 치료 데이터 무결성을 보장해야 한다.
    • 21 CFR Part 11 준수
    • 치료 기록 변경 불가
    • 전자 서명 구현
    • 감사 추적 완전성
  • ATF-FR-067: 시스템은 임상 프로토콜을 보호해야 한다.
    • 프로토콜 버전 관리
    • 승인된 프로토콜만 사용
    • 프로토콜 변경 추적
    • 위기 프로토콜 즉시 접근

8.2 Critical Issue 관리​

백엔드 요구사항​

  • ATF-FR-068: 시스템은 Critical Issue를 안전하게 관리해야 한다.
    • 24시간 대응 체계
    • (공통 정책 참조) 알림 전송 보안: PLT-SEC-002
    • 의료진 접근 통제
    • 사고 대응 기록

9. 변경 이력​

버전날짜작성자변경 내용
0.1.02024-12-27bok@weltcorp.com초안 작성
1.0.02025-01-03bok@weltcorp.com전체 요구사항 정의 완료, overview.md, P1-P5 문서 내용 기반
1.1.02025-01-04bok@weltcorp.comMessagePriority enum 도입, TreatmentProcess 용어 통일
1.2.02025-01-04bok@weltcorp.comUserCycle과 TreatmentProcess 관계 요구사항 추가
1.3.02025-01-04bok@weltcorp.comFR 체계 제거 및 가독성 개선
2.0.02025-01-03bok@weltcorp.comDDD 표준 형식으로 재구성 - Mobile 도메인 문서 형식 참조
2.1.02025-06-23bok@weltcorp.com기본 시스템 메시지와 치료적 개입 메시지 구분 명확화, 개인화 특성 추가
2.2.02025-08-07bok@weltcorp.com요구사항 ID 체계 적용 - ATF 도메인 코드 적용 (ATF-FR-xxx, ATF-NFR-xxx, ATF-CR-xxx, ATF-AR-xxx, ATF-DR-xxx, ATF-IR-xxx)
2.3.02025-08-12bok@weltcorp.comGDPR 및 ISO27001 컴플라이언스 요구사항 추가 (섹션 7, 8) - 치료 프로세스 데이터, AI 투명성, 치료 데이터 무결성