계정 URL 엑셀로 Instagram 프로필을 수집하고 DM 모집메세지 시트를 생성하는 관리자 API입니다.

DM 자동화 API

계정 URL 엑셀을 업로드해 Instagram 프로필 정보를 수집하고, 수작업으로 확인한 이름·금액을 기반으로 DM 모집메세지 시트를 생성합니다.

실제 수집·치환 작업은 파이썬 서버(/tools/dm-automation/*)가 수행하고, 스프링은 잡 이력 관리와 파일 보관을 담당합니다. 수집(COLLECT)은 파이썬 RQ 워커가 비동기로 돌린 뒤 스프링에 콜백으로 완료를 통보하는 구조이고, 모집메세지 생성(GENERATE_MESSAGE)은 동기 프록시입니다.

전체 흐름

수집 API에 계정 URL 엑셀 업로드 → jobId 즉시 반환 (파이썬 큐에 등록됨)
잡 상세 조회로 폴링 (계정 수에 따라 수 시간 소요, 수천~수만 계정이면 2시간 이상)
COMPLETED가 되면 downloadUrl로 1차 결과 엑셀 다운로드
엑셀에서 크리에이터명, 금액을 수작업 확인·수정
수정 엑셀과 모집메세지 템플릿을 모집메세지 API에 업로드 (동기, 즉시 결과 반환)
최종 모집메세지 엑셀 다운로드

엔드포인트

메서드	경로	설명	처리 방식
`POST`	`/ai/admin/dm-automation/collect`	계정 URL 기반 프로필 수집 + 추천금액 계산	비동기
`GET`	`/ai/admin/dm-automation/jobs/{jobId}`	잡 상세 조회 (폴링용)	동기
`GET`	`/ai/admin/dm-automation/jobs`	잡 목록 조회 (이력)	동기
`POST`	`/ai/admin/dm-automation/generate-message`	템플릿 치환 후 모집메세지 시트 생성	동기

전 엔드포인트 ADMIN 권한이 필요합니다.

에러 판별 방법

res.ok 나 HTTP 상태 코드로 에러를 판별하면 안 됩니다.

이 서버의 GlobalExceptionHandler는 모든 CustomException에 대해 HTTP 전송 상태를 항상 200 으로 반환하고, 실제 상태 코드는 응답 본문의 status 필드에 담습니다. 저장소 전역 컨벤션이며 이 API만의 예외가 아닙니다.

프론트는 반드시 body.status !== 200 으로 에러를 판별해야 합니다. HTTP 상태로 판별하면 모든 에러가 성공으로 보입니다.

에러 응답 예시 (HTTP 상태는 200):

{
  "status": 400,
  "code": "UNSUPPORTED_FILE_FORMAT",
  "message": "xlsx 또는 xls 파일만 업로드할 수 있습니다.",
  "data": null
}

잡 상태

상태	설명
`QUEUED`	잡 생성 직후의 짧은 순간. 입력 업로드·큐 등록 전
`RUNNING`	파이썬 큐에 등록되어 워커가 수집 진행 중. `collect` 응답을 받은 시점에 이미 이 상태
`COMPLETED`	성공. `downloadUrl`, `rowCount`, `errorCount` 사용 가능
`FAILED`	실패. `errorMessage`에 사유

COMPLETED가 아닌 상태에서는 downloadUrl, resultFileName, rowCount, errorCount가 모두 null로 내려갑니다. 작업 도중의 불완전한 결과가 노출되지 않도록 서버에서 막습니다.

잡 종류

종류	설명
`COLLECT`	계정 프로필 수집 (비동기)
`GENERATE_MESSAGE`	모집메세지 생성 (동기)

두 종류 모두 같은 잡 이력 테이블에 기록되므로, 목록 조회 API 하나로 전체 이력을 볼 수 있습니다.

결과 파일 다운로드

결과 엑셀은 GCS에 저장되고 downloadUrl에 공개 URL이 담깁니다. 프론트는 별도 인증 헤더 없이 그대로 열면 됩니다.

window.location = data.downloadUrl;

이 링크는 만료되지 않으며, URL을 아는 사람은 인증 없이 파일을 받을 수 있습니다. 경로에 추측 불가능한 무작위 토큰(잡 번호가 아님)이 들어가지만 서명은 하지 않습니다. 외부에 URL을 공유하지 마세요.

가격 공식

추천금액은 파이썬 서버가 팔로워수 구간별로 계산합니다. 스프링은 계산에 관여하지 않습니다.

팔로워수 구간	공식	반올림
`0 ~ 10,000`	`y = 0.8x + 12,000`	1,000엔 단위
`10,001 ~ 30,000`	`y = 0.5x + 15,000`	1,000엔 단위 (21,000 → 20,000 / 22,000 → 23,000 예외)
`30,001 ~ 100,000`	`y = (5/7)x + (60000/7)`	5,000엔 단위
`100,001 ~ 200,000`	`y = 0.7x + 10,000`	10,000엔 단위
`200,001 ~ 300,000`	`y = 0.8x - 10,000`	10,000엔 단위
`300,001 ~ 400,000`	`y = 0.7x + 20,000`	10,000엔 단위
`400,001 ~`	-	`별도 협의`

제약 사항

진행률(%)은 제공하지 않습니다. 파이썬이 중간 상태를 알려주지 않아 RUNNING / COMPLETED만 구분됩니다.
워커가 재배포로 죽으면 그 잡은 콜백을 못 보내 RUNNING으로 남습니다. 복구 스케줄러가 없으므로 관리자가 재실행해야 합니다.
실패한 잡의 자동 재시도는 없습니다.
평균조회수는 수집하지 않습니다.
restricted profile은 팔로워수 0으로 출력됩니다.

개요