Skip to content
This repository was archived by the owner on Mar 7, 2026. It is now read-only.

CLIENT_API_GUIDE.md

Latest commit

 

History

History
553 lines (476 loc) · 10.6 KB

CLIENT_API_GUIDE.md

File metadata and controls

553 lines (476 loc) · 10.6 KB
Raw

📘 인터뷰 기반 자서전 생성 시스템 - 클라이언트 API 가이드

🌐 Base URL

http://15.165.32.26:3000/api/v2

🔌 WebSocket URL

ws://15.165.32.26:3000/ws?userId={user_id}

📋 API 엔드포인트

1. 인증 (Authentication)

1.1 디바이스 등록/로그인

POST /auth/device-id-register
Content-Type: application/json

{
  "device_id": "unique-device-identifier"
}

응답:

{
  "user_id": "uuid-string",
  "profile_completed": false
}

2. 사용자 관리 (User Management)

2.1 사용자 메타데이터 설정

POST /user/metadata
Content-Type: application/json

{
  "user_id": "user-uuid",
  "age_group": "ADULT",
  "education_level": "UNIVERSITY_GRADUATE", 
  "gender": "NONE",
  "marital_status": "SINGLE"
}

응답:

{
  "success": true
}

2.2 사용자 프로필 조회

GET /user/profile?userId={user_id}

응답:

