5. API 설계 — 명세

이 단계에서 하는 것: 백엔드 아키텍트 역할을 세우고, 화면기획서와 ERD를 근거로 API 명세서(docs/API명세.md)를 만든다. 다음 단계로 넘길 것: 인증 기준 엔드포인트와 상태코드가 정리된 API 명세.

API 명세는 백엔드와 프론트가 함께 지키는 공통 계약이다. 어떤 경로로, 어떤 요청을 보내면, 어떤 응답이 돌아오는지 미리 글로 정해 두면 양쪽이 따로 만들어도 어긋나지 않는다. 아직 코드를 짜지 않고, 계약서부터 쓴다.

준비 확인

3단계에서 docs/화면기획서.md가 만들어져 있다.
4단계에서 docs/ERD.md가 만들어져 있고, Supabase에 테이블과 인증이 서 있다.
이 두 문서가 이번 명세의 근거가 된다.

따라하기

단계 1 — 아키텍트 역할로 API 명세 만들기

Claude Code에 아래 프롬프트를 그대로 붙여 넣는다.

'백엔드 아키텍트' 역할을 만들어줘. API를 설계하고 명세서를 관리한다.
이 역할로, docs/화면기획서.md와 docs/ERD.md를 근거로 API 명세서를 docs/API명세.md로 만들어줘. 최소:
- 거래 목록 조회 / 거래 생성 / 거래 삭제 (모두 로그인 사용자 기준)
- 월별 통계 조회(잔액·카테고리별 합계) — 서버가 집계
- AI 자동 분류(거래 내용 → 카테고리 추천), 월별 요약 — 서버가 Claude API 호출
각 API마다 경로·방식·요청/응답·상태코드(200 / 400 잘못된 요청 / 401 미인증)를 적어줘.
잔액·통계·AI 호출은 반드시 서버에서 한다는 원칙을 명세에 반영해줘.

이렇게 나오면 성공: docs/API명세.md가 만들어지고, 다음이 담겨 있다. - 거래 목록 조회 / 거래 생성 / 거래 삭제, 월별 통계 조회, AI 자동 분류, 월별 요약 엔드포인트. - 각 API마다 경로, HTTP 방식(GET/POST/DELETE), 요청 형식, 응답 형식. - 상태코드가 200(성공) / 400(잘못된 요청) / 401(미인증)으로 구분되어 있다. - 모든 거래 API가 로그인한 사용자 기준으로 동작한다고 적혀 있다.

단계 2 — 계약이 제대로 섰는지 짚어 보기

명세가 우리 원칙을 지키는지 확인한다.

방금 만든 docs/API명세.md에서, 잔액·통계 집계와 AI 호출이 서버에서 이뤄진다고 명확히 적혔는지 짚어줘.
그리고 각 엔드포인트가 미인증(401) 상황을 어떻게 다루는지 한 줄씩 확인해줘. 지금 코드는 만들지 마.

이렇게 나오면 성공: 집계·AI 호출이 서버 몫이라는 점과, 각 엔드포인트의 401 처리가 한 줄씩 확인된다.

이 단계 마무리

백엔드 아키텍트 역할로 docs/API명세.md를 만들었다.
거래 목록/생성/삭제, 월별 통계, AI 분류·요약이 경로·방식·요청/응답·상태코드로 정리됐다.
집계와 AI 호출은 서버에서 한다는 원칙이 명세에 반영됐다.
막히면: 명세가 화면기획서·ERD와 어긋나면, 근거 문서를 다시 지정해 명세를 고쳐 달라고 요청한다.

API 명세는 다음 단계의 계약이다. 백엔드는 이 명세대로 구현하고, 프론트는 이 명세대로 화면에서 호출한다. 다음 단계에서 백엔드 개발자 역할을 세워 API와 AI 기능을 구현한다.