Feature #1529
closed[T06] 전체 API·DTO 계약 확정
100%
Description
제목: [T06] 전체 API·DTO 계약 확정
목표 및 사용자 시나리오: S04 API 후보를 T04 화면·기능과 T05 테이블에 1:1 대응시키고, 인증 방식·오류·페이징·응답 타입·비동기 상태 계약을 확정. OpenAPI 3.1 초안과 mock 예시 작성
범위/비범위: API 계약 문서·OpenAPI·DTO 목록·검증 스크립트. FastAPI 구현(T13T18), 프런트 구현(T19)은 비범위
담당자: 이상재 (GitHub: sangjae-lee97)
선행조건: T04 (#1495, PR #13 머지), T05 (#1521, PR #17 머지)
관련 화면/API/DB: docs/API_CONTRACT.md, docs/requirements/FEATURE_BASELINE.md, database/DATA_DICTIONARY.md
완료조건(테스트·증빙 포함): API_CONTRACT.md 업데이트, OpenAPI 3.1 초안(문법·참조 검증), DTO 목록, 화면↔API↔테이블 추적 100%, mock 예시 스키마 검증, 팀 리뷰 승인
예상 일정: 2026-11-06 ~
브랜치 / PR / Merge SHA: task/t06-api-contract / https://github.com/ai-career-platform/ai-career-platform/pull/29 / d1fae3a5e146f745b17189f2191d3d57d3db4a29
Staging 검증 결과: 해당 없음
결정 메모: F-001 인증 방식은 담당자 제안으로 "자체 로그인(이메일+비밀번호, JWT access + refresh 쿠키)" 기준 작성. PM 승인 대기 (T04 D-01)
링크
- 작업지시서: https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/work-orders/initial-30/T06.md
- 선행 T04: https://sulfite-footbath-next.ngrok-free.dev/issues/1495 / https://github.com/ai-career-platform/ai-career-platform/pull/13
- 선행 T05: https://sulfite-footbath-next.ngrok-free.dev/issues/1521 / https://github.com/ai-career-platform/ai-career-platform/pull/17
- 후행 일감: T13
T18, T21T24, T29
Updated by Anonymous 11 days ago
- Precedes Feature #1548: [T35] 목표 직무 관리 API added
Updated by Anonymous 11 days ago
- Precedes Feature #1551: [T37] 개인 경력·프로젝트 이력 API added
Updated by Anonymous 11 days ago
- Precedes Feature #1553: [T39] 관심 채용공고 북마크 API added
상이 Updated by 상재 이 11 days ago
- Description updated (diff)
- % Done changed from 10 to 90
PR 생성 + 리뷰 요청(Crasnec), main의 T04·T05 기준 — 진척도 90%
https://github.com/ai-career-platform/ai-career-platform/pull/29
- OpenAPI 3.1: API 74개, DTO 85개, 예시 173개 검증 통과. 요구사항 36/37, 화면 29/29, 테이블 48/51 연결
- 공유 필요(T13·T30): T13 앱 접두사 /api/v1 vs Staging Nginx의 /api/ 제거 → /api/v1/... 요청 404 위험 (API_CONTRACT.md §7 T06-4)
상이 Updated by 상재 이 11 days ago
- Description updated (diff)
- Due date deleted (
11/13/2026) - Status changed from In Progress to Closed
- % Done changed from 90 to 100
완료 — PR #29 리뷰 후 main에 머지.
- PR: https://github.com/ai-career-platform/ai-career-platform/pull/29
- Merge SHA: d1fae3a5e146f745b17189f2191d3d57d3db4a29 (2026-11-06, main)
- 계약서: https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/API_CONTRACT.md
- OpenAPI: https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/api/openapi.yaml
h3. 머지된 최종 내용 (4개 파일)
- docs/api/openapi.yaml — OpenAPI 3.1, API 74개 · DTO 85개 · 예시 173개. 모든 API에 x-requirements(요구사항)·x-screens(화면)·x-tables(테이블) 추적
- docs/API_CONTRACT.md v0.2 — 공통 규칙, 영역별 API 목록, DTO 목록, v0.1 대비 변경, 미결정 사항
- docs/api/check_openapi.py, test_check_openapi.py — 문법·$ref·예시↔스키마·공통 규칙·추적 검사 (main의 docs/requirements, database/DATA_DICTIONARY.md와 대조)
h3. 작업지시서 결정 사항
- 인증: 자체 로그인 (이메일+비밀번호, JWT 15분 + 갱신 쿠키 14일·사용 시 교체)
- /me 소유권: 토큰 sub로만 사용자 결정, 다른 사람 리소스는 404
- 오류: application/problem+json + code + request_id, 400/401/403/404/409/413/415/422/429/503/504 정책
- 202: 문서 검사·분석·삭제, 탈퇴, AI 작업만. 리소스 status로 진행 확인
- 추적: 기능 요구사항 36/37(FR-CMN-004는 공통 오류 형식으로 충족), 화면 29/29, 테이블 48/51(배치·이용 기록 3개 제외)
h3. 진행 중 바뀐 내용
- T04 리뷰 기준 반영: 비교용 이메일, 비밀번호 재설정 API, 선택 동의만 변경, 문서 다운로드 API(분리 저장소·무작위 이름)
- main의 T04·T05 기준으로 재작성 (T05 위에 쌓았던 브랜치를 main 기준으로 이동)
- T13 골격 대조: 경로 접두사 불일치(T06-4) 발견 → 계약서 §7에 기록, T13(#1498)·T30(#1536) 일감에 공유
h3. 남은 사항
- T06-4 경로 접두사 해결 (T13·T30 담당 결정)
- CI(ci.yml)에 계약 검사 연결 (T28)
상이 Updated by 상재 이 11 days ago
- Related to Feature #1569: [T06] 공통 에러 계약·에러 DTO·글로벌 예외 핸들러 (후속) added
상이 Updated by 상재 이 11 days ago
- Status changed from In Progress to Closed
완료 — 하위 일감 #1569의 PR #41이 main에 머지되어 상위 일감을 다시 Closed 처리합니다.
- 상위 T06 API·DTO 계약: PR #29 main 머지 완료 (d1fae3a5e146f745b17189f2191d3d57d3db4a29).
- 하위 #1569 공통 에러 계약: PR #41 main 머지 완료 (1aa17298d6d5fb1e9e25c8b47caee466b4a043db), Closed / 100%.
- 최종 공통 오류 응답은 application/json의 {code, status, message}. 카탈로그·글로벌 예외 핸들러·API 계약서 §1.4 및 OpenAPI에 반영했습니다.
- PR #41: https://github.com/ai-career-platform/ai-career-platform/pull/41