Project

General

Profile

Feature #1529

closed
상이 상이

[T06] 전체 API·DTO 계약 확정

Feature #1529: [T06] 전체 API·DTO 계약 확정

Added by 상재 이 11 days ago. Updated 11 days ago.

Status:
Closed
Priority:
Normal
Assignee:
Start date:
11/06/2026
Due date:
% Done:

100%

Estimated time:
(Total: 0:00 h)

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)

링크


Add

Subtasks 1 (0 open — 1 closed)

Feature #1569: [T06] 공통 에러 계약·에러 DTO·글로벌 예외 핸들러 (후속)Closed상재 이11/06/2026

Remove subtaskActions

Add

Related issues 3 (0 open — 3 closed)

Precedes Feature #1548: [T35] 목표 직무 관리 APIClosed지나 팡11/18/202611/23/2026

Remove relationActions
Precedes Feature #1551: [T37] 개인 경력·프로젝트 이력 APIClosed지나 팡11/18/202611/23/2026

Remove relationActions
Precedes Feature #1553: [T39] 관심 채용공고 북마크 APIClosed지나 팡11/23/202611/26/2026

Remove relationActions

상이 Updated by 상재 이 11 days ago Actions #1

  • % Done changed from 0 to 10
  • Status changed from New to In Progress

작업 착수 (OpenAPI 3.1 계약 작성 시작)

Updated by Anonymous 11 days ago Actions #2

Updated by Anonymous 11 days ago Actions #3

  • Precedes Feature #1551: [T37] 개인 경력·프로젝트 이력 API added

Updated by Anonymous 11 days ago Actions #4

  • Precedes Feature #1553: [T39] 관심 채용공고 북마크 API added

길문 Updated by 길래 문 11 days ago Actions #5

  • Due date set to 11/13/2026
  • Start date changed from 11/06/2026 to 11/11/2026

상이 Updated by 상재 이 11 days ago Actions #6

  • 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 Actions #7

  • 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에 머지.

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 Actions #8

  • Related to Feature #1569: [T06] 공통 에러 계약·에러 DTO·글로벌 예외 핸들러 (후속) added

상이 Updated by 상재 이 11 days ago Actions #9

  • Status changed from Closed to In Progress
  • % Done changed from 100 to 90

하위 일감 #1569(공통 에러 계약·에러 DTO·글로벌 예외 핸들러) 연결을 위해 재오픈. PR #29 산출물은 머지 완료 상태 그대로이며, #1569 머지 후 다시 Closed 처리.

상이 Updated by 상재 이 11 days ago Actions #10

  • Subtask #1569 added

상이 Updated by 상재 이 11 days ago Actions #11

  • 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

Also available in: PDF Atom