{
  "user_id": "uuid",
  "device_id": "device-id",
  "profile_completed": true,
  "age_group": "ADULT",
  "education_level": "UNIVERSITY_GRADUATE",
  "gender": "NONE", 
  "marital_status": "SINGLE",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

2.3 현재 챕터 조회

GET /user/current-chapter?userId={user_id}

응답:

{
  "currentChapter": {
    "id": "chapter-uuid",
    "number": "1",
    "title": "성장과정",
    "description": "출생부터 유년기까지의 성장 과정"
  },
  "nextCandidateChapter": {
    "id": "next-chapter-uuid", 
    "number": "2",
    "title": "가족관계",
    "description": "가족 구성원과의 관계"
  }
}

3. 챕터 관리 (Chapter Management)

3.1 챕터 목록 조회

GET /chapters?userId={user_id}

응답:

{
  "chapters": [
    {
      "id": "chapter-uuid",
      "number": "1", 
      "name": "성장과정",
      "description": "출생부터 유년기까지의 성장 과정",
      "representativeImageUrl": "https://...",
      "isCurrentChapter": true,
      "subchapters": [
        {
          "id": "subchapter-uuid",
          "number": "1.1",
          "name": "출생",
          "description": "태어난 곳과 환경",
          "representativeImageUrl": null
        }
      ]
    }
  ]
}

3.2 챕터 시작

POST /chapters/{chapter_number}/start
Content-Type: application/json

{
  "user_id": "user-uuid"
}

응답:

{
  "success": true,
  "status": "new",
  "message": "챕터가 시작되었습니다",
  "first_question": {
    "id": "question-uuid",
    "text": "어린 시절 가장 기억에 남는 순간은 언제인가요?"
  },
  "message_count": 0
}

4. 대화 (Conversation)

4.1 대화 진행

POST /conversation/{chapter_id}
Content-Type: application/json

{
  "user_id": "user-uuid",
  "message": "저는 어린 시절에 강가에서 뛰어놀던 기억이 가장 인상 깊어요."
}

응답:

{
  "next_question": {
    "id": "question-uuid",
    "text": "그때 어떤 기분이셨나요? 더 자세히 말씀해 주실 수 있나요?"
  }
}

4.2 대화 기록 조회

GET /conversation/{chapter_id}/history?userId={user_id}

응답:

{
  "chapter": {
    "id": "chapter-uuid",
    "number": "1",
    "name": "성장과정", 
    "description": "출생부터 유년기까지의 성장 과정"
  },
  "statistics": {
    "totalMessages": 10,
    "userMessages": 5,
    "aiMessages": 5,
    "firstMessageAt": "2024-01-15T10:30:00Z",
    "lastMessageAt": "2024-01-15T11:00:00Z"
  },
  "messages": [
    {
      "id": "msg-uuid",
      "role": "ai",
      "content": "어린 시절 가장 기억에 남는 순간은 언제인가요?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "id": "msg-uuid",
      "role": "user", 
      "content": "저는 5살 때 할머니와 함께 강가에서 뛰어놀던 기억이 가장 인상 깊어요.",
      "timestamp": "2024-01-15T10:32:00Z"
    }
  ]
}

5. 자서전 관리 (Autobiography Management)

5.1 챕터별 자서전 조회

GET /autobiography/chapters/{chapter_id}?userId={user_id}

응답:

{
  "chapterId": "chapter-uuid",
  "content": "어린 시절 저는...",
  "createdAt": "2024-01-15T12:00:00Z"
}

5.2 자서전 목록 조회

GET /autobiography/list?userId={user_id}

응답:

{
  "userId": "user-uuid",
  "totalChapters": 8,
  "completedChapters": 3,
  "autobiographies": [
    {
      "chapterId": "chapter-uuid",
      "chapterNumber": "1",
      "chapterTitle": "성장과정",
      "content": "어린 시절 저는...",
      "summary": "부산에서 태어나 바다를 보며 자란 이야기",
      "imageUrl": "https://...",
      "createdAt": "2024-01-15T12:00:00Z",
      "isCompleted": true
    }
  ]
}

5.3 자서전 상세 조회

GET /autobiography/detail/{chapter_id}?userId={user_id}

응답:

{
  "chapterId": "chapter-uuid",
  "chapterNumber": "1",
  "chapterTitle": "성장과정",
  "chapterDescription": "출생부터 유년기까지의 성장 과정",
  "content": "어린 시절 저는...",
  "summary": "부산에서 태어나 바다를 보며 자란 이야기",
  "imageUrl": "https://...",
  "createdAt": "2024-01-15T12:00:00Z",
  "updatedAt": "2024-01-15T12:30:00Z",
  "messageCount": 15,
  "topics": ["바다", "부산", "어린시절", "가족"]
}

6. 책 생성 (Book Generation)

6.1 전체 자서전 책 생성

POST /autobiography/book/generate
Content-Type: application/json

{
  "userId": "user-uuid"
}

응답:

{
  "bookId": "book-uuid",
  "chapters": [
    {
      "chapterId": "chapter-uuid",
      "title": "성장과정",
      "content": "어린 시절 저는...",
      "imageUrl": "https://..."
    }
  ]
}

6.2 생성된 책 조회

GET /autobiography/book/{book_id}

응답:

{
  "bookId": "book-uuid",
  "userId": "user-uuid", 
  "title": "나의 자서전",
  "totalChapters": 8,
  "createdAt": "2024-01-15T15:00:00Z",
  "chapters": [
    {
      "chapterId": "chapter-uuid",
      "chapterNumber": "1",
      "title": "성장과정",
      "content": "어린 시절 저는...",
      "imageUrl": "https://..."
    }
  ]
}

🔌 WebSocket 이벤트

연결

const ws = new WebSocket('ws://15.165.32.26:3000/ws?userId=your-user-id');

이벤트 타입

1. chapter_selected

챕터가 선택되거나 시작될 때 발생

{
  "event": "chapter_selected",
  "data": {
    "currentChapter": {
      "id": "chapter-uuid",
      "title": "성장과정", 
      "number": "1"
    },
    "question": {
      "id": "question-uuid",
      "text": "어린 시절 가장 기억에 남는 순간은 언제인가요?"
    },
    "nextCandidateChapter": {
      "id": "next-chapter-uuid",
      "title": "가족관계",
      "number": "2"
    }
  }
}

2. topic_updated

대화 중 주제가 추출될 때 발생

{
  "event": "topic_updated",
  "data": {
    "topic": "바다에서의 추억",
    "confidence": 0.85
  }
}

3. interview_sufficient

인터뷰가 충분히 진행되었을 때 발생

{
  "event": "interview_sufficient",
  "data": {}
}

4. chapter_autobiography_generated

챕터 자서전이 생성되었을 때 발생

{
  "event": "chapter_autobiography_generated", 
  "data": {
    "chapterId": "chapter-uuid",
    "content": "어린 시절 저는...",
    "summary": "부산에서 태어나 바다를 보며 자란 이야기"
  }
}

5. chapter_completed

챕터가 완료되었을 때 발생

{
  "event": "chapter_completed",
  "data": {
    "chapterId": "chapter-uuid",
    "nextChapterId": "next-chapter-uuid"
  }
}

📊 Enum 값들

AgeGroup

type AgeGroup = 
  | 'TEENAGER'        // 10대
  | 'YOUNG_ADULT'     // 20대
  | 'ADULT'           // 30대
  | 'MIDDLE_AGED'     // 40-50대
  | 'SENIOR'          // 60대
  | 'ELDERLY';        // 70대 이상

EducationLevel

type EducationLevel = 
  | 'ELEMENTARY_GRADUATE'   // 초등학교 졸업
  | 'MIDDLE_GRADUATE'       // 중학교 졸업
  | 'HIGH_GRADUATE'         // 고등학교 졸업
  | 'UNIVERSITY_GRADUATE'   // 대학교 졸업
  | 'MASTER'                // 석사
  | 'DOCTORATE'             // 박사
  | 'OTHER';                // 기타

Gender

type Gender = 
  | 'MALE'      // 남성
  | 'FEMALE'    // 여성
  | 'NONE';     // 선택 안함

MaritalStatus

type MaritalStatus = 
  | 'SINGLE'    // 미혼
  | 'MARRIED'   // 기혼
  | 'OTHER';    // 기타

MessageRole

type MessageRole = 
  | 'user'      // 사용자 메시지
  | 'ai';       // AI 메시지

ChapterStatus

type ChapterStatus = 
  | 'new'           // 새로운 챕터
  | 'in_progress'   // 진행 중
  | 'completed';    // 완료됨

WSEventType

type WSEventType = 
  | 'chapter_selected'                // 챕터 선택됨
  | 'topic_updated'                   // 주제 업데이트됨
  | 'interview_sufficient'            // 인터뷰 충분함
  | 'chapter_autobiography_generated' // 챕터 자서전 생성됨
  | 'chapter_completed';              // 챕터 완료됨

❌ 에러 응답 형식

모든 API에서 에러 발생 시 동일한 형식으로 응답합니다:

{
  "detail": [
    {
      "loc": ["field_name"],
      "msg": "Error message",
      "type": "error_type"
    }
  ]
}

주요 에러 타입

  • not_found: 리소스를 찾을 수 없음
  • missing_required_parameter: 필수 파라미터 누락
  • any.required: 필수 필드 누락 (Joi 검증)
  • internal_server_error: 서버 내부 오류

예시

{
  "detail": [
    {
      "loc": ["user_id"],
      "msg": "User with id 'invalid-user' not found",
      "type": "not_found"
    }
  ]
}

🎯 사용 흐름

  1. 디바이스 등록: POST /auth/device-id-register
  2. 프로필 설정: POST /user/metadata
  3. WebSocket 연결: ws://...?userId={user_id}
  4. 챕터 목록 조회: GET /chapters
  5. 챕터 시작: POST /chapters/{number}/start
  6. 대화 진행: POST /conversation/{chapter_id}
  7. 자서전 확인: GET /autobiography/detail/{chapter_id}
  8. 책 생성: POST /autobiography/book/generate

📚 추가 정보

모든 API는 JSON 형식으로 요청/응답하며, Content-Type은 application/json을 사용합니다.