공통 인증
처리 흐름은 Mermaid 소스 코드로 제공합니다.
JWT 인증이 활성화된 서버에서 제공합니다. 이 로그인 API 자체에는 Bearer 토큰이 필요하지 않습니다. 클럽별 DB의 동일 사용자를 가정하지 않습니다.
로그인과 가입 상태는 클럽별로 독립적입니다. 같은 익명키도 대상 `club`이 다르면 별도 사용자로 식별하며, 로그인은 다른 클럽의 가입이나 프로필 생성을 수행하지 않습니다. 클럽 API는 검증된 JWT의 `sub`를 사용자 ID로 사용하고, `club`과 `aud`가 해당 클럽을 가리키는지 확인합니다.
공통 오류 응답
오류 응답은 application/problem+json`을 사용합니다. `type`은 `about:blank`이며 직렬화 설정에 따라 생략될 수 있습니다. `title·`detail`은 표시용 한국어 설명, `status`는 HTTP 상태, `instance`는 query를 제외한 요청 경로, `code`는 안정적인 소문자 snake_case 값입니다. 클라이언트는 `detail`이나 `title`로 분기하지 않습니다.
기존 업무 오류의 HTTP 상태와 code를 유지합니다. 메시지는 한국어로 정리되며 식단 오류에도 detail이 포함됩니다. JSON 구문·타입·필수 입력 오류는 400/invalid_request, 지원하지 않는 Content-Type은 415/unsupported_media_type, 메서드는 405/method_not_allowed, 예상하지 못한 서버 실패는 `500/internal_error`입니다. 로그인 입력 검증에도 같은 규칙을 적용합니다.
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
|
토큰 누락·만료·검증 실패 |
대상 클럽으로 다시 로그인합니다. |
403 |
|
인증된 JWT의 대상 클럽·사용자 식별 조건 불일치 |
대상 클럽과 접근 권한을 확인합니다. |
403 |
|
식단 컨트롤러의 JWT 식별 거절 |
식단 클럽 토큰과 접근 권한을 확인합니다. |
500 |
|
예상하지 못한 서버 오류 |
자동으로 쓰기 요청을 반복하지 않고 상태를 확인합니다. |
보안 필터의 401에는 `WWW-Authenticate: Bearer`가 포함되며 잘못된 토큰에는 안전한 `error="invalid_token"`이 추가됩니다. 잘못된 Bearer 요청의 기존 400 상태는 `invalid_request`로 유지합니다. 서버가 판정한 토큰 오류의 내부 설명은 응답에 노출하지 않습니다. 업무 오류의 403에는 이 헤더가 항상 제공되는 것은 아닙니다. `Retry-After`와 자동 재시도는 제공하지 않습니다.
HTTP/1.1 401 Unauthorized
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
WWW-Authenticate: Bearer
Content-Type: application/problem+json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 168
{"code":"not_authenticated","status":401,"type":"about:blank","detail":"인증이 필요합니다.","instance":"/api/v1/wakeup/me","title":"인증이 필요합니다."}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI: about:blank |
|
|
한국어 오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 한국어 설명 |
|
|
요청 경로, query 제외 |
|
|
클라이언트 분기용 안정적인 오류 코드 |
HTTP/1.1 403 Forbidden
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/problem+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 173
{"detail":"요청을 수행할 권한이 없습니다.","instance":"/api/v1/wakeup/me","status":403,"title":"요청을 수행할 권한이 없습니다.","code":"forbidden"}
sequenceDiagram
participant C as 클라이언트
participant A as API·JWT 인증
participant S as 클럽 서비스
participant D as 클럽 DB·외부 연동
C->>A: API 요청
alt 토큰 검증 실패
A-->>C: 401 not_authenticated
else 인증 통과
A->>S: 입력·클럽·사용자 검증 후 호출
S->>D: 필요한 업무 처리
D-->>S: 결과 또는 장애
S-->>A: 업무 결과 또는 예외
A-->>C: 성공 DTO 또는 ProblemDetail
end
익명 로그인
Toss 익명 로그인
Toss 일회용 코드로 대상 클럽의 사용자와 JWT를 발급합니다.
POST /api/v1/auth/toss/anonymous
공개 API이며 Bearer 토큰이 필요하지 않습니다.
club(최대 32자)과 code(최대 1024자)를 전달합니다. code는 User.createAnonymousKeyAuthCode()로 발급받으며 다시 사용하지 않습니다.
POST /api/v1/auth/toss/anonymous HTTP/1.1
Content-Type: application/json
Content-Length: 40
Host: localhost:8080
{"club":"wakeup","code":"one-time-code"}
| Path | Type | Description |
|---|---|---|
|
|
대상 클럽: workout, wakeup, diet, attendance |
|
|
User.createAnonymousKeyAuthCode()의 일회용 인증 코드 |
HTTP 200. user.id, accessToken, tokenType, expiresIn을 반환합니다. expiresIn의 단위는 초입니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 119
{"user":{"id":"e02331ee-c858-4741-b7ea-7d4af567569a"},"accessToken":"signed-jwt","tokenType":"Bearer","expiresIn":3600}
| Path | Type | Description |
|---|---|---|
|
|
클럽 범위의 공통 인증 사용자 UUID |
|
|
해당 클럽 JWT |
|
|
토큰 유형: Bearer |
|
|
JWT 유효기간 (초) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
필수 값 누락·입력 제약 위반·JSON 오류 |
입력을 수정합니다. |
400 |
|
지원하지 않는 클럽 |
조건을 확인한 뒤 다시 요청합니다. |
401 |
|
Toss가 코드를 거절함 |
새 일회용 코드를 발급받습니다. |
503 |
|
Toss 인증 장애 |
잠시 후 새 코드로 제한된 횟수만 재시도합니다. |
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 169
{"detail":"입력값을 확인해 주세요.","instance":"/api/v1/auth/toss/anonymous","status":400,"title":"입력값을 확인해 주세요.","code":"invalid_request"}
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as AnonymousAuthenticationService
participant T as Toss 공개 연동
participant D as Auth DB
participant J as JWT 발급
C->>A: 클럽·일회용 코드
A->>S: 입력 검증 후 로그인
S->>T: 대상 클럽 mTLS로 코드 교환
T-->>S: 클럽 범위 익명 키
S->>D: 사용자 식별·저장
D-->>S: 사용자 UUID
S->>J: 대상 클럽 토큰 발급
J-->>S: JWT·유효기간
S-->>A: 업무 결과
A-->>C: 200 응답
대표 오류 응답
아래 예제는 컨트롤러와 ControllerAdvice의 계약 테스트에서 생성합니다. 서비스 오류는 mock으로 재현하며 실제 외부 장애·보안 필터 검증을 대신하지 않습니다.
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
Content-Length: 214
{"detail":"인증 코드가 거절되었습니다. 새 코드를 발급해 주세요.","instance":"/api/v1/auth/toss/anonymous","status":401,"title":"인증이 필요합니다.","code":"invalid_authorization_code"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json
Content-Length: 223
{"detail":"인증 서비스를 일시적으로 이용할 수 없습니다.","instance":"/api/v1/auth/toss/anonymous","status":503,"title":"서비스를 일시적으로 이용할 수 없습니다.","code":"toss_unavailable"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
기상 클럽
처리 흐름은 Mermaid 소스 코드로 제공합니다.
보호 API의 문서 테스트는 가짜 JWT를 주입한 standalone MockMvc 계약 테스트입니다.
보안 필터의 서명·issuer·만료·audience 검증과 DB 잠금·외부 시스템의 동작 검증은 별도 테스트의 범위입니다.
실제 로그인은 공통 인증의 일회용 코드 교환으로 수행합니다. 보호 API 요청마다 Toss 인증을 호출하지 않습니다.
보안 필터와 업무 오류는 공통 ProblemDetail 형식을 사용합니다. 인증 실패는 401/not_authenticated, 공통 권한 거절은 `403/forbidden`입니다. 식단 클럽의 기존 컨트롤러 권한 거절 코드 `diet_token_required`는 유지합니다. 자세한 계약은 공통 오류 응답을 참고합니다.
사용자
사용자 조회
가입한 사용자 정보를 조회합니다.
GET /api/v1/wakeup/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/wakeup/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 118
{"id":"10000000-0000-0000-0000-000000000001","name":"아침형","tossUserKey":null,"createdAt":"2026-09-29T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
공통 인증 사용자 UUID |
|
|
이름 |
|
|
기존 토스 사용자 키 (null 허용) |
|
|
가입 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
가입 정보 없음 |
사용자 가입 API를 호출합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant D as 기상 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사용자 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
사용자 가입
검증된 사용자 ID로 프로필을 생성합니다. 이미 가입한 사용자는 기존 프로필을 반환합니다.
POST /api/v1/wakeup/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name은 공백만인 값을 제외하고 1~16자입니다.
POST /api/v1/wakeup/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 20
Host: localhost:8080
{"name":"아침형"}
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
1~16자 이름 |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 118
{"id":"10000000-0000-0000-0000-000000000001","name":"아침형","tossUserKey":null,"createdAt":"2026-09-29T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
공통 인증 사용자 UUID |
|
|
이름 |
|
|
기존 토스 사용자 키 (null 허용) |
|
|
가입 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant D as 기상 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사용자 가입
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
이름 변경
본인 이름을 변경합니다.
PATCH /api/v1/wakeup/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name은 공백만인 값을 제외하고 1~16자입니다.
PATCH /api/v1/wakeup/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 20
Host: localhost:8080
{"name":"새이름"}
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
1~16자 이름 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 118
{"id":"10000000-0000-0000-0000-000000000001","name":"새이름","tossUserKey":null,"createdAt":"2026-09-29T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
공통 인증 사용자 UUID |
|
|
이름 |
|
|
기존 토스 사용자 키 (null 허용) |
|
|
가입 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant D as 기상 클럽 DB
C->>A: PATCH 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 이름 변경
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방과 참여
참여 방 조회
본인이 참여한 방 목록을 조회합니다.
GET /api/v1/wakeup/rooms
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/wakeup/rooms HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 276
[{"id":"20000000-0000-0000-0000-000000000001","code":"ABCDEF","name":"아침방","activationTime":"06:30","activationDurationMin":10,"capacity":8,"activeWeekdays":[1,2,3,4,5],"ownerId":"10000000-0000-0000-0000-000000000001","memberCount":1,"createdAt":"2026-09-29T00:00:00Z"}]
| Path | Type | Description |
|---|---|---|
|
|
방 UUID |
|
|
참여 코드 |
|
|
방 이름 |
|
|
기상 시각 (HH:mm, Asia/Seoul) |
|
|
기상 버튼 활성 시간 (분) |
|
|
정원 |
|
|
활성 요일 (일=0 ~ 토=6) |
|
|
방장 UUID |
|
|
현재 멤버 수 |
|
|
생성 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
프로필 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 참여 방 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 생성
방과 방장 참여를 한 트랜잭션으로 생성합니다. 정원은 8명이며 사용자는 한 방에 참여합니다.
POST /api/v1/wakeup/rooms
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name 1~16자, activationTime 04:00~11:55, activeWeekdays는 일요일 0~토요일 6의 중복 없는 비어 있지 않은 배열입니다.
POST /api/v1/wakeup/rooms HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 74
Host: localhost:8080
{"name":"아침방","activeWeekdays":[1,2,3,4,5],"activationTime":"06:30"}
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
1~16자 방 이름 |
|
|
04:00~11:55 기상 시각 |
|
|
활성 요일 |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 274
{"id":"20000000-0000-0000-0000-000000000001","code":"ABCDEF","name":"아침방","activationTime":"06:30","activationDurationMin":10,"capacity":8,"activeWeekdays":[1,2,3,4,5],"ownerId":"10000000-0000-0000-0000-000000000001","memberCount":1,"createdAt":"2026-09-29T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
방 UUID |
|
|
참여 코드 |
|
|
방 이름 |
|
|
기상 시각 (HH:mm, Asia/Seoul) |
|
|
기상 버튼 활성 시간 (분) |
|
|
정원 |
|
|
활성 요일 (일=0 ~ 토=6) |
|
|
방장 UUID |
|
|
현재 멤버 수 |
|
|
생성 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
409 |
|
이미 방에 참여 중 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 생성
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
방 설정 변경
방장이 방 이름과 기상 시각·요일을 변경합니다.
PATCH /api/v1/wakeup/rooms/{roomId}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID와 방 생성과 동일한 전체 설정을 전달합니다.
PATCH /api/v1/wakeup/rooms/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 74
Host: localhost:8080
{"name":"아침방","activeWeekdays":[1,2,3,4,5],"activationTime":"06:30"}
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
| Path | Type | Description |
|---|---|---|
|
|
1~16자 방 이름 |
|
|
04:00~11:55 기상 시각 |
|
|
활성 요일 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 274
{"id":"20000000-0000-0000-0000-000000000001","code":"ABCDEF","name":"아침방","activationTime":"06:30","activationDurationMin":10,"capacity":8,"activeWeekdays":[1,2,3,4,5],"ownerId":"10000000-0000-0000-0000-000000000001","memberCount":1,"createdAt":"2026-09-29T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
방 UUID |
|
|
참여 코드 |
|
|
방 이름 |
|
|
기상 시각 (HH:mm, Asia/Seoul) |
|
|
기상 버튼 활성 시간 (분) |
|
|
정원 |
|
|
활성 요일 (일=0 ~ 토=6) |
|
|
방장 UUID |
|
|
현재 멤버 수 |
|
|
생성 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
403 |
|
방장 권한 없음 또는 방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: PATCH 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 설정 변경
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 삭제
방장이 방을 삭제합니다.
DELETE /api/v1/wakeup/rooms/{roomId}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
DELETE /api/v1/wakeup/rooms/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
방장 권한 없음 또는 방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 삭제
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
초대 코드로 방 가입
초대 코드로 참여합니다. 같은 방에 다시 가입하면 기존 방을 반환합니다.
POST /api/v1/wakeup/rooms/join
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
code는 필수이며 최대 12자입니다. 서버는 공백 제거 후 대문자로 정규화합니다.
POST /api/v1/wakeup/rooms/join HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 17
Host: localhost:8080
{"code":"ABCDEF"}
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
방 참여 코드 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 274
{"id":"20000000-0000-0000-0000-000000000001","code":"ABCDEF","name":"아침방","activationTime":"06:30","activationDurationMin":10,"capacity":8,"activeWeekdays":[1,2,3,4,5],"ownerId":"10000000-0000-0000-0000-000000000001","memberCount":1,"createdAt":"2026-09-29T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
방 UUID |
|
|
참여 코드 |
|
|
방 이름 |
|
|
기상 시각 (HH:mm, Asia/Seoul) |
|
|
기상 버튼 활성 시간 (분) |
|
|
정원 |
|
|
활성 요일 (일=0 ~ 토=6) |
|
|
방장 UUID |
|
|
현재 멤버 수 |
|
|
생성 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
404 |
|
초대 코드 또는 프로필 없음 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
다른 방에 참여 중 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
정원 초과 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 초대 코드로 방 가입
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 탈퇴
현재 방에서 탈퇴합니다. 이미 탈퇴한 요청도 성공합니다.
DELETE /api/v1/wakeup/rooms/membership
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
DELETE /api/v1/wakeup/rooms/membership HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
프로필 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 탈퇴
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
내 참여 설정 조회
현재 방의 알림·닉네임 설정을 조회합니다.
GET /api/v1/wakeup/rooms/{roomId}/membership
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
GET /api/v1/wakeup/rooms/20000000-0000-0000-0000-000000000001/membership HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 92
{"notifyEnabled":false,"notificationAgreementAt":null,"reminderOffsetMin":0,"nickname":null}
| Path | Type | Description |
|---|---|---|
|
|
알림 수신 여부 |
|
|
알림 동의 시각 (null 허용) |
|
|
기상 시각 이전 알림 분 (0~60) |
|
|
방 닉네임 (null 허용) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
해당 방의 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 내 참여 설정 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
내 참여 설정 변경
알림 동의·알림 시각·닉네임을 부분 변경합니다. 최초 알림 활성화 시 서버 시각으로 동의를 기록합니다.
PATCH /api/v1/wakeup/rooms/{roomId}/membership
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
notifyEnabled, reminderOffsetMin(0~60), nickname(1~16자)은 선택입니다. clearNickname=true는 닉네임 삭제이며 생략한 값은 유지합니다.
PATCH /api/v1/wakeup/rooms/20000000-0000-0000-0000-000000000001/membership HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 87
Host: localhost:8080
{"nickname":"방장","reminderOffsetMin":10,"clearNickname":false,"notifyEnabled":true}
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
| Path | Type | Description |
|---|---|---|
|
|
알림 수신 여부 |
|
|
기상 시각 이전 알림 분 (0~60) |
|
|
1~16자 방 닉네임 |
|
|
닉네임 삭제 여부 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 114
{"notifyEnabled":true,"notificationAgreementAt":"2026-09-29T00:00:00Z","reminderOffsetMin":10,"nickname":"방장"}
| Path | Type | Description |
|---|---|---|
|
|
알림 수신 여부 |
|
|
알림 동의 시각 (null 허용) |
|
|
기상 시각 이전 알림 분 (0~60) |
|
|
방 닉네임 (null 허용) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
403 |
|
해당 방의 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: PATCH 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 내 참여 설정 변경
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 멤버 조회
방 멤버의 닉네임 또는 사용자 이름을 조회합니다.
GET /api/v1/wakeup/rooms/{roomId}/members
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
GET /api/v1/wakeup/rooms/20000000-0000-0000-0000-000000000001/members HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 67
[{"userId":"10000000-0000-0000-0000-000000000001","name":"방장"}]
| Path | Type | Description |
|---|---|---|
|
|
멤버 UUID |
|
|
방 닉네임 또는 사용자 이름 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
해당 방의 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 멤버 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
기상 출석
기상 출석
서버의 Asia/Seoul 오늘 날짜로 출석합니다. 같은 날 재요청은 기존 출석을 반환하며 HTTP 상태는 201입니다.
POST /api/v1/wakeup/rooms/{roomId}/check-ins
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다. 클라이언트 날짜·시각을 받지 않습니다.
POST /api/v1/wakeup/rooms/20000000-0000-0000-0000-000000000001/check-ins HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 168
{"id":"b05a928a-41c0-4117-8017-cae696d7c135","userId":"10000000-0000-0000-0000-000000000001","userName":"방장","date":"2026-09-29","pressedAt":"2026-09-29T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
출석 UUID |
|
|
출석 사용자 UUID |
|
|
출석 당시 이름 |
|
|
출석 날짜 (Asia/Seoul) |
|
|
서버에서 기록한 버튼 입력 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
해당 방의 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 기상 출석
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
방 출석 조회
최근 출석을 입력 시각 내림차순으로 최대 500건 조회합니다.
GET /api/v1/wakeup/rooms/{roomId}/check-ins
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `wakeup`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
GET /api/v1/wakeup/rooms/20000000-0000-0000-0000-000000000001/check-ins HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
기상 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 170
[{"id":"31c6b4df-6e66-44ab-9644-e7669ced400b","userId":"10000000-0000-0000-0000-000000000001","userName":"방장","date":"2026-09-29","pressedAt":"2026-09-29T00:00:00Z"}]
| Path | Type | Description |
|---|---|---|
|
|
출석 UUID |
|
|
출석 사용자 UUID |
|
|
출석 당시 이름 |
|
|
출석 날짜 (Asia/Seoul) |
|
|
서버에서 기록한 버튼 입력 시각 (UTC) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
해당 방의 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 기상 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 출석 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
대표 오류 응답
아래 예제는 컨트롤러와 ControllerAdvice의 계약 테스트에서 생성합니다. 서비스 오류는 mock으로 재현하며 실제 외부 장애·보안 필터 검증을 대신하지 않습니다.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 159
{"detail":"입력값을 확인해 주세요.","instance":"/api/v1/wakeup/me","status":400,"title":"입력값을 확인해 주세요.","code":"invalid_request"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Content-Length: 148
{"detail":"가입 정보가 없어요.","instance":"/api/v1/wakeup/me","status":404,"title":"대상을 찾을 수 없습니다.","code":"not_found"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
출석 클럽
처리 흐름은 Mermaid 소스 코드로 제공합니다.
보호 API의 문서 테스트는 가짜 JWT를 주입한 standalone MockMvc 계약 테스트입니다.
보안 필터의 서명·issuer·만료·audience 검증과 DB 잠금·외부 시스템의 동작 검증은 별도 테스트의 범위입니다.
실제 로그인은 공통 인증의 일회용 코드 교환으로 수행합니다. 보호 API 요청마다 Toss 인증을 호출하지 않습니다.
보안 필터와 업무 오류는 공통 ProblemDetail 형식을 사용합니다. 인증 실패는 401/not_authenticated, 공통 권한 거절은 `403/forbidden`입니다. 식단 클럽의 기존 컨트롤러 권한 거절 코드 `diet_token_required`는 유지합니다. 자세한 계약은 공통 오류 응답을 참고합니다.
`ATTENDANCE_ENABLED=true`이고 전용 DB·저장소 설정이 준비된 서버에서 보호 API를 제공합니다. 문서의 구현 계약은 운영 전환 완료 여부와 별개입니다.
이미지 비교
출석 사진 비교
입실 사진과 퇴실 사진의 전체 색 분포를 비교합니다. 객체가 동일하다는 증명이나 출석 확정 결과가 아니며, 사진과 출석 기록을 저장하지 않습니다. 방과 입실·퇴실 기록은 아래 사용자·방·출석 기록 API에서 처리합니다.
POST /api/v1/attendance/images/compare
공개 API이며 Authorization 헤더 없이 호출할 수 있습니다.
`reference`는 입실 사진, `candidate`는 퇴실 사진입니다. 파일 파트는 이 두 이름으로 각각 정확히 하나씩 보내며, 다른 파일 파트나 중복 파일은 허용하지 않습니다. 파일명·Content-Type만으로 형식을 판단하지 않고 실제 JPEG 바이트와 디코딩 가능 여부를 검증합니다.
| 제약 | 기준 |
|---|---|
파일 크기 |
파일당 최대 8 MiB (8 × 1024 × 1024 바이트) |
전체 multipart 요청 |
최대 17 MiB (multipart 부가 데이터 포함, 기본 설정) |
픽셀 수 |
이미지당 최대 4,000,000 픽셀, 디코딩 전에 검사 |
요청 빈도 |
서버의 ImageService 인스턴스당 1분 고정 구간 최대 120회 |
동시 비교 |
ImageService 인스턴스당 최대 4개, 대기 없이 초과 요청 거절 |
요청 제한은 사용자별 한도가 아닙니다. 여러 서버 인스턴스가 공유하는 전역 한도도 아닙니다. 빈도 검사 후 동시 실행 한도를 검사하므로 동시 실행 초과 요청도 빈도에 포함됩니다.
POST /api/v1/attendance/images/compare HTTP/1.1
Content-Type: multipart/form-data;charset=ISO-8859-1; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: localhost:8080
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=reference; filename=check-in.jpg
Content-Type: image/jpeg
���� JFIF �� C
$.' ",#(7),01444'9=82<.342�� C
2!!22222222222222222222222222222222222222222222222222�� � �" ��
�� � } !1AQa"q2���#B��R��$3br�
%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz���������������������������������������������������������������������������
�� � w !1AQaq"2�B���� #3R�br�
$4�%�&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz�������������������������������������������������������������������������� ? ��(��
(��
(��
(��
(��
(��
(��
(��
(��
(��
+/\������nV1����JF8E�y�<�s^!⏈�Lj��F��e
m�~[���,Oc���=|L)o�c��2LN`�
!�����]�իx�A�ئ��A��Z%%�RFFQr�c��z���rx{�|�O��� ^Ey���o�V>�� `�����߇�{��.OϞ�� ~�� ��OI���U�f�f %�����G$��~|����O[T�<�h�'���K��ȲE"�GC�`y�S���#]�4�>�{-���
r��r�8��5�^��c�?�K���6�V�䜜�������0O8��Gg�>_3�F.�7�-ת� /���(����(��(���A�Z�wE��n�@�H�6ld�ڃ���p2zZ����_7��D�C"���4V�@��� ��G� ��5��/��2L���G�-_�o���[��C�I�j��
8Xײ�����I��(� �����:q�+%�
(��aEPEP��3��-��
��<��=��V\u�H�}�R������w�<,����rE})�]z?xv�QR�V]��� �����2s�z�0X�u�-���eS�4U�-�g�O��l�E�|�QE���Y�?
�:�Yb���T1Y�C��0'�־e�p��� "��������>�||�������F9U�'�m���EW �AEPEPEP^��cVa6��9b�E�@(ڤa_'�NS������߆�P���k� ����IƬZ<��ke�c.���_���(�|��(�� �m�z� s���O���Mx�}�3ImW�7F0�-��U`���`��r���^6>-U�s������OT���Q\G�Q@Q@Q@u�� �i��� E=rU�����T���!$2��pT:��y���t�X۹�f�#OY��Z���s��+��(�Ks�����U��U���Q_0k�D��y��w=��Cp7��[ �eH8����������H��}iơeUL�өNs���H�9x��.�G���g!Ө�����?���x%Q^)�pQE QE QE W�|/��H��w"����A!F�`$����y�^s��������>�E,���P��c���r=�<�G�>��8��Tߜ�E���EW�|8QE QE�>7�g�4�����)i-��\?�9�X��N3�I�[�+����� ���
2�ddzk���+��������v��|��\a�a�����F M�CF}VQ��0�Q���[>�����|�Ez���b@��mQYKEx�*1�ޠ������<��+?� �#� &b� ��Ζ�]�O��������z�~v9*+�� �g�� ���_�]i�?���
����3 d�8 )�Fx��픰�[�+4���)Ǚ֏ɧ�+����w�{�� ��l4�4<������~�#��yǣh�=�2�qj7FM�`��Bc9�۱��Z���>���>+N.� ���_���,-t�l��X-�]�����I�QEzi[D|D��ܤ��QE(�� (�� (�� (�� (�� (�� (�� (�� ��
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=candidate; filename=check-out.jpg
Content-Type: image/jpeg
���� JFIF �� C
$.' ",#(7),01444'9=82<.342�� C
2!!22222222222222222222222222222222222222222222222222�� � �" ��
�� � } !1AQa"q2���#B��R��$3br�
%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz���������������������������������������������������������������������������
�� � w !1AQaq"2�B���� #3R�br�
$4�%�&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz�������������������������������������������������������������������������� ? ��(��
(��
(��
(��
(��
(��
(��
(��
(��
(��
+/\������nV1����JF8E�y�<�s^!⏈�Lj��F��e
m�~[���,Oc���=|L)o�c��2LN`�
!�����]�իx�A�ئ��A��Z%%�RFFQr�c��z���rx{�|�O��� ^Ey���o�V>�� `�����߇�{��.OϞ�� ~�� ��OI���U�f�f %�����G$��~|����O[T�<�h�'���K��ȲE"�GC�`y�S���#]�4�>�{-���
r��r�8��5�^��c�?�K���6�V�䜜�������0O8��Gg�>_3�F.�7�-ת� /���(����(��(���A�Z�wE��n�@�H�6ld�ڃ���p2zZ����_7��D�C"���4V�@��� ��G� ��5��/��2L���G�-_�o���[��C�I�j��
8Xײ�����I��(� �����:q�+%�
(��aEPEP��3��-��
��<��=��V\u�H�}�R������w�<,����rE})�]z?xv�QR�V]��� �����2s�z�0X�u�-���eS�4U�-�g�O��l�E�|�QE���Y�?
�:�Yb���T1Y�C��0'�־e�p��� "��������>�||�������F9U�'�m���EW �AEPEPEP^��cVa6��9b�E�@(ڤa_'�NS������߆�P���k� ����IƬZ<��ke�c.���_���(�|��(�� �m�z� s���O���Mx�}�3ImW�7F0�-��U`���`��r���^6>-U�s������OT���Q\G�Q@Q@Q@u�� �i��� E=rU�����T���!$2��pT:��y���t�X۹�f�#OY��Z���s��+��(�Ks�����U��U���Q_0k�D��y��w=��Cp7��[ �eH8����������H��}iơeUL�өNs���H�9x��.�G���g!Ө�����?���x%Q^)�pQE QE QE W�|/��H��w"����A!F�`$����y�^s��������>�E,���P��c���r=�<�G�>��8��Tߜ�E���EW�|8QE QE�>7�g�4�����)i-��\?�9�X��N3�I�[�+����� ���
2�ddzk���+��������v��|��\a�a�����F M�CF}VQ��0�Q���[>�����|�Ez���b@��mQYKEx�*1�ޠ������<��+?� �#� &b� ��Ζ�]�O��������z�~v9*+�� �g�� ���_�]i�?���
����3 d�8 )�Fx��픰�[�+4���)Ǚ֏ɧ�+����w�{�� ��l4�4<������~�#��yǣh�=�2�qj7FM�`��Bc9�۱��Z���>���>+N.� ���_���,-t�l��X-�]�����I�QEzi[D|D��ܤ��QE(�� (�� (�� (�� (�� (�� (�� (�� ��
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
| Part | Description |
|---|---|
|
입실 JPEG 사진, 최대 8 MiB·4,000,000 픽셀, 정확히 하나 |
|
퇴실 JPEG 사진, 최대 8 MiB·4,000,000 픽셀, 정확히 하나 |
HTTP 200. JSON 객체를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 38
{"verdict":"MATCH","reason":"similar"}
| Path | Type | Description |
|---|---|---|
|
|
색 분포 판정: MATCH, NON_MATCH, UNDECIDABLE |
|
|
판정 사유: similar, different, uncertain |
| verdict | reason | 클라이언트 처리 |
|---|---|---|
MATCH |
similar |
색 분포가 유사합니다. 출석 처리에는 별도 업무 규칙을 적용합니다. |
NON_MATCH |
different |
색 분포가 다릅니다. 사진과 촬영 환경을 확인하도록 안내합니다. |
UNDECIDABLE |
uncertain |
판정이 애매합니다. 확정 성공으로 처리하지 않고 확인을 안내합니다. |
세 판정 모두 비교가 완료된 정상 200 응답입니다.
HSV 유사도 점수는 공개 응답에 포함하지 않으며 객체 동일성·확률로 해석하지 않습니다.
배경과 조명에 영향을 받고 서로 다른 객체도 비슷한 색 분포를 가지면 MATCH가 될 수 있습니다.
업무 오류는 application/problem+json`의 ProblemDetail로 반환합니다.
클라이언트는 `code`로 분기하고 `detail 문구를 비교하지 않습니다.
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
missing_image |
파일 파트 누락·중복·추가 |
두 파일 파트를 정확히 구성합니다. |
413 |
image_too_large |
파일·요청 크기 또는 픽셀 수 초과 |
사진을 축소합니다. |
415 |
unsupported_image_type |
JPEG 형식 미지원 |
JPEG로 변환합니다. |
422 |
invalid_image |
빈 파일 또는 디코딩 불가 |
정상 사진을 다시 선택합니다. |
429 |
rate_limited |
요청 빈도 또는 동시 비교 한도 초과 |
지연 후 제한된 횟수로 재시도합니다. |
503 |
comparison_unavailable |
비교 계산 중 장애 |
잠시 후 제한된 횟수로 재시도합니다. |
`Retry-After`는 현재 제공하지 않습니다. 아래 예제는 필수 파일 누락에 대한 실제 테스트 응답입니다.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 199
{"detail":"두 이미지 파일을 각각 한 번씩 보내 주세요.","instance":"/api/v1/attendance/images/compare","status":400,"title":"입력값을 확인해 주세요.","code":"missing_image"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI. 기본 유형일 때 생략될 수 있음 |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
오류 설명. 분기 조건으로 사용하지 않음 |
|
|
오류가 발생한 요청 경로 |
|
|
클라이언트 분기용 오류 코드: missing_image |
sequenceDiagram
participant C as 클라이언트
participant A as 공개 이미지 API
participant I as ImageService
C->>A: JPEG 두 장 비교 요청
A->>I: 파트 검증 후 비교
I->>I: 빈도·동시 실행·JPEG·픽셀 검증
I->>I: HSV 색 분포 비교
I-->>A: 판정 결과
A-->>C: verdict와 reason
이 API는 JWT·DB·Toss를 호출하지 않습니다. 위 Mermaid는 소스 코드로 제공합니다.
사용자
사용자 조회
사용자를 조회하고 첫 요청이면 Auth 사용자 ID로 프로필을 생성합니다.
GET /api/v1/attendance/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/attendance/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 102
{"id":"10000000-0000-0000-0000-000000000001","name":"출석한량","createdAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
이름 |
|
|
생성 시각 (UTC ISO 8601) |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant I as Auth 공개 API
participant D as 출석 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사용자 조회
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 프로필 조회·없으면 생성
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
이름 변경
본인 이름을 변경합니다.
PATCH /api/v1/attendance/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name은 공백만인 값을 제외하고 1~16자입니다.
PATCH /api/v1/attendance/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 20
Host: localhost:8080
{"name":"새이름"}
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
이름, 공백만인 값 제외, 1~16자 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 99
{"id":"10000000-0000-0000-0000-000000000001","name":"새이름","createdAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
이름 |
|
|
생성 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant I as Auth 공개 API
participant D as 출석 클럽 DB
C->>A: PATCH 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 이름 변경
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방
내 방 조회
내 참여 방을 조회합니다. 참여한 방이 없으면 빈 본문으로 200을 반환합니다.
GET /api/v1/attendance/me/room
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/attendance/me/room HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 177
{"id":"20000000-0000-0000-0000-000000000001","code":"ABCDEF","name":"출석방","capacity":20,"hostId":"10000000-0000-0000-0000-000000000001","createdAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
초대 코드 |
|
|
방 이름 |
|
|
방 정원 (명) |
|
|
방장 UUID |
|
|
생성 시각 (UTC ISO 8601) |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 출석 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 내 방 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 생성
정원 20명의 방과 방장 가입을 한 트랜잭션으로 저장합니다. 한 사용자는 한 방에 참여합니다.
POST /api/v1/attendance/rooms
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name은 공백만인 값을 제외하고 1~16자입니다.
POST /api/v1/attendance/rooms HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 20
Host: localhost:8080
{"name":"출석방"}
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
이름, 공백만인 값 제외, 1~16자 |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 177
{"id":"20000000-0000-0000-0000-000000000001","code":"ABCDEF","name":"출석방","capacity":20,"hostId":"10000000-0000-0000-0000-000000000001","createdAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
초대 코드 |
|
|
방 이름 |
|
|
방 정원 (명) |
|
|
방장 UUID |
|
|
생성 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
409 |
|
이미 방에 참여 중 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
프로필 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 출석 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 생성
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
초대 코드 미리보기
방 정보를 조회합니다. 코드에 해당하는 방이 없으면 빈 본문으로 200을 반환합니다.
GET /api/v1/attendance/rooms/preview
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query code에 초대 코드를 전달합니다.
GET /api/v1/attendance/rooms/preview?code=ABCDEF HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
초대 코드 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 127
{"id":"20000000-0000-0000-0000-000000000001","name":"출석방","memberCount":1,"hostName":"출석한량","alreadyMember":true}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
방 이름 |
|
|
현재 멤버 수 |
|
|
방장 이름 |
|
|
현재 참여 여부 |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 출석 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 초대 코드 미리보기
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 멤버 조회
현재 방 멤버를 가입 순서로 조회합니다.
GET /api/v1/attendance/rooms/{room}/members
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
GET /api/v1/attendance/rooms/20000000-0000-0000-0000-000000000001/members HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 107
[{"userId":"10000000-0000-0000-0000-000000000001","name":"출석한량","joinedAt":"2026-10-01T00:00:00Z"}]
| Path | Type | Description |
|---|---|---|
|
|
멤버 UUID |
|
|
이름 |
|
|
가입 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
방 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
404 |
|
방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 출석 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 멤버 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 가입
현재 사용자를 방에 참여시킵니다.
POST /api/v1/attendance/rooms/{room}/membership
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
POST /api/v1/attendance/rooms/20000000-0000-0000-0000-000000000001/membership HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
409 |
|
이미 방에 참여 중 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
프로필 없음 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
정원 초과 |
조건을 확인한 뒤 다시 요청합니다. |
404 |
|
방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 출석 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 가입
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
방 탈퇴
본인 참여와 본인 출석을 삭제합니다. 방장은 가장 먼저 가입한 남은 멤버에게 인계하며 마지막 멤버가 나가면 방을 삭제합니다. 사진은 영속 큐에서 삭제합니다.
DELETE /api/v1/attendance/me/membership
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
DELETE /api/v1/attendance/me/membership HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant D as 출석 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 탈퇴
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
출석 기록과 사진
입실·퇴실 기록
서울 오늘 날짜와 서버 Instant로 입실·퇴실을 저장합니다. 둘 중 하나만 있어도 기록을 유지합니다. 실패한 퇴실은 재시도할 수 있습니다. 사진 쌍이 있으면 위치 200 m와 HSV 색 분포를 비교하고 판정을 같은 트랜잭션에서 저장합니다. location_far, photo_mismatch, photo_uncertain은 정상 응답의 verifyReason입니다. 비교 장애는 comparison_unavailable로 저장하며 HSV는 객체 동일성·확률이 아닙니다.
POST /api/v1/attendance/sessions
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
kind는 in/out, photoPath는 실제 존재하는 본인 사진 경로입니다. latitude -90~90, longitude -180~180, accuracy 0 이상 (m), placeName 선택·최대 24자입니다.
POST /api/v1/attendance/sessions HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 176
Host: localhost:8080
{"kind":"in","photoPath":"20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/in.jpg","accuracy":5,"longitude":127.0,"placeName":"자리","latitude":37.5}
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
입실 in 또는 퇴실 out |
|
|
현재 방의 본인 사진 경로, 최대 256자 |
|
|
위도, -90~90도 |
|
|
경도, -180~180도 |
|
|
위치 정확도, 0 이상 (m) |
|
|
장소 이름, 최대 24자 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 500
{"id":"10000000-0000-0000-0000-000000000001","roomId":"20000000-0000-0000-0000-000000000001","userId":"10000000-0000-0000-0000-000000000001","date":"2026-10-01","placeName":"자리","checkIn":{"photoPath":"20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/in.jpg","at":"2026-10-01T00:00:00Z","latitude":37.5,"longitude":127.0,"accuracy":5.0},"checkOut":null,"verified":false,"verifyReason":null,"locationDistanceM":null,"photoDistance":null,"updatedAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
방 UUID |
|
|
사용자 UUID |
|
|
출석 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
장소 이름 |
|
|
입실 또는 퇴실 기록, null 허용 |
|
|
사진 경로 |
|
|
기록 시각 (UTC ISO 8601) |
|
|
위도 (도) |
|
|
경도 (도) |
|
|
위치 정확도 (m) |
|
|
입실 또는 퇴실 기록, null 허용 |
|
|
사진 경로 |
|
|
기록 시각 (UTC ISO 8601) |
|
|
위도 (도) |
|
|
경도 (도) |
|
|
위치 정확도 (m) |
|
|
출석 인증 성공 여부 |
|
|
판정 사유, null 허용 |
|
|
사진 위치 거리 (m), null 허용 |
|
|
내부 사진 거리 값, 확률이 아님, null 허용 |
|
|
갱신 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
409 |
|
중복 입실 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
성공 퇴실 또는 퇴실 단독 기록 중복 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
참여 방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
429 |
|
비교 실행 제한 초과, 트랜잭션 롤백 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as SessionService
participant D as 출석 클럽 DB
participant X as S3
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 입실·퇴실 기록
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S->>X: 사진 존재 확인·판정용 사진 읽기
X-->>S: 사진 바이트
S->>S: 위치·HSV 판정
S->>D: 판정과 출석 확정
S-->>A: 업무 결과
A-->>C: 200 응답
방 출석 조회
방 출석을 날짜 내림차순으로 조회합니다. userId로 방 내 특정 사용자 기록을 필터링합니다.
GET /api/v1/attendance/rooms/{room}/sessions
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID, 선택 query from/to(서울 YYYY-MM-DD, 기본 오늘부터 120일 전~오늘, 최대 366일), userId(UUID)입니다.
GET /api/v1/attendance/rooms/20000000-0000-0000-0000-000000000001/sessions?from=2026-10-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
| Parameter | Description |
|---|---|
|
시작 날짜 (YYYY-MM-DD), 기본 최근 120일 |
|
종료 날짜 (YYYY-MM-DD), 기본 오늘, 최대 366일 |
|
방 내 사용자 UUID 필터 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 502
[{"id":"10000000-0000-0000-0000-000000000001","roomId":"20000000-0000-0000-0000-000000000001","userId":"10000000-0000-0000-0000-000000000001","date":"2026-10-01","placeName":"자리","checkIn":{"photoPath":"20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/in.jpg","at":"2026-10-01T00:00:00Z","latitude":37.5,"longitude":127.0,"accuracy":5.0},"checkOut":null,"verified":false,"verifyReason":null,"locationDistanceM":null,"photoDistance":null,"updatedAt":"2026-10-01T00:00:00Z"}]
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
방 UUID |
|
|
사용자 UUID |
|
|
출석 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
장소 이름 |
|
|
입실 또는 퇴실 기록, null 허용 |
|
|
사진 경로 |
|
|
기록 시각 (UTC ISO 8601) |
|
|
위도 (도) |
|
|
경도 (도) |
|
|
위치 정확도 (m) |
|
|
입실 또는 퇴실 기록, null 허용 |
|
|
사진 경로 |
|
|
기록 시각 (UTC ISO 8601) |
|
|
위도 (도) |
|
|
경도 (도) |
|
|
위치 정확도 (m) |
|
|
출석 인증 성공 여부 |
|
|
판정 사유, null 허용 |
|
|
사진 위치 거리 (m), null 허용 |
|
|
내부 사진 거리 값, 확률이 아님, null 허용 |
|
|
갱신 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
조회 기간 역전 또는 초과 |
조건을 확인한 뒤 다시 요청합니다. |
403 |
|
방 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as SessionService
participant D as 출석 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 출석 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
출석 삭제
본인 출석을 삭제하고 연결 사진을 삭제 대기열에 저장합니다.
DELETE /api/v1/attendance/sessions/{id}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
출석 UUID를 전달합니다. 본문이 없습니다.
DELETE /api/v1/attendance/sessions/10000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
출석 UUID |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
타인 기록 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as SessionService
participant D as 출석 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 출석 삭제
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
사진 업로드
현재 방의 본인 사진을 S3에 업로드하고 경로를 반환합니다.
POST /api/v1/attendance/rooms/{room}/photos
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID, query kind(in/out), image/jpeg 원시 바이트 최대 8 MiB입니다.
POST /api/v1/attendance/rooms/20000000-0000-0000-0000-000000000001/photos?kind=in HTTP/1.1
Content-Type: image/jpeg;charset=ISO-8859-1
Authorization: Bearer documented-token
Content-Length: 3
Host: localhost:8080
ÿØÿ
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
| Parameter | Description |
|---|---|
|
입실 in 또는 퇴실 out |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 91
{"path":"20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/in.jpg"}
| Path | Type | Description |
|---|---|---|
|
|
사진 저장 경로 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
in/out이 아닌 kind |
조건을 확인한 뒤 다시 요청합니다. |
413 |
|
8 MiB 초과 |
조건을 확인한 뒤 다시 요청합니다. |
429 |
|
동시 업로드 초과 |
조건을 확인한 뒤 다시 요청합니다. |
503 |
|
S3 장애 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as SessionService
participant D as 출석 클럽 DB
participant X as S3
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사진 업로드
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S->>X: JPEG 검증 후 사진 저장
X-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
사진 읽기 URL 발급
출석에 연결된 사진과 방 멤버십을 검증해 600초 서명 URL을 반환합니다.
GET /api/v1/attendance/photos/url
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query path에 사진 경로를 전달합니다.
GET /api/v1/attendance/photos/url?path=20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/in.jpg HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
사진 저장 경로 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 65
{"url":"https://photos.example.com/signed-photo","expiresIn":600}
| Path | Type | Description |
|---|---|---|
|
|
서명된 사진 URL |
|
|
URL 유효기간 (초) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
기록에 연결된 사진 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as SessionService
participant D as 출석 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사진 읽기 URL 발급
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S->>S: S3Presigner로 읽기 URL 서명
S-->>A: 업무 결과
A-->>C: 200 응답
미사용 사진 삭제
미사용 본인 사진을 삭제 대기열에 저장합니다. 실제 S3 삭제는 스케줄러가 재시도합니다.
DELETE /api/v1/attendance/photos
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `attendance`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query path에 본인 사진 경로를 전달합니다.
DELETE /api/v1/attendance/photos?path=20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/in.jpg HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
출석 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
미사용 본인 사진 경로 |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
타인 사진 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
기록에서 사용 중인 사진 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as SessionService
participant D as 출석 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 미사용 사진 삭제
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
대표 오류 응답
아래 예제는 컨트롤러와 ControllerAdvice의 계약 테스트에서 생성합니다. 서비스 오류는 mock으로 재현하며 실제 외부 장애·보안 필터 검증을 대신하지 않습니다.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 163
{"detail":"입력값을 확인해 주세요.","instance":"/api/v1/attendance/me","status":400,"title":"입력값을 확인해 주세요.","code":"invalid_request"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Length: 220
{"detail":"현재 상태에서는 요청을 처리할 수 없습니다.","instance":"/api/v1/attendance/rooms","status":409,"title":"현재 상태에서는 요청을 처리할 수 없습니다.","code":"already_in_room"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 169
{"detail":"입력값을 확인해 주세요.","instance":"/api/v1/attendance/sessions","status":400,"title":"입력값을 확인해 주세요.","code":"invalid_request"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
식단 클럽
처리 흐름은 Mermaid 소스 코드로 제공합니다.
보호 API의 문서 테스트는 가짜 JWT를 주입한 standalone MockMvc 계약 테스트입니다.
보안 필터의 서명·issuer·만료·audience 검증과 DB 잠금·외부 시스템의 동작 검증은 별도 테스트의 범위입니다.
실제 로그인은 공통 인증의 일회용 코드 교환으로 수행합니다. 보호 API 요청마다 Toss 인증을 호출하지 않습니다.
보안 필터와 업무 오류는 공통 ProblemDetail 형식을 사용합니다. 인증 실패는 401/not_authenticated, 공통 권한 거절은 `403/forbidden`입니다. 식단 클럽의 기존 컨트롤러 권한 거절 코드 `diet_token_required`는 유지합니다. 자세한 계약은 공통 오류 응답을 참고합니다.
공통 업무 규칙
식단 클럽은 개인 식단·사진·AI 분석·끼니 알림을 관리합니다. 결제·구독 API는 제공하지 않습니다. 식단 DB·트랜잭션·Flyway 이력은 다른 클럽과 분리합니다. 사진은 영속 디스크에 보관하고 식단 삭제만으로 제거하지 않습니다. AI 분석에서 음식 없음·모델 거절은 사용량을 유지하고 외부 호출 실패는 예약했던 서울 날짜의 사용량을 환급합니다. 알림 스케줄러는 5분마다 지난 15분 이내의 동의한 설정을 확인하고, 이미 기록한 끼니는 제외합니다. 사용자·서울 날짜·끼니의 유일성 제약으로 발송 전에 확보합니다. Auth 공개 API에서 클럽 범위 익명 키를 조회하고 Toss 공개 모듈로 메시지를 발송합니다. 실패한 발송은 재확보하지 않아 응답 유실로 인한 중복 알림을 방지합니다. API에서 알림 설정을 저장하는 요청은 Toss를 직접 호출하지 않습니다.
사용자
사용자 조회
프로필을 조회하고 없으면 Auth 사용자 ID로 생성합니다.
GET /api/v1/diet/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/diet/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 85
{"id":"10000000-0000-0000-0000-000000000001","name":"식단친구","targetKcal":null}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
이름 |
|
|
목표 칼로리, 500~10000 kcal, null이면 해제 |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant D as 식단 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사용자 조회
S->>D: 프로필 조회·없으면 생성
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
프로필 변경
이름 또는 목표 칼로리를 변경합니다. 이름을 지정한 요청은 이름만 변경합니다.
PATCH /api/v1/diet/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name은 공백 제거 후 1~16자입니다. 목표 변경 시 name을 생략하고 targetKcal 500~10000 또는 null(해제)을 전달합니다.
PATCH /api/v1/diet/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 20
Host: localhost:8080
{"name":"식단왕"}
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
이름, 1~16자, 지정하면 이름만 변경 |
|
|
목표 칼로리, 500~10000 kcal, null이면 해제 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 82
{"id":"10000000-0000-0000-0000-000000000001","name":"식단왕","targetKcal":2000}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
이름 |
|
|
목표 칼로리, 500~10000 kcal, null이면 해제 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant D as 식단 클럽 DB
C->>A: PATCH 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 프로필 변경
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
식단과 최근 음식
기간별 식단 조회
본인 식단을 기간별로 조회합니다.
GET /api/v1/diet/meals
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query from/to(YYYY-MM-DD)는 필수이며 최대 366일 구간입니다.
GET /api/v1/diet/meals?from=2026-10-01&to=2026-10-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
시작 날짜 (YYYY-MM-DD) |
|
종료 날짜 (YYYY-MM-DD), 최대 366일 구간 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 338
[{"id":"20000000-0000-0000-0000-000000000001","date":"2026-10-01","mealType":"lunch","source":"manual","photoPath":null,"memo":null,"createdAt":"2026-10-01T00:00:00Z","items":[{"id":"10000000-0000-0000-0000-000000000001","name":"밥","amount":"1공기","kcal":300,"carbG":null,"proteinG":null,"fatG":null,"fromAi":false,"edited":false}]}]
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
식단 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
끼니: breakfast, lunch, dinner, snack |
|
|
입력 출처: ai, manual, copy |
|
|
본인이 업로드한 사진 UUID, null 허용 |
|
|
메모, 최대 200자, null 허용 |
|
|
생성 시각 (UTC ISO 8601) |
|
|
음식 항목 배열 (1~20개) |
|
|
식별자 UUID |
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
AI 분석 항목 여부 |
|
|
사용자 수정 여부 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
잘못된 조회 기간 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as MealService
participant D as 식단 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 기간별 식단 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
식단 조회
본인 식단과 항목을 조회합니다.
GET /api/v1/diet/meals/{id}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
식단 UUID를 전달합니다. 본문이 없습니다.
GET /api/v1/diet/meals/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
식단 UUID |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 336
{"id":"20000000-0000-0000-0000-000000000001","date":"2026-10-01","mealType":"lunch","source":"manual","photoPath":null,"memo":null,"createdAt":"2026-10-01T00:00:00Z","items":[{"id":"10000000-0000-0000-0000-000000000001","name":"밥","amount":"1공기","kcal":300,"carbG":null,"proteinG":null,"fatG":null,"fromAi":false,"edited":false}]}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
식단 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
끼니: breakfast, lunch, dinner, snack |
|
|
입력 출처: ai, manual, copy |
|
|
본인이 업로드한 사진 UUID, null 허용 |
|
|
메모, 최대 200자, null 허용 |
|
|
생성 시각 (UTC ISO 8601) |
|
|
음식 항목 배열 (1~20개) |
|
|
식별자 UUID |
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
AI 분석 항목 여부 |
|
|
사용자 수정 여부 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
없거나 타인 소유 식단 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as MealService
participant D as 식단 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 식단 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
식단 생성
식단과 음식 항목을 한 트랜잭션으로 저장합니다.
POST /api/v1/diet/meals
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
date는 서울 오늘부터 7일 전까지, mealType은 breakfast/lunch/dinner/snack, source는 ai/manual/copy입니다. items 1~20개, 이름 1~40자, amount 최대 20자, kcal 0~5000, 영양소 0~99999.9 g, memo 최대 200자입니다. photoPath는 본인 사진 UUID 또는 null입니다.
POST /api/v1/diet/meals HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 143
Host: localhost:8080
{"date":"2026-10-01","mealType":"lunch","source":"manual","items":[{"edited":false,"name":"밥","amount":"1공기","kcal":300,"fromAi":false}]}
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
식단 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
끼니: breakfast, lunch, dinner, snack |
|
|
입력 출처: ai, manual, copy |
|
|
본인이 업로드한 사진 UUID, null 허용 |
|
|
메모, 최대 200자, null 허용 |
|
|
음식 항목 배열 (1~20개) |
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
AI 분석 항목 여부 |
|
|
사용자 수정 여부 |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 336
{"id":"20000000-0000-0000-0000-000000000001","date":"2026-10-01","mealType":"lunch","source":"manual","photoPath":null,"memo":null,"createdAt":"2026-10-01T00:00:00Z","items":[{"id":"10000000-0000-0000-0000-000000000001","name":"밥","amount":"1공기","kcal":300,"carbG":null,"proteinG":null,"fatG":null,"fromAi":false,"edited":false}]}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
식단 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
끼니: breakfast, lunch, dinner, snack |
|
|
입력 출처: ai, manual, copy |
|
|
본인이 업로드한 사진 UUID, null 허용 |
|
|
메모, 최대 200자, null 허용 |
|
|
생성 시각 (UTC ISO 8601) |
|
|
음식 항목 배열 (1~20개) |
|
|
식별자 UUID |
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
AI 분석 항목 여부 |
|
|
사용자 수정 여부 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
400 |
|
미래 날짜 |
조건을 확인한 뒤 다시 요청합니다. |
400 |
|
7일보다 오래된 날짜 |
조건을 확인한 뒤 다시 요청합니다. |
400 |
|
본인 사진 아님 또는 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as MealService
participant D as 식단 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 식단 생성
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
식단 교체
본인 식단과 전체 음식 항목을 교체합니다.
PUT /api/v1/diet/meals/{id}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
date는 서울 오늘부터 7일 전까지, mealType은 breakfast/lunch/dinner/snack, source는 ai/manual/copy입니다. items 1~20개, 이름 1~40자, amount 최대 20자, kcal 0~5000, 영양소 0~99999.9 g, memo 최대 200자입니다. photoPath는 본인 사진 UUID 또는 null입니다.
PUT /api/v1/diet/meals/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 143
Host: localhost:8080
{"date":"2026-10-01","mealType":"lunch","source":"manual","items":[{"edited":false,"name":"밥","amount":"1공기","kcal":300,"fromAi":false}]}
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
식단 UUID |
| Path | Type | Description |
|---|---|---|
|
|
식단 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
끼니: breakfast, lunch, dinner, snack |
|
|
입력 출처: ai, manual, copy |
|
|
본인이 업로드한 사진 UUID, null 허용 |
|
|
메모, 최대 200자, null 허용 |
|
|
음식 항목 배열 (1~20개) |
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
AI 분석 항목 여부 |
|
|
사용자 수정 여부 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 336
{"id":"20000000-0000-0000-0000-000000000001","date":"2026-10-01","mealType":"lunch","source":"manual","photoPath":null,"memo":null,"createdAt":"2026-10-01T00:00:00Z","items":[{"id":"10000000-0000-0000-0000-000000000001","name":"밥","amount":"1공기","kcal":300,"carbG":null,"proteinG":null,"fatG":null,"fromAi":false,"edited":false}]}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
식단 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
끼니: breakfast, lunch, dinner, snack |
|
|
입력 출처: ai, manual, copy |
|
|
본인이 업로드한 사진 UUID, null 허용 |
|
|
메모, 최대 200자, null 허용 |
|
|
생성 시각 (UTC ISO 8601) |
|
|
음식 항목 배열 (1~20개) |
|
|
식별자 UUID |
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
AI 분석 항목 여부 |
|
|
사용자 수정 여부 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
404 |
|
없거나 타인 소유 식단 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as MealService
participant D as 식단 클럽 DB
C->>A: PUT 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 식단 교체
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
식단 삭제
본인 식단과 항목을 삭제합니다. 사진 원본은 자동 삭제하지 않습니다.
DELETE /api/v1/diet/meals/{id}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
식단 UUID를 전달합니다. 본문이 없습니다.
DELETE /api/v1/diet/meals/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
식단 UUID |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as MealService
participant D as 식단 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 식단 삭제
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
최근 음식 조회
최근 60일 음식 이름을 소문자로 정규화해 빈도·최근순으로 조회합니다.
GET /api/v1/diet/recent-foods
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query limit는 선택이며 1~100, 기본 40입니다.
GET /api/v1/diet/recent-foods?limit=40 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
최대 항목 수, 1~100, 기본값 40 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 97
[{"name":"밥","amount":"1공기","kcal":300,"carbG":null,"proteinG":null,"fatG":null,"times":3}]
| Path | Type | Description |
|---|---|---|
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
최근 60일 기록 횟수 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
limit 범위 초과 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as MealService
participant D as 식단 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 최근 음식 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
비공개 사진
비공개 사진 업로드
본인 JPEG 사진을 영속 디스크에 저장하고 UUID 경로를 반환합니다.
POST /api/v1/diet/photos
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
multipart file은 JPEG, 최대 8 MiB·1600만 픽셀입니다.
POST /api/v1/diet/photos HTTP/1.1
Content-Type: multipart/form-data;charset=ISO-8859-1; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Authorization: Bearer documented-token
Host: localhost:8080
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=meal.jpg
Content-Type: image/jpeg
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Part | Description |
|---|---|
|
JPEG 사진, 최대 8 MiB·1600만 픽셀 |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 47
{"path":"20000000-0000-0000-0000-000000000001"}
| Path | Type | Description |
|---|---|---|
|
|
사진 UUID |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
JPEG 헤더 형식 아님 |
조건을 확인한 뒤 다시 요청합니다. |
400 |
|
이미지 검증 실패 |
조건을 확인한 뒤 다시 요청합니다. |
413 |
|
파일 크기 초과 |
조건을 확인한 뒤 다시 요청합니다. |
503 |
|
사진 저장 장애 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as PhotoService
participant D as 식단 클럽 DB
participant X as 영속 사진 디스크
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 비공개 사진 업로드
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S->>X: JPEG 검증 후 본인 사진 저장
X-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
비공개 사진 조회
본인 사진 바이트를 반환합니다.
GET /api/v1/diet/photos/{id}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
사진 UUID를 전달합니다. 본문이 없습니다.
GET /api/v1/diet/photos/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
사진 UUID |
HTTP 200. image/jpeg 바이트와 Cache-Control: no-store를 반환합니다.
HTTP/1.1 200 OK
Content-Type: image/jpeg
Cache-Control: no-store
Content-Length: 3
| Name | Description |
|---|---|
|
image/jpeg |
|
no-store |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
없거나 타인 소유 사진 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as PhotoService
participant D as 식단 클럽 DB
participant X as 영속 사진 디스크
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 비공개 사진 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S->>X: 본인 사진 읽기
X-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
AI 분석
AI 사용량 조회
서울 오늘 사용량과 일일 5회 한도를 조회합니다. subscribed는 호환용이며 항상 false입니다.
GET /api/v1/diet/ai-status
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/diet/ai-status HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 39
{"used":2,"limit":5,"subscribed":false}
| Path | Type | Description |
|---|---|---|
|
|
서울 오늘 사용 횟수 |
|
|
일일 한도, 5회 |
|
|
호환용 필드, 항상 false |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as AnalysisService·QuotaService
participant D as 식단 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: AI 사용량 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
식단 이미지 분석
날짜별 사용량을 예약하고 Anthropic 분석 결과를 반환합니다. 최대 20개 음식 항목을 정규화하며 결과 이력을 DB에 기록합니다.
POST /api/v1/diet/analyses
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
imageBase64는 최대 150만 자, mimeType은 image/jpeg, image/png, image/webp입니다.
POST /api/v1/diet/analyses HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 50
Host: localhost:8080
{"imageBase64":"aW1hZ2U=","mimeType":"image/jpeg"}
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
Base64 이미지, 최대 150만 자 |
|
|
image/jpeg, image/png, image/webp |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 155
{"items":[{"name":"밥","amount":"1공기","kcal":300,"carbG":null,"proteinG":null,"fatG":null,"fromAi":true,"edited":false}],"note":"AI 추정치예요."}
| Path | Type | Description |
|---|---|---|
|
|
분석한 음식 항목 배열, 최대 20개 |
|
|
AI 추정 안내 |
|
|
음식 이름, 1~40자 |
|
|
섭취량, 최대 20자 |
|
|
칼로리, 0~5000 kcal |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
영양소, 0~99999.9 g |
|
|
AI 분석 항목 여부 |
|
|
사용자 수정 여부 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
429 |
|
오늘 5회 한도 소진 |
다음 서울 날짜에 다시 요청합니다. |
422 |
|
음식 없음 또는 모델 거절, 사용량 유지 |
조건을 확인한 뒤 다시 요청합니다. |
502 |
|
외부 호출 실패, 예약 날짜의 사용량 환급 |
조건을 확인한 뒤 다시 요청합니다. |
503 |
|
분석 기능 설정 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as AnalysisService·QuotaService
participant D as 식단 클럽 DB
participant X as Anthropic
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 식단 이미지 분석
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S->>X: 예약 후 이미지 분석
X-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
끼니 알림
끼니 알림 설정 조회
알림 설정을 조회합니다. 설정이 없으면 모든 알림이 꺼진 기본값을 반환합니다.
GET /api/v1/diet/reminder-settings
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/diet/reminder-settings HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 75
{"times":{"breakfast":"08:00:00","lunch":null,"dinner":null},"agreed":true}
| Path | Type | Description |
|---|---|---|
|
|
끼니별 알림 시각 |
|
|
서울 알림 시각 (HH:mm:ss), null이면 비활성 |
|
|
서울 알림 시각 (HH:mm:ss), null이면 비활성 |
|
|
서울 알림 시각 (HH:mm:ss), null이면 비활성 |
|
|
알림 수신 동의 여부 |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as ReminderSettingsService
participant D as 식단 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 끼니 알림 설정 조회
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
끼니 알림 설정 교체
알림 시각과 수신 동의를 전체 교체합니다. 실제 발송은 별도 스케줄러가 수행합니다.
PUT /api/v1/diet/reminder-settings
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `diet`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
times는 필수입니다. breakfast/lunch/dinner는 서울 HH:mm 또는 null이며 agreed는 수신 동의 여부입니다.
PUT /api/v1/diet/reminder-settings HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 45
Host: localhost:8080
{"times":{"breakfast":"08:00"},"agreed":true}
| Name | Description |
|---|---|
|
식단 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
끼니별 알림 시각 |
|
|
서울 알림 시각 (HH:mm:ss), null이면 비활성 |
|
|
서울 알림 시각 (HH:mm:ss), null이면 비활성 |
|
|
서울 알림 시각 (HH:mm:ss), null이면 비활성 |
|
|
알림 수신 동의 여부 |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as ReminderSettingsService
participant D as 식단 클럽 DB
C->>A: PUT 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 끼니 알림 설정 교체
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
대표 오류 응답
아래 예제는 컨트롤러와 ControllerAdvice의 계약 테스트에서 생성합니다. 서비스 오류는 mock으로 재현하며 실제 외부 장애·보안 필터 검증을 대신하지 않습니다.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 160
{"detail":"입력값을 확인해 주세요.","instance":"/api/v1/diet/meals","status":400,"title":"입력값을 확인해 주세요.","code":"invalid_request"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Content-Length: 207
{"detail":"요청 제한을 초과했습니다. 잠시 후 다시 시도해 주세요.","instance":"/api/v1/diet/analyses","status":429,"title":"요청 제한을 초과했습니다.","code":"quota_exceeded"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
운동 클럽
처리 흐름은 Mermaid 소스 코드로 제공합니다.
보호 API의 문서 테스트는 가짜 JWT를 주입한 standalone MockMvc 계약 테스트입니다.
보안 필터의 서명·issuer·만료·audience 검증과 DB 잠금·외부 시스템의 동작 검증은 별도 테스트의 범위입니다.
실제 로그인은 공통 인증의 일회용 코드 교환으로 수행합니다. 보호 API 요청마다 Toss 인증을 호출하지 않습니다.
보안 필터와 업무 오류는 공통 ProblemDetail 형식을 사용합니다. 인증 실패는 401/not_authenticated, 공통 권한 거절은 `403/forbidden`입니다. 식단 클럽의 기존 컨트롤러 권한 거절 코드 `diet_token_required`는 유지합니다. 자세한 계약은 공통 오류 응답을 참고합니다.
`WORKOUT_ENABLED=true`이고 전용 DB·저장소 설정이 준비된 서버에서 보호 API를 제공합니다. 문서의 구현 계약은 운영 전환 완료 여부와 별개입니다.
공통 업무 규칙
운동 클럽은 여러 방의 운동 인증과 개인 루틴을 관리합니다. 운동·Auth의 DB와 트랜잭션은 분리합니다. 클럽 범위의 Auth 사용자 식별 조회는 공개 모듈 API로 수행합니다. 삭제 사진은 DB의 영속 대기열에 기록하고 커밋 이후 S3 삭제를 재시도합니다. 개인 루틴은 방 탈퇴 시 보존합니다. 새 사진은 JPEG를 검증하고 기존 PNG/JPEG는 변환 없이 읽습니다. 클라이언트는 서명 URL을 만료 범위 내에서 캐시할 수 있습니다.
사용자
사용자 조회
사용자를 조회하고 프로필이 없으면 Auth 사용자 ID로 생성합니다.
GET /api/v1/workout/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/workout/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 67
{"id":"10000000-0000-0000-0000-000000000001","name":"운동한량"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
이름 |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사용자 조회
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 프로필 조회·없으면 생성
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
이름 변경
본인 이름을 변경합니다.
PATCH /api/v1/workout/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name은 공백만인 값을 제외하고 1~16자입니다.
PATCH /api/v1/workout/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 23
Host: localhost:8080
{"name":"운동수달"}
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
이름, 공백만인 값 제외, 1~16자 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 67
{"id":"10000000-0000-0000-0000-000000000001","name":"운동수달"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
이름 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
400 |
|
공백 제거 후 빈 이름 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as UserService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: PATCH 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 이름 변경
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방
참여 방 조회
내 참여 방을 가입 순서로 조회합니다.
GET /api/v1/workout/rooms
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/workout/rooms HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 179
[{"id":"20000000-0000-0000-0000-000000000001","code":"ABC123","name":"운동방","capacity":20,"hostId":"10000000-0000-0000-0000-000000000001","createdAt":"2026-10-01T00:00:00Z"}]
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
초대 코드 |
|
|
방 이름 |
|
|
방 정원 (명) |
|
|
방장 UUID |
|
|
생성 시각 (UTC ISO 8601) |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 참여 방 조회
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 생성
방과 방장 참여를 생성합니다. 정원 20명, 최대 참여 방 5개입니다.
POST /api/v1/workout/rooms
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
name은 공백만인 값을 제외하고 1~16자입니다.
POST /api/v1/workout/rooms HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 20
Host: localhost:8080
{"name":"운동방"}
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
이름, 공백만인 값 제외, 1~16자 |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 177
{"id":"20000000-0000-0000-0000-000000000001","code":"ABC123","name":"운동방","capacity":20,"hostId":"10000000-0000-0000-0000-000000000001","createdAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
초대 코드 |
|
|
방 이름 |
|
|
방 정원 (명) |
|
|
방장 UUID |
|
|
생성 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
409 |
|
참여 방 5개 초과 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 생성
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
초대 코드 미리보기
방 정보·인원·방장·내 참여 여부를 조회합니다.
GET /api/v1/workout/rooms/preview
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query code에 초대 코드를 전달합니다.
GET /api/v1/workout/rooms/preview?code=ABC123 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
초대 코드 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 249
{"room":{"id":"20000000-0000-0000-0000-000000000001","code":"ABC123","name":"운동방","capacity":20,"hostId":"10000000-0000-0000-0000-000000000001","createdAt":"2026-10-01T00:00:00Z"},"memberCount":1,"hostName":"운동한량","alreadyMember":true}
| Path | Type | Description |
|---|---|---|
|
|
방 정보 |
|
|
현재 멤버 수 |
|
|
방장 이름 |
|
|
현재 참여 여부 |
|
|
식별자 UUID |
|
|
초대 코드 |
|
|
방 이름 |
|
|
방 정원 (명) |
|
|
방장 UUID |
|
|
생성 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
초대 코드에 해당하는 방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 초대 코드 미리보기
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 상세 조회
멤버와 최근 운동 인증 최대 1000건을 조회합니다.
GET /api/v1/workout/rooms/{room}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
GET /api/v1/workout/rooms/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 356
{"members":[{"userId":"10000000-0000-0000-0000-000000000001","name":"운동한량","joinedAt":"2026-10-01T00:00:00Z"}],"checkIns":[{"id":"20000000-0000-0000-0000-000000000001","roomId":"20000000-0000-0000-0000-000000000001","userId":"10000000-0000-0000-0000-000000000001","date":"2026-10-01","photoPaths":["photo.jpg"],"createdAt":"2026-10-01T00:00:00Z"}]}
| Path | Type | Description |
|---|---|---|
|
|
멤버 배열 |
|
|
최근 운동 인증 배열, 최대 1000건 |
|
|
멤버 UUID |
|
|
이름 |
|
|
가입 시각 (UTC ISO 8601) |
|
|
식별자 UUID |
|
|
방 UUID |
|
|
사용자 UUID |
|
|
운동 인증 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
인증 사진 경로 배열 |
|
|
생성 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
방 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
404 |
|
방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 상세 조회
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
방 가입
현재 사용자를 방에 참여시킵니다. 사용자·방 잠금으로 정원과 중복을 확인합니다.
POST /api/v1/workout/rooms/{room}/members
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
POST /api/v1/workout/rooms/20000000-0000-0000-0000-000000000001/members HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
409 |
|
이미 참여 중 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
정원 초과 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
참여 방 제한 초과 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 가입
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
방 탈퇴
본인 참여와 해당 방의 본인 인증을 삭제합니다. 방장은 가장 먼저 가입한 남은 멤버에게 인계하고 마지막 멤버가 나가면 방을 삭제합니다. 개인 루틴은 보존합니다.
DELETE /api/v1/workout/rooms/{room}/members/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID를 전달합니다. 본문이 없습니다.
DELETE /api/v1/workout/rooms/20000000-0000-0000-0000-000000000001/members/me HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
404 |
|
방 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoomService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 방 탈퇴
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
운동 인증과 사진
운동 사진 인증
서울 오늘 날짜로 운동 인증을 생성합니다. 동일 방·사용자·날짜의 중복을 막습니다.
POST /api/v1/workout/rooms/{room}/check-ins
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
multipart photos 1~3장, JPEG, 각 최대 8 MiB·2500만 픽셀, 요청 최대 25 MiB입니다. 업로드 동시 실행은 프로세스당 4건입니다.
POST /api/v1/workout/rooms/20000000-0000-0000-0000-000000000001/check-ins HTTP/1.1
Content-Type: multipart/form-data;charset=ISO-8859-1; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Authorization: Bearer documented-token
Host: localhost:8080
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=photos; filename=photo.jpg
Content-Type: image/jpeg
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
| Part | Description |
|---|---|
|
JPEG 사진 1~3장, 각 최대 8 MiB, 최대 2500만 픽셀 |
HTTP 201. DTO를 직접 반환합니다.
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 297
{"id":"20000000-0000-0000-0000-000000000001","roomId":"20000000-0000-0000-0000-000000000001","userId":"10000000-0000-0000-0000-000000000001","date":"2026-10-01","photoPaths":["20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/photo.jpg"],"createdAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
방 UUID |
|
|
사용자 UUID |
|
|
운동 인증 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
인증 사진 경로 배열 |
|
|
생성 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
파일 수 또는 파트 구성 오류 |
조건을 확인한 뒤 다시 요청합니다. |
400 |
|
JPEG 검증 실패 |
조건을 확인한 뒤 다시 요청합니다. |
409 |
|
오늘 이미 인증함 |
조건을 확인한 뒤 다시 요청합니다. |
413 |
|
사진 또는 요청 크기 초과 |
조건을 확인한 뒤 다시 요청합니다. |
429 |
|
동시 업로드 초과 |
조건을 확인한 뒤 다시 요청합니다. |
503 |
|
S3 장애 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as CheckInService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
participant X as S3
C->>A: POST 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 운동 사진 인증
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S->>X: JPEG 검증 후 사진 저장
X-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 201 응답
오늘 인증한 방 조회
오늘 운동 인증한 방 UUID 목록을 반환합니다.
GET /api/v1/workout/me/check-ins/today/rooms
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
본문이 없습니다.
GET /api/v1/workout/me/check-ins/today/rooms HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 40
["20000000-0000-0000-0000-000000000001"]
| Path | Type | Description |
|---|---|---|
|
|
오늘 운동 인증한 방 UUID 배열 |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as CheckInService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 오늘 인증한 방 조회
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
기간별 내 운동 인증 조회
해당 방의 본인 운동 인증을 조회합니다.
GET /api/v1/workout/rooms/{room}/check-ins/me
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
방 UUID, query from/to(YYYY-MM-DD)는 필수이며 순서가 올바른 최대 366일 구간입니다.
GET /api/v1/workout/rooms/20000000-0000-0000-0000-000000000001/check-ins/me?from=2026-10-01&to=2026-10-31 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
방 UUID |
| Parameter | Description |
|---|---|
|
시작 날짜 (YYYY-MM-DD) |
|
종료 날짜 (YYYY-MM-DD), 최대 366일 구간 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 299
[{"id":"20000000-0000-0000-0000-000000000001","roomId":"20000000-0000-0000-0000-000000000001","userId":"10000000-0000-0000-0000-000000000001","date":"2026-10-01","photoPaths":["20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/photo.jpg"],"createdAt":"2026-10-01T00:00:00Z"}]
| Path | Type | Description |
|---|---|---|
|
|
식별자 UUID |
|
|
방 UUID |
|
|
사용자 UUID |
|
|
운동 인증 날짜 (Asia/Seoul, YYYY-MM-DD) |
|
|
인증 사진 경로 배열 |
|
|
생성 시각 (UTC ISO 8601) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
날짜 역전 또는 366일 초과 |
조건을 확인한 뒤 다시 요청합니다. |
403 |
|
방 멤버가 아님 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as CheckInService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 기간별 내 운동 인증 조회
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
운동 인증 삭제
본인 인증을 삭제하고 사진 삭제는 커밋 이후 영속 큐로 처리합니다. S3 장애 시 스케줄러가 재시도합니다.
DELETE /api/v1/workout/check-ins/{id}
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
인증 UUID를 전달합니다. 본문이 없습니다.
DELETE /api/v1/workout/check-ins/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
운동 인증 UUID |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
403 |
|
타인 인증 |
조건을 확인한 뒤 다시 요청합니다. |
404 |
|
인증 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as CheckInService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: DELETE 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 운동 인증 삭제
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·삭제
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
사진 읽기 URL 발급
현재 참여 방의 실제 인증 사진에 600초 서명 URL을 발급합니다. 실제 S3 키는 workout/{path}입니다.
GET /api/v1/workout/photos/url
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query path에 인증 사진 경로를 전달합니다.
GET /api/v1/workout/photos/url?path=20000000-0000-0000-0000-000000000001/10000000-0000-0000-0000-000000000001/photo.jpg HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
사진 저장 경로 |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 53
{"url":"https://example.test/signed","expiresIn":600}
| Path | Type | Description |
|---|---|---|
|
|
서명된 사진 URL |
|
|
URL 유효기간 (초) |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
사진 경로 오류 |
조건을 확인한 뒤 다시 요청합니다. |
404 |
|
인증에 연결되지 않은 사진 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as CheckInService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 사진 읽기 URL 발급
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S->>S: S3Presigner로 읽기 URL 서명
S-->>A: 업무 결과
A-->>C: 200 응답
개인 루틴
개인 루틴 조회
루틴 설정·종목과 지정 날짜의 체크 UUID를 반환합니다.
GET /api/v1/workout/me/routine
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
query date(YYYY-MM-DD)는 필수입니다.
GET /api/v1/workout/me/routine?date=2026-10-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
조회 날짜 (YYYY-MM-DD) |
HTTP 200. DTO를 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 174
{"enabled":true,"items":[{"id":"20000000-0000-0000-0000-000000000001","weekday":4,"name":"스쿼트","position":0}],"checkedItemIds":["20000000-0000-0000-0000-000000000001"]}
| Path | Type | Description |
|---|---|---|
|
|
루틴 활성 여부 |
|
|
운동 종목 배열 |
|
|
조회 날짜에 체크한 종목 UUID 배열 |
|
|
식별자 UUID |
|
|
요일: 일요일 0~토요일 6 |
|
|
운동 종목, 1~30자 |
|
|
표시 순서, 0~69 |
보호 API는 인증 실패 시 재인증하고, 클럽 또는 접근 권한 거절 시 대상 클럽과 소유권·참여 상태를 확인합니다.
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoutineService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: GET 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 개인 루틴 조회
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·조회
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 200 응답
개인 루틴 교체
루틴 설정과 종목을 원자적으로 교체합니다. 같은 종목 ID의 체크는 보존하고 삭제한 종목의 체크는 제거합니다.
PUT /api/v1/workout/me/routine
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
enabled와 items(최대 70개)를 전달합니다. 종목 id(UUID), weekday(0~6), name(1~30자), position(0~69)입니다.
PUT /api/v1/workout/me/routine HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 116
Host: localhost:8080
{"enabled":true,"items":[{"name":"스쿼트","id":"20000000-0000-0000-0000-000000000001","position":0,"weekday":4}]}
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
루틴 활성 여부 |
|
|
운동 종목 배열, 최대 70개 |
|
|
식별자 UUID |
|
|
요일: 일요일 0~토요일 6 |
|
|
운동 종목, 1~30자 |
|
|
표시 순서, 0~69 |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
400 |
|
중복 종목 ID |
조건을 확인한 뒤 다시 요청합니다. |
403 |
|
타인 종목 ID |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoutineService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: PUT 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 개인 루틴 교체
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
오늘 루틴 체크 변경
서버 서울 오늘 날짜의 체크 여부를 변경합니다. 같은 체크 값은 멱등 처리합니다.
PUT /api/v1/workout/me/routine/items/{item}/checks/today
`Authorization: Bearer <JWT>`가 필요하며 대상 클럽은 `workout`입니다. 사용자 ID는 검증된 `sub`에서 얻습니다.
종목 UUID와 checked(boolean)는 필수입니다. 날짜는 받지 않습니다.
PUT /api/v1/workout/me/routine/items/20000000-0000-0000-0000-000000000001/checks/today HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 16
Host: localhost:8080
{"checked":true}
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
운동 종목 UUID |
| Path | Type | Description |
|---|---|---|
|
|
오늘 체크 여부 |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
|
입력 제약 위반 |
입력값을 수정합니다. |
403 |
|
타인 종목 |
조건을 확인한 뒤 다시 요청합니다. |
404 |
|
종목 없음 |
조건을 확인한 뒤 다시 요청합니다. |
sequenceDiagram
participant C as 클라이언트
participant A as API·인증
participant S as RoutineService
participant I as Auth 공개 API
participant D as 운동 클럽 DB
C->>A: PUT 요청
A->>A: JWT 인증·클럽 사용자 식별
A->>S: 오늘 루틴 체크 변경
S->>I: 클럽 범위 익명 키 확인
I-->>S: 사용자 식별 조회 결과
S->>D: 업무 조건 확인·저장
D-->>S: 처리 결과
S-->>A: 업무 결과
A-->>C: 204 응답
대표 오류 응답
아래 예제는 컨트롤러와 ControllerAdvice의 계약 테스트에서 생성합니다. 서비스 오류는 mock으로 재현하며 실제 외부 장애·보안 필터 검증을 대신하지 않습니다.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 160
{"detail":"입력값을 확인해 주세요.","instance":"/api/v1/workout/me","status":400,"title":"입력값을 확인해 주세요.","code":"invalid_request"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Length: 256
{"detail":"현재 상태에서는 요청을 처리할 수 없습니다.","instance":"/api/v1/workout/rooms/20000000-0000-0000-0000-000000000001/members","status":409,"title":"현재 상태에서는 요청을 처리할 수 없습니다.","code":"room_full"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
개인 운동 기록
사진 인증·방 참여·루틴 체크와 독립적인 개인 기록입니다. 방을 나가도 기록과 직접 만든 운동은 유지됩니다. 기본 운동은 공유하고 직접 만든 운동·즐겨찾기·기록은 JWT 사용자 범위로 분리합니다. 운동 부위와 이름은 운동 목록에서 얻고 기록에는 운동 UUID와 실제 측정값을 보관합니다. 기본 운동이나 직접 만든 운동을 변경·삭제하는 API는 제공하지 않아 과거 기록의 운동 정보가 유지됩니다. 워밍업을 제외한 중량 × 횟수의 합이 볼륨이며, 유산소 평균 페이스는 운동 시간 ÷ 거리입니다. 칼로리 추정은 제공하지 않습니다.
운동 목록 조회
기본 운동과 본인 운동, 본인 즐겨찾기를 반환합니다. 조회는 프로필을 생성하지 않습니다.
GET /api/v1/workout/exercises
운동 클럽 JWT의 서명·issuer·audience·club·sub를 검증합니다. 사용자 ID를 요청 본문에서 받지 않습니다.
GET /api/v1/workout/exercises HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
HTTP 200. DTO 또는 DTO 배열을 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 142
[{"id":"20000000-0000-0000-0000-000000000001","name":"바벨 스쿼트","bodyPart":"하체","type":"STRENGTH","custom":true,"favorite":false}]
| Path | Type | Description |
|---|---|---|
|
|
운동 UUID |
|
|
운동 이름 |
|
|
운동 부위 |
|
|
STRENGTH, BODYWEIGHT, CARDIO, TIMED |
|
|
본인이 만든 운동 여부 |
|
|
본인의 즐겨찾기 여부 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
|
JWT 누락·인증 실패 |
다시 인증합니다. |
403 |
|
다른 클럽 JWT |
운동 클럽 계정으로 인증합니다. |
flowchart LR
C["클라이언트"] --> A["Workout API · JWT 검증"]
A --> S["ExerciseService 또는 TrainingRecordService"]
S --> D[("운동 클럽 DB")]
D --> R["DTO 또는 204 응답"]
R --> C
직접 운동 만들기
같은 사용자에게 이름(대소문자 무시)·부위·유형이 같은 운동이 있으면 재사용합니다. 양 끝 공백은 제거합니다. 프로필이 없으면 Auth 공개 API를 확인하고 생성합니다.
POST /api/v1/workout/exercises
운동 클럽 JWT의 서명·issuer·audience·club·sub를 검증합니다. 사용자 ID를 요청 본문에서 받지 않습니다.
POST /api/v1/workout/exercises HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 65
Host: localhost:8080
{"bodyPart":"하체","name":"바벨 스쿼트","type":"STRENGTH"}
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Path | Type | Description |
|---|---|---|
|
|
운동 이름 1~60자, 공백 이름 금지 |
|
|
운동 부위 1~20자 |
|
|
STRENGTH, BODYWEIGHT, CARDIO, TIMED |
HTTP 200. DTO 또는 DTO 배열을 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 140
{"id":"20000000-0000-0000-0000-000000000001","name":"바벨 스쿼트","bodyPart":"하체","type":"STRENGTH","custom":true,"favorite":false}
| Path | Type | Description |
|---|---|---|
|
|
운동 UUID |
|
|
공백을 정리한 운동 이름 |
|
|
운동 부위 |
|
|
입력 유형 |
|
|
본인이 만든 운동 여부 |
|
|
본인의 즐겨찾기 여부 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
|
JWT 누락·인증 실패 |
다시 인증합니다. |
403 |
|
다른 클럽 JWT |
운동 클럽 계정으로 인증합니다. |
400 |
|
필드 제약·자료형·날짜 형식 위반 |
입력값을 수정합니다. |
flowchart LR
C["클라이언트"] --> A["Workout API · JWT 검증"]
A --> S["ExerciseService 또는 TrainingRecordService"]
S --> D[("운동 클럽 DB")]
D --> R["DTO 또는 204 응답"]
R --> C
즐겨찾기 변경
favorite 값을 멱등 저장합니다. 다른 사용자의 직접 만든 운동은 지정할 수 없습니다.
PUT /api/v1/workout/exercises/{id}/favorite
운동 클럽 JWT의 서명·issuer·audience·club·sub를 검증합니다. 사용자 ID를 요청 본문에서 받지 않습니다.
PUT /api/v1/workout/exercises/20000000-0000-0000-0000-000000000001/favorite HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 17
Host: localhost:8080
{"favorite":true}
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
기본 또는 본인 운동 UUID |
| Path | Type | Description |
|---|---|---|
|
|
즐겨찾기 설정 여부, 같은 값 재요청은 멱등 |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
|
JWT 누락·인증 실패 |
다시 인증합니다. |
403 |
|
다른 클럽 JWT |
운동 클럽 계정으로 인증합니다. |
400 |
|
필드 제약·자료형·날짜 형식 위반 |
입력값을 수정합니다. |
403 |
|
다른 사용자의 운동·기록 지정 |
본인 자료를 선택합니다. |
404 |
|
지정한 운동이 없음 |
운동 목록을 다시 조회합니다. |
flowchart LR
C["클라이언트"] --> A["Workout API · JWT 검증"]
A --> S["ExerciseService 또는 TrainingRecordService"]
S --> D[("운동 클럽 DB")]
D --> R["DTO 또는 204 응답"]
R --> C
기간별 기록 조회
시작일과 종료일을 포함한 최대 93일 범위를 조회합니다. 날짜 내림차순·생성 시각 내림차순입니다. 조회는 프로필을 생성하지 않습니다.
GET /api/v1/workout/me/records?from={from}&to={to}
운동 클럽 JWT의 서명·issuer·audience·club·sub를 검증합니다. 사용자 ID를 요청 본문에서 받지 않습니다.
GET /api/v1/workout/me/records?from=2026-09-28&to=2026-10-04 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
조회 시작 날짜, YYYY-MM-DD |
|
조회 종료 날짜, 시작일 포함 최대 93일 |
HTTP 200. DTO 또는 DTO 배열을 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 351
[{"id":"20000000-0000-0000-0000-000000000001","version":1,"date":"2026-10-01","durationSeconds":3480,"note":"컨디션 좋음","exercises":[{"exerciseId":"20000000-0000-0000-0000-000000000001","sets":[{"weightKg":60,"reps":10,"warmup":false}],"durationSeconds":0,"distanceKm":0}],"createdAt":"2026-10-01T00:00:00Z","updatedAt":"2026-10-01T00:00:00Z"}]
| Path | Type | Description |
|---|---|---|
|
|
기록 UUID |
|
|
기록 버전 |
|
|
서울 기준 운동 날짜 |
|
|
총 운동 시간, 초 |
|
|
메모 |
|
|
운동별 세트·시간·거리, 아래 입력 계약 참조 |
|
|
생성 절대 시각 |
|
|
수정 절대 시각 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
|
JWT 누락·인증 실패 |
다시 인증합니다. |
403 |
|
다른 클럽 JWT |
운동 클럽 계정으로 인증합니다. |
400 |
|
필드 제약·자료형·날짜 형식 위반 |
입력값을 수정합니다. |
400 |
|
기간 범위·미래 날짜·중복 운동·유형별 측정값 위반 |
입력값과 조회 기간을 수정합니다. |
flowchart LR
C["클라이언트"] --> A["Workout API · JWT 검증"]
A --> S["ExerciseService 또는 TrainingRecordService"]
S --> D[("운동 클럽 DB")]
D --> R["DTO 또는 204 응답"]
R --> C
기록 저장·수정
클라이언트가 UUID를 생성하며 재시도에도 동일한 ID와 본문을 사용합니다. 새 기록은 version=0, 수정은 마지막 응답의 version을 보냅니다. 동일 내용 재전송은 버전을 올리지 않고 저장 결과를 반환합니다. 다른 내용의 오래된 버전은 거절합니다. 한 기록의 운동 UUID는 중복할 수 없습니다. 날짜는 서울 기준 2000-01-01~오늘입니다. 유형별 값과 전체 입력 상한은 아래 필드 표를 따릅니다. 사용자 잠금과 기록 ID 잠금으로 중복 생성을 직렬화합니다. 사진 인증이나 루틴 체크를 변경하지 않습니다.
PUT /api/v1/workout/me/records/{id}
하루 통합 저장에는 sourceRecords`를 보냅니다. 해당 날짜에 조회한 모든 본인 기록의 `id`와 `version 목록이며 최대 100개입니다. 빈 배열은 해당 날짜에 기존 기록이 없다는 조건이고, 생략 또는 null이면 기존 개별 저장 계약을 유지합니다. 원본 ID는 중복할 수 없으며 version은 1 이상입니다. 수정 대상 ID를 포함하고 그 버전은 요청 version과 같아야 합니다. 통합 중 날짜 변경은 허용하지 않습니다.
서버는 사용자 잠금 안에서 날짜의 전체 원본과 버전을 대조합니다. 다른 기기에서 추가·수정·삭제한 원본이 있으면 `409/record_conflict`로 전체 요청을 거절합니다. 검증 성공 시 전달한 운동·시간·메모로 대상 ID를 저장하고 다른 원본을 같은 트랜잭션에서 정리합니다. 클라이언트가 원본의 세트·시간·메모를 합쳐 보내며 서버가 값을 추정하거나 자동으로 더하지 않습니다. 통합 성공 응답을 잃은 동일 ID·본문 재시도는 다시 저장하거나 버전을 올리지 않습니다. 기존 API의 운동·세트·시간·메모 상한은 통합에도 동일하게 적용합니다.
운동 클럽 JWT의 서명·issuer·audience·club·sub를 검증합니다. 사용자 ID를 요청 본문에서 받지 않습니다.
PUT /api/v1/workout/me/records/20000000-0000-0000-0000-000000000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 254
Host: localhost:8080
{"note":"컨디션 좋음","version":0,"durationSeconds":3480,"date":"2026-10-01","sourceRecords":[],"exercises":[{"exerciseId":"20000000-0000-0000-0000-000000000001","sets":[{"weightKg":60,"reps":10,"warmup":false}],"durationSeconds":0,"distanceKm":0}]}
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
클라이언트가 생성한 기록 UUID, 재시도에도 동일한 값 |
| Path | Type | Description |
|---|---|---|
|
|
새 기록은 0, 수정은 마지막 응답의 버전 |
|
|
2000-01-01~서버 서울 오늘 날짜 |
|
|
총 운동 시간, 0~86400초 |
|
|
메모, 최대 1000자, 빈 문자열 허용 |
|
|
하루 통합 저장 시 날짜의 전체 원본 id/version 목록, 최대 100개. 빈 배열은 기록 없는 날짜의 시작. 생략/null은 기존 개별 기록 저장 |
|
|
중복 없는 운동 1~30개 |
|
|
기본 또는 본인 운동 UUID |
|
|
운동 시간: 근력·맨몸은 0, 유산소·시간은 1~86400초 |
|
|
유산소 거리 0~1000km, 다른 유형은 0 |
|
|
근력·맨몸은 1~30개, 다른 유형은 빈 배열 |
|
|
0~2000kg, 맨몸은 0 |
|
|
1~1000회 정수 |
|
|
워밍업 여부, 볼륨에서 제외 |
HTTP 200. DTO 또는 DTO 배열을 직접 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 349
{"id":"20000000-0000-0000-0000-000000000001","version":1,"date":"2026-10-01","durationSeconds":3480,"note":"컨디션 좋음","exercises":[{"exerciseId":"20000000-0000-0000-0000-000000000001","sets":[{"weightKg":60,"reps":10,"warmup":false}],"durationSeconds":0,"distanceKm":0}],"createdAt":"2026-10-01T00:00:00Z","updatedAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
기록 UUID |
|
|
저장 후 버전 |
|
|
운동 날짜 |
|
|
총 운동 시간, 초 |
|
|
메모 |
|
|
저장한 운동 배열, 요청과 같은 측정 필드 |
|
|
생성 절대 시각 |
|
|
수정 절대 시각 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
|
JWT 누락·인증 실패 |
다시 인증합니다. |
403 |
|
다른 클럽 JWT |
운동 클럽 계정으로 인증합니다. |
400 |
|
필드 제약·자료형·날짜 형식 위반 |
입력값을 수정합니다. |
403 |
|
다른 사용자의 운동·기록 지정 |
본인 자료를 선택합니다. |
404 |
|
지정한 운동이 없음 |
운동 목록을 다시 조회합니다. |
400 |
|
기간 범위·미래 날짜·중복 운동·유형별 측정값 위반 |
입력값과 조회 기간을 수정합니다. |
404 |
|
수정·삭제 대상이 없음 |
기록 목록을 갱신합니다. |
409 |
|
다른 내용으로 저장된 버전과 요청 버전이 다름 |
임시 내용을 보관하고 최신 기록을 조회합니다. |
flowchart LR
C["클라이언트"] --> A["Workout API · JWT 검증"]
A --> S["ExerciseService 또는 TrainingRecordService"]
S --> D[("운동 클럽 DB")]
D --> R["DTO 또는 204 응답"]
R --> C
기록 삭제
본인 기록의 마지막 버전만 삭제합니다. 다른 데이터는 보존합니다. 삭제 후 동일 ID와 version=0으로 원본을 다시 저장하면 복구할 수 있으며 생성 시각은 복구 시각입니다. 클라이언트는 복구 내용이 남아 있을 때만 되돌리기를 제공합니다.
DELETE /api/v1/workout/me/records/{id}?version={version}
운동 클럽 JWT의 서명·issuer·audience·club·sub를 검증합니다. 사용자 ID를 요청 본문에서 받지 않습니다.
DELETE /api/v1/workout/me/records/20000000-0000-0000-0000-000000000001?version=1 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Name | Description |
|---|---|
|
운동 클럽 JWT (Bearer) |
| Parameter | Description |
|---|---|
|
삭제할 기록 UUID |
| Parameter | Description |
|---|---|
|
마지막 조회한 버전 |
HTTP 204. 본문이 없습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
|
JWT 누락·인증 실패 |
다시 인증합니다. |
403 |
|
다른 클럽 JWT |
운동 클럽 계정으로 인증합니다. |
400 |
|
필드 제약·자료형·날짜 형식 위반 |
입력값을 수정합니다. |
403 |
|
다른 사용자의 운동·기록 지정 |
본인 자료를 선택합니다. |
404 |
|
수정·삭제 대상이 없음 |
기록 목록을 갱신합니다. |
409 |
|
다른 내용으로 저장된 버전과 요청 버전이 다름 |
임시 내용을 보관하고 최신 기록을 조회합니다. |
flowchart LR
C["클라이언트"] --> A["Workout API · JWT 검증"]
A --> S["ExerciseService 또는 TrainingRecordService"]
S --> D[("운동 클럽 DB")]
D --> R["DTO 또는 204 응답"]
R --> C
쓰기에서는 UserService.ensureProfileAndLock이 Auth 공개 API로 운동 클럽 사용자 식별을 확인하고 Workout DB 프로필과 사용자 잠금을 확보합니다. 다른 모듈 DB와 하나의 트랜잭션으로 커밋하지 않습니다. 조회에는 Auth 조회·Toss 호출·프로필 생성이 없습니다.
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Length: 259
{"detail":"현재 상태에서는 요청을 처리할 수 없습니다.","instance":"/api/v1/workout/me/records/20000000-0000-0000-0000-000000000001","status":409,"title":"현재 상태에서는 요청을 처리할 수 없습니다.","code":"record_conflict"}
| Path | Type | Description |
|---|---|---|
|
|
문제 유형 URI |
|
|
오류 제목 |
|
|
HTTP 상태 코드 |
|
|
표시용 오류 설명, 분기에 사용하지 않습니다 |
|
|
요청 경로 |
|
|
클라이언트 분기용 오류 코드 |
운동 기록 임시 저장
임시 기록은 완료 기록과 분리해 사용자별로 하나씩 서버에 보관합니다. 완료 기록 목록·운동 통계에 포함하지 않습니다. 같은 운동 클럽 사용자로 로그인하면 기기와 관계없이 이어 쓸 수 있습니다. 입력 중인 빈 문자열과 미완성 숫자도 문자열로 보관하며, 실제 날짜·운동·측정값 검증은 완료 기록 저장 시 수행합니다. 요청 크기는 DTO의 문자열·운동·세트 개수 제한으로 검증합니다.
`draft.sourceRecords`는 선택적인 하루 통합 원본 목록입니다. 각 항목의 id와 1 이상의 version을 보관하며 최대 100개입니다. 생략/null은 기존 개별 초안이고 빈 배열은 새로운 날짜의 시작입니다. 원본 목록의 최신 여부는 완료 기록 저장 시 검증하므로 충돌한 편집 내용도 서버 초안으로 보관할 수 있습니다.
작성 중인 운동 기록 조회
현재 사용자의 임시 기록과 마지막 서버 저장 버전을 조회합니다.
GET /api/v1/workout/me/record-drafts/current, `clubs.workout.enabled=true`일 때 제공합니다.
운동 클럽 Bearer JWT가 필요합니다. 검증된 JWT의 사용자만 조회하며 다른 사용자 ID를 요청으로 받지 않습니다.
본문과 query가 없습니다.
GET /api/v1/workout/me/record-drafts/current HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
200을 반환합니다. 작성 중인 기록이 없으면 draft=null`입니다. 최초 `revision=0, `updatedAt=null`이며 삭제 후에도 마지막 revision을 유지합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 336
{"revision":1,"draft":{"id":"20000000-0000-0000-0000-000000000001","version":0,"date":"2026-10-01","minutes":"","note":"작성 중","exercises":[{"exerciseId":"10000000-0000-0000-0000-000000000001","sets":[{"weightKg":"","reps":"","warmup":false}],"minutes":"","distanceKm":""}],"sourceRecords":null},"updatedAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
임시 기록 버전, 변경 요청의 기대 버전으로 사용 |
|
|
현재 임시 기록, 저장 요청의 draft와 동일한 형식 |
|
|
서버 저장 절대 시각 |
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 44
{"revision":0,"draft":null,"updatedAt":null}
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
401 |
not_authenticated |
JWT 누락·검증 실패 |
운동 클럽으로 로그인합니다. |
403 |
forbidden |
다른 클럽 JWT 또는 잘못된 사용자 식별 |
클럽·권한을 확인합니다. |
flowchart LR
C[클라이언트] --> A[API · Workout JWT 검증]
A --> S[RecordDraftService.get]
S --> D[(Workout DB · record_drafts)]
D --> R[revision · 임시 기록 · 저장 시각]
R --> C
작성 중인 운동 기록 저장
입력 중인 내용을 전체 대체하고 다른 기기에서 이어 쓸 수 있도록 보관합니다.
PUT /api/v1/workout/me/record-drafts/current, `clubs.workout.enabled=true`일 때 제공합니다.
운동 클럽 Bearer JWT가 필요합니다. Workout 프로필을 확인·생성하고 사용자 잠금 안에서 자기 임시 기록만 변경합니다.
`revision`은 조회·직전 저장 응답의 기대 버전입니다. 최초 생성은 0입니다. draft에는 기록 UUID·완료 기록의 기반 version·날짜·분 단위 시간·메모·운동별 세트 입력을 포함합니다. 문자열은 필수이며 빈 문자열을 허용합니다. 날짜 최대 10자, 메모 1000자, 시간·거리·중량·횟수 입력 32자, 운동과 각 운동의 세트 최대 30개입니다. 임시 입력의 숫자·날짜 유효성은 완료 단계에서 검증합니다.
PUT /api/v1/workout/me/record-drafts/current HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Content-Length: 301
Host: localhost:8080
{"draft":{"id":"20000000-0000-0000-0000-000000000001","version":0,"date":"2026-10-01","minutes":"","note":"작성 중","exercises":[{"exerciseId":"10000000-0000-0000-0000-000000000001","sets":[{"weightKg":"","reps":"","warmup":false}],"minutes":"","distanceKm":""}],"sourceRecords":null},"revision":0}
| Path | Type | Description |
|---|---|---|
|
|
기대 버전, 최초 생성은 0이며 이후 조회·저장 응답의 값을 사용 |
|
|
작성 중인 운동 기록 UUID |
|
|
완료 기록의 기반 버전, 신규 기록은 0 |
|
|
작성 중인 날짜 문자열, 최대 10자, 빈 문자열 허용 |
|
|
총 운동 시간 입력 문자열, 단위 분, 최대 32자 |
|
|
메모 문자열, 최대 1000자 |
|
|
선택한 운동 UUID, 운동은 최대 30개 |
|
|
운동별 시간 입력 문자열, 분, 최대 32자 |
|
|
거리 입력 문자열, km, 최대 32자 |
|
|
중량 입력 문자열, kg, 최대 32자, 세트 최대 30개 |
|
|
횟수 입력 문자열, 최대 32자 |
|
|
워밍업 여부 |
|
|
하루 통합 대상 원본 id/version 목록, 최대 100개, 생략/null은 개별 기록 초안 |
200과 저장한 내용을 반환합니다. 변경 시 revision을 증가시키며 같은 draft 본문 재시도는 이미 저장된 응답을 반환합니다. 응답을 잃으면 동일 본문과 revision으로 먼저 재시도하고 최신 입력은 그 다음에 저장합니다. 삭제·완료 이후에도 마지막 revision을 유지하므로 늦게 도착한 이전 저장 요청은 거절됩니다. 다른 임시 기록 UUID로 직접 대체하지 않고 현재 기록을 완료하거나 삭제한 후 새로 작성합니다.
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 336
{"revision":1,"draft":{"id":"20000000-0000-0000-0000-000000000001","version":0,"date":"2026-10-01","minutes":"","note":"작성 중","exercises":[{"exerciseId":"10000000-0000-0000-0000-000000000001","sets":[{"weightKg":"","reps":"","warmup":false}],"minutes":"","distanceKm":""}],"sourceRecords":null},"updatedAt":"2026-10-01T00:00:00Z"}
| Path | Type | Description |
|---|---|---|
|
|
저장 후 버전, 같은 본문의 재시도는 증가하지 않음 |
|
|
서버에 보관한 작성 내용 |
|
|
서버 저장 절대 시각 |
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
invalid_request |
필수값·문자열·개수 제한 위반 |
입력을 수정합니다. |
401 |
not_authenticated |
JWT 누락·검증 실패 |
운동 클럽으로 로그인합니다. |
403 |
forbidden |
다른 클럽 JWT 또는 잘못된 사용자 식별 |
클럽·권한을 확인합니다. |
403 |
not_owner |
다른 사용자의 완료 기록 ID |
자기 기록을 선택합니다. |
404 |
record_not_found |
기반 version이 있으나 완료 기록이 없음 |
완료 기록을 다시 조회합니다. |
409 |
record_draft_conflict |
revision·UUID 충돌 또는 완료 후 오래된 자동 저장 |
현재 입력을 유지하고 서버 최신 기록을 확인합니다. 덮어쓰기 재시도를 하지 않습니다. |
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Length: 242
{"detail":"현재 상태에서는 요청을 처리할 수 없습니다.","instance":"/api/v1/workout/me/record-drafts/current","status":409,"title":"현재 상태에서는 요청을 처리할 수 없습니다.","code":"record_draft_conflict"}
flowchart LR
C[클라이언트 · 자동 저장 직렬화] --> A[API · JWT와 입력 크기 검증]
A --> S[RecordDraftService.save · Workout 트랜잭션]
S --> U[UserService.ensureProfileAndLock]
U --> I[Auth 공개 식별 API]
S --> V[완료 기록 소유권 · 기반 version · draft revision 검증]
V --> D[(Workout DB · record_drafts)]
D --> R[revision과 작성 내용 응답]
R --> C
작성 중인 운동 기록 삭제
현재 임시 기록을 버립니다. 다른 기기의 최신 변경을 지우지 않도록 ID와 revision을 확인합니다.
DELETE /api/v1/workout/me/record-drafts/current, `clubs.workout.enabled=true`일 때 제공합니다.
운동 클럽 Bearer JWT가 필요합니다. 자기 임시 기록만 삭제하며 Workout 프로필 확인·사용자 잠금을 수행합니다.
본문이 없습니다. query `id`와 `revision`은 필수입니다.
DELETE /api/v1/workout/me/record-drafts/current?id=20000000-0000-0000-0000-000000000001&revision=1 HTTP/1.1
Content-Type: application/json
Authorization: Bearer documented-token
Host: localhost:8080
| Parameter | Description |
|---|---|
|
삭제할 임시 기록 UUID |
|
기대 임시 기록 버전 |
204이며 본문이 없습니다. 이미 임시 기록이 없으면 동일한 성공을 반환합니다. 내용은 삭제하고 revision은 증가시켜 늦은 저장의 복원을 막습니다. 삭제 후 조회한 revision으로 새 기록을 작성합니다. 완료 기록 저장은 같은 Workout 트랜잭션에서 일치하는 ID와 기반 version의 임시 기록을 정리합니다. 이전 완료 요청의 재시도는 이후 새로 작성한 편집 초안을 지우지 않습니다.
HTTP/1.1 204 No Content
| HTTP 상태 | code | 발생 조건 | 클라이언트 처리 |
|---|---|---|---|
400 |
invalid_request |
query 누락·형식 오류 |
ID와 revision을 확인합니다. |
401 |
not_authenticated |
JWT 누락·검증 실패 |
운동 클럽으로 로그인합니다. |
403 |
forbidden |
다른 클럽 JWT 또는 잘못된 사용자 식별 |
클럽·권한을 확인합니다. |
409 |
record_draft_conflict |
서버의 임시 기록 ID 또는 revision 불일치 |
최신 기록을 다시 확인합니다. |
flowchart LR
C[클라이언트] --> A[API · Workout JWT 검증]
A --> S[RecordDraftService.delete · 사용자 잠금]
S --> V[ID와 revision 확인]
V --> D[(Workout DB · 내용 제거와 revision 증가)]
D --> R[204 응답]
R --> C