[AI]1단계_모델_API_설계_미션_생성 - 100-hours-a-week/12-marong-Wiki GitHub Wiki

미션 생성 엔드포인트 미설계 이유

현재 /mission/generate 엔드포인트는 예정된 기능으로, 아직 실제 API로 구현되지는 않았습니다. 그 이유는 다음과 같습니다.

미션 생성은 소스 파일 실행을 통해 DB에 저장됨
- FastAPI를 통해 미션을 실시간 생성하지 않고,
- 별도의 스크립트 실행 방식으로 미션을 생성하고 필터링한 후, 직접 DB에 저장하는 방식으로 운영되고 있습니다.
실시간 생성 요청에 대한 서비스 수요 없음
- 현재 서비스는 사용자 요청 시마다 새로운 미션을 생성하지 않고,
- 사전에 생성된 미션을 조회하는 방식으로 동작하므로, 별도의 API가 없어도 서비스에 지장이 없습니다.
API 구현은 향후 운영 방식 변경 시점에 도입 예정
- 향후 사용자 요청에 따라 LLM을 활용한 실시간 미션 생성이 필요해지는 시점에,
- 위 명세에 따라 /mission/generate API를 정식 구현할 계획입니다.

API 엔드포인트 목록(설계 가정)

Method	경로	설명
POST(예정)	/mission/generate	지정된 입력 난이도 수에 대한 마니또 미션 생성
GET(예정)	/mission/history	사용자 요청 기반 마니또 미션 생성 히스토리 조회 (예정)

API 입/출력 형식 명세서

Request

POST /mission/generate

{
  "difficulty": {
    "상": 0,
    "중": 3,
    "하": 0
  }
}

필드명	타입	필수 여부	설명
difficulty	object(dict)	필수	난이도별 요청 개수 ('key': '상', '중', '하' / value: int)

Response

200 OK

{
  "difficulty": "중",
  "missions": [
    {
      "content": "마니띠가 가장 좋아하는 개발 언어는 무엇인지 알아보기 ❤️ 🔍",
      "difficulty": "중"
    },
    {
      "content": "마니띠에게 오늘 한 가지 칭찬 쪽지로 남겨주기 📅 💌",
      "difficulty": "하"
    }
  ]
}

400 Bad Request

{
  "message": "invalid_request",
  "data": null
}

500 Internal Server Error

{
  "message": "internal_server_error",
  "data": null
}

서비스 전체 구조 및 연동 관계

1. FastAPI 서버 (/mission/generate)

사용자 요청(난이도) 처리 → LLM + DB 검색 + 후처리 진행

2. MySQL DB (그룹별 정보, 피드 조회)

Groups 테이블에서 그룹별 설명 조회
Posts, GroupMissions 테이블을 JOIN하여 현재 주차 기준으로 3주간 좋아요가 많았던 게시글의 내용 조회

3. ChromaDB (RAG 컨텍스트)

위 MySQL DB에서 조회한 정보를 포함하여 미션 유사도 검색, 데이터 기반 필터링

4. LLM (HyperCLOVA-X)

난이도 기반 조건 프롬프트로 미션 생성
요청 난이도 이하의 미션만 반환

5. 후처리 단계 (Emoji Mapping)

이모지 자동 매핑 및 부적절 미션 필터링

6. 최종 미션 응답 반환

난이도, 미션 내용 포함된 상, 중, 하 미션 반환

API 호출 예시 및 응답

요청 예시

{
  "difficulty": "중"
}

응답 예시

{
  "difficulty": "중",
  "missions": [
    {
      "content": "마니띠가 가장 좋아하는 개발 언어는 무엇인지 알아보기 ❤️ 🔍",
      "difficulty": "중"
    },
    {
      "content": "마니띠에게 오늘 한 가지 칭찬 쪽지로 남겨주기 📅 💌",
      "difficulty": "하"
    }
  ]
}

참고 사항

현재는 미션 데이터에 대해 DB 실시간 업로드가 불필요하여 API 엔드포인트를 별도로 구현하지 않았으나, 구현하는 경우 위 명세에 따라 구현할 예정입니다.