문서(API): MVP 엔드포인트의 백엔드 API 요청·응답 계약 정의

[dkfhddla]

문제

저장소에는 이제 MVP 엔드포인트와 백엔드 서비스 단위가 정의되어 있지만, 구현에 필요한 안정적인 백엔드 API 요청/응답 계약은 아직 정의되어 있지 않다.

기대 동작

백엔드와 프론트엔드가 동일한 페이로드 구조와 상태 규약을 기준으로 작업할 수 있도록, 저장소에 MVP 백엔드 엔드포인트의 지속 가능한 API 계약 문서가 있어야 한다.

범위

• docs/specs/ 아래에 백엔드 API 계약 문서 추가
• MVP 엔드포인트의 요청 및 응답 구조 정의
• 최소한 종목, 거래, 포트폴리오, 알림, 기본 대시보드 경로 포함
• 필요한 경우 생성/수정 입력과 조회 모델 구분
• 해당하는 곳에 계산 상태 및 스키마 검증 관련 응답 필드 문서화

수용 기준

• 문서가 POST /stocks, GET /stocks, PATCH /stocks/{stock_id}의 요청/응답 계약을 정의한다.
• 문서가 POST /trades, PATCH /trades/{trade_id}, DELETE /trades/{trade_id}의 요청/응답 계약을 정의한다.
• 문서가 GET /portfolio/positions와 GET /portfolio/relative-returns의 응답 계약을 정의한다.
• 문서가 GET /alerts/rules, GET /alerts/events, GET /dashboards/default의 응답 계약을 정의한다.
• 문서가 API 전송 구조와 영속성 모델을 명확히 분리한다.
• 새 계약이 기존 가정을 변경한다면 관련 소유 문서를 같은 변경에서 갱신한다.

근거 위치

• 소유 지속 문서: docs/arch/backend-architecture-slices.md - MVP 엔드포인트 표면 제안됨
• 소유 지속 문서: docs/specs/mvp-foundation.md - MVP 백엔드 동작 승인됨
• 소유 지속 문서: docs/specs/stock-signal-view-data-model.md - 엔티티 및 파생 모델 입력 승인됨
• 소유 지속 문서: docs/specs/frontend-user-flow.md - 프론트엔드 API 소비 맥락 승인됨

영향 영역

• docs/specs/
• docs/arch/backend-architecture-slices.md
• docs/specs/mvp-foundation.md
• MAP.md

제외 범위

• API 실제 구현
• OpenAPI 생성 자동화
• 인증 또는 다중 사용자 API 설계