기능 명세와 화면·API 계약
신청 흐름의 입력·처리·예외·권한을 개발자와 테스트할 수 있는 명세로 작성하기
이번 문서에서 만드는 것
7주는 6주의 와이어프레임을 구현·검증할 수 있는 기능 명세로 바꿉니다. 대상은 세션 신청 흐름 하나입니다. Figma 링크만 전달하고 개발자가 업무 규칙을 추측하게 하지 않는 것이 목표입니다.
좋은 명세는 사용자 행동, 시스템 판단, 입력·응답, 실패 후 행동을 연결합니다. API 기술 선택을 디자이너가 혼자 확정하는 문서가 아니라 기획·디자인·개발이 함께 합의하는 계약입니다.
먼저 고정할 용어와 범위
아래는 학습용 가상 요구사항입니다. 실제 팀의 정책으로 수정한 뒤 사용합니다.
- 세션: 일정과 정원이 있는 학습 모임.
- 신청: 로그인한 회원과 세션의 연결. 같은 회원·세션 중복 신청은 허용하지 않음.
- 신청 가능: 마감 전이며 남은 정원이 있고 이미 신청하지 않은 상태.
- 첫 버전 포함: 목록·상세·신청·신청 결과 확인.
- 제외: 결제·대기열·자동 알림. 제외 항목은 재검토 조건을 별도로 기록.
“마감일 당일”처럼 모호한 표현 대신 기준 시간대와 정확한 마감 시각을 정합니다. 화면에 보이는 정원은 조회 시점의 값이므로 신청 요청 시 서버가 다시 검사합니다.
한 기능의 명세를 채운 예시
| 항목 | 신청 기능 예시 |
|---|---|
| 기능 ID | APPLY-01 |
| 목적 | 회원이 신청 결과를 확실히 알고 준비를 이어감 |
| 진입 조건 | 상세 화면을 열었음 |
| 입력 | 세션 ID. 회원 ID는 로그인 신원에서 결정 |
| 동작 | 신청 버튼 → 서버 검증 → 저장 → 결과 안내 |
| 성공 | 신청 ID·세션·상태를 표시하고 내 신청으로 이동 가능 |
| 중복 | 기존 신청 안내, 중복 행 생성 없음 |
| 마감·정원 초과 | 이유와 다른 세션 탐색 경로 제공 |
| 비로그인 | 로그인 안내 후 원래 상세로 돌아갈 경로 제공 |
| 네트워크 오류 | 상태 확인 또는 재시도 안내, 입력과 맥락 유지 |
회원 ID를 브라우저 입력값으로 신뢰하면 다른 사람 명의의 신청이 생길 수 있습니다. 서버의 인증 신원을 사용해야 한다는 계약을 명시합니다. 버튼 disabled만으로 중복·권한·정원을 보호할 수 없습니다.
화면 상태와 API의 연결
다음 URL과 코드는 팀 합의용 예시이며 앞의 명단 CRUD 실습에 이미 구현된 API가 아닙니다. 백엔드 담당자가 실제 계약을 확정하면 문서도 함께 갱신합니다.
POST /api/sessions/42/applicationsContent-Type: application/json
{}{ "id": 108, "sessionId": 42, "status": "applied"}| 응답 상황 | 화면 | 사용자 다음 행동 |
|---|---|---|
| 201 생성 | 완료 정보 | 내 신청 확인 |
| 인증 필요 | 로그인 안내 | 로그인 후 복귀 |
| 권한 거절 | 권한 없음 | 목록 또는 문의 |
| 없는 세션 | 찾을 수 없음 | 목록으로 이동 |
| 409 충돌 | 중복·마감·정원 사유 | 기존 신청 확인 또는 다른 세션 |
| 연결 실패 | 저장 여부 불확실 안내 | 내 신청 확인 후 재시도 |
401·403 등 실제 코드는 인증 방식에 따라 달라질 수 있으므로 백엔드와 확정합니다. 특히 응답을 못 받았다고 저장되지 않았다고 단정하지 않습니다. 재시도 때 중복 처리를 어떻게 할지 합의해야 합니다.
수용 기준을 Given·When·Then으로 쓰기
- Given: 신청 가능한 세션과 로그인한 회원. When: 신청을 한 번 제출. Then: 신청 한 건이 저장되고 완료 정보를 확인할 수 있다.
- Given: 이미 신청한 회원. When: 같은 신청을 다시 제출. Then: 행이 늘지 않고 기존 신청으로 이동할 수 있다.
- Given: 상세를 연 뒤 다른 사용자가 마지막 자리를 신청. When: 현재 사용자가 제출. Then: 정원 초과가 저장되지 않고 마감 상태를 안내한다.
- Given: 신청 응답 전 연결이 끊김. When: 사용자가 다시 시도. Then: 중복 기록이 생기지 않으며 최종 신청 상태를 확인할 수 있다.
기술 구현 방법을 지정하기 전에 관찰할 결과부터 정합니다. 동시 요청 같은 조건은 그림만으로 검증되지 않으므로 서버 테스트 담당자를 지정합니다.
명세 리뷰와 변경 기록
각 기능 ID에 화면 링크·API 계약·테스트 기준을 연결합니다. 미확정 항목에는 질문, 결정 담당자, 필요한 시점을 적습니다. “추후 결정”만 적고 넘기지 않습니다.
변경 예: APPLY-01 / 중복 신청은 일반 오류 대신 기존 신청 링크 제공 / 이유: 재시도 후 결과 확인 / 영향: 상세·완료 화면, 오류 응답, 테스트 2. 실제 결정 날짜를 적고 이전 합의가 무엇이었는지 남깁니다.
세션 진행과 완료 기준
권장 100분: 용어·정책 20분, 명세 작성 30분, 개발자 역질문 25분, 수용 기준 검사 25분입니다. 기획자 한 명이 설명하지 않아도 개발자가 정상·실패 흐름을 설명할 수 있는지 확인합니다.
완료 기준은 기능 하나에 입력·권한·실패·복구·수용 기준이 있고 미확정 정책과 담당자가 드러나는 것입니다. 제출물은 기능 명세, 화면 상태 표, API 합의와 남은 질문입니다.
더 읽어보기
연결된 PBL 미션과 VOD
| 주차·미션 | 참고 VOD 범위 |
|---|---|
| 7주 · 기능 명세 | PM 6·9장 / Figma 1·2·3장 |
PM은 ‘PM업무, 강의 하나로 정리하기’, Figma는 ‘Figma로 앱 디자인부터 포트폴리오까지’를 뜻합니다.
강좌 안내: 참고 강좌 1 · 참고 강좌 2. 이 문서는 영상 전체를 옮긴 전사 자료가 아닙니다. 세부 내용은 위 공식 문서에서 확인합니다.