SelfCheck_AI 3. API 명세서

---

0. 공통 규약 (Standard)

• Wrapper: 모든 응답은 아래 ApiResponse 형태로 감싸서 반환합니다.JSON { "success": true, "data": { ... }, // 실제 데이터 "error": null // 에러 발생 시 { code, message } }
  
• Status Enum: 비동기 작업(AI)의 상태값은 다음 4가지로 고정합니다.
  • PENDING (대기 중), PROCESSING (생성 중), COMPLETED (완료), FAILED (실패/에러)

---

1. 인증 및 회원 (Auth & User) [보강]

Method	URI	기능 설명	Request Body (핵심)	Response Data (success: true)
POST	/api/v1/auth/register	회원가입	{ email, password }	{ userId: 1, email: "..." }
POST	/api/v1/auth/login	로그인	{ email, password }	{ accessToken: "...", refreshToken: "..." }
POST	/api/v1/auth/refresh	토큰 재발급 🆕	{ refreshToken: "..." }	{ accessToken: "..." }
POST	/api/v1/auth/logout	로그아웃 🆕	-	(성공 메시지)
GET	/api/v1/users/me	내 정보 조회	(Header)	{ userId, email, joinedAt }
DELETE	/api/v1/users/me	회원 탈퇴 🆕	(Header)	(성공 메시지 - Soft Delete 권장)

2. 자소서 관리 (Resume) [명칭 통일]

Method	URI	기능 설명	Request Body (핵심)	Response Data
POST	/api/v1/resumes	자소서 생성	{ jobCategory, question, originalContent }	{ resumeId: 101 }
GET	/api/v1/resumes	목록 조회	?page=0&size=10	{ items: [...], pageInfo: {...} }
GET	/api/v1/resumes/{id}	상세 조회	-	{ resumeId, originalContent, ... }
POST	/api/v1/resumes/{id}/validate	규칙 검사	-	{ valid: false, violations: [{field, msg}] }
PATCH	/api/v1/resumes/{id}	내용 수정/반영	{ originalContent: "...", fromFeedbackId: 5001 }	{ resumeId, updatedAt: "..." }
(기존 내용은 VersionControl로 백업)
DELETE	/api/v1/resumes/{id}	삭제	-	(성공 메시지)

3. AI 첨삭 (LLM A - Editor) [비동기 강화]

Method	URI	기능 설명	Request Body (핵심)	Response Data
POST	/api/v1/resumes/{id}/feedback	첨삭 요청	{ option: "STAR_GUIDE" }	(202 Accepted)
{ status: "PENDING", feedbackId: 5001 }
GET	/api/v1/resumes/{id}/feedback/{fid}	상태/결과 조회	-	(진행중) { status: "PROCESSING", progress: 50 }

(완료) { status: "COMPLETED", editedContent: "..." }
(실패) { status: "FAILED", error: "API_TIMEOUT" } |
| GET | /api/v1/resumes/{id}/diff | Diff 조회 | ?feedbackId=5001 | { diffs: [{ op: "INSERT", text: "..." }] } |

4. 심층 평가 (LLM B - Evaluator) [타겟 명확화]

Method	URI	기능 설명	Request Body (핵심)	Response Data
POST	/api/v1/resumes/{id}/evaluation	평가 요청	{ targetType: "FEEDBACK", feedbackId: 5001 }
("ORIGINAL"도 가능)	(202 Accepted)
{ status: "PENDING", evaluationId: 9001 }
GET	/api/v1/resumes/{id}/evaluation/{eid}	상태/결과 조회	-	(완료) { status: "COMPLETED", scores: {...}, risks: [...] }

5. 결과 리포트 (Report) [스키마 구체화]

Method	URI	기능 설명	Request Body	Response Data (프론트 렌더링용)
GET	/api/v1/resumes/{id}/report	종합 리포트	?evaluationId=9001	{ summary: { passFail: "PASS", scoreAvg: 78.5 }, radarChart: [{ axis: "직무", value: 80 }...], details: { ... } }

6. 버전 관리 (Version Control) [신규]

Method	URI	기능 설명	Request Body	Response Data
GET	/api/v1/resumes/{id}/versions	버전 목록	?page=0	{ items: [{ ver: 1, createdAt: "..." }] }
GET	/api/v1/resumes/{id}/versions/{vid}	버전 상세	-	{ contentSnapshot: "...", reason: "첨삭반영" }

---