공통 인증

처리 흐름은 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

not_authenticated

토큰 누락·만료·검증 실패

대상 클럽으로 다시 로그인합니다.

403

forbidden

인증된 JWT의 대상 클럽·사용자 식별 조건 불일치

대상 클럽과 접근 권한을 확인합니다.

403

diet_token_required

식단 컨트롤러의 JWT 식별 거절

식단 클럽 토큰과 접근 권한을 확인합니다.

500

internal_error

예상하지 못한 서버 오류

자동으로 쓰기 요청을 반복하지 않고 상태를 확인합니다.

보안 필터의 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

type

String

문제 유형 URI: about:blank

title

String

한국어 오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 한국어 설명

instance

String

요청 경로, query 제외

code

String

클라이언트 분기용 안정적인 오류 코드

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

club

String

대상 클럽: workout, wakeup, diet, attendance

code

String

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

user.id

String

클럽 범위의 공통 인증 사용자 UUID

accessToken

String

해당 클럽 JWT

tokenType

String

토큰 유형: Bearer

expiresIn

Number

JWT 유효기간 (초)

Table 1. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

필수 값 누락·입력 제약 위반·JSON 오류

입력을 수정합니다.

400

unsupported_club

지원하지 않는 클럽

조건을 확인한 뒤 다시 요청합니다.

401

invalid_authorization_code

Toss가 코드를 거절함

새 일회용 코드를 발급받습니다.

503

toss_unavailable

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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

기상 클럽

처리 흐름은 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

Authorization

기상 클럽 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

id

String

공통 인증 사용자 UUID

name

String

이름

tossUserKey

Number

기존 토스 사용자 키 (null 허용)

createdAt

String

가입 시각 (UTC)

Table 2. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

not_found

가입 정보 없음

사용자 가입 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

Authorization

기상 클럽 JWT (Bearer)

Path Type Description

name

String

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

id

String

공통 인증 사용자 UUID

name

String

이름

tossUserKey

Number

기존 토스 사용자 키 (null 허용)

createdAt

String

가입 시각 (UTC)

Table 3. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Path Type Description

name

String

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

id

String

공통 인증 사용자 UUID

name

String

이름

tossUserKey

Number

기존 토스 사용자 키 (null 허용)

createdAt

String

가입 시각 (UTC)

Table 4. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

실제 처리 흐름
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

Authorization

기상 클럽 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

[].id

String

방 UUID

[].code

String

참여 코드

[].name

String

방 이름

[].activationTime

String

기상 시각 (HH:mm, Asia/Seoul)

[].activationDurationMin

Number

기상 버튼 활성 시간 (분)

[].capacity

Number

정원

[].activeWeekdays

Array

활성 요일 (일=0 ~ 토=6)

[].ownerId

String

방장 UUID

[].memberCount

Number

현재 멤버 수

[].createdAt

String

생성 시각 (UTC)

Table 5. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

not_found

프로필 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Path Type Description

name

String

1~16자 방 이름

activationTime

String

04:00~11:55 기상 시각

activeWeekdays

Array

활성 요일

성공 응답

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

id

String

방 UUID

code

String

참여 코드

name

String

방 이름

activationTime

String

기상 시각 (HH:mm, Asia/Seoul)

activationDurationMin

Number

기상 버튼 활성 시간 (분)

capacity

Number

정원

activeWeekdays

Array

활성 요일 (일=0 ~ 토=6)

ownerId

String

방장 UUID

memberCount

Number

현재 멤버 수

createdAt

String

생성 시각 (UTC)

Table 6. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

409

already_in_room

이미 방에 참여 중

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Table 7. /api/v1/wakeup/rooms/{roomId}
Parameter Description

roomId

방 UUID

Path Type Description

name

String

1~16자 방 이름

activationTime

String

04:00~11:55 기상 시각

activeWeekdays

Array

활성 요일

성공 응답

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

id

String

방 UUID

code

String

참여 코드

name

String

방 이름

activationTime

String

기상 시각 (HH:mm, Asia/Seoul)

activationDurationMin

Number

기상 버튼 활성 시간 (분)

capacity

Number

정원

activeWeekdays

Array

활성 요일 (일=0 ~ 토=6)

ownerId

String

방장 UUID

memberCount

Number

현재 멤버 수

createdAt

String

생성 시각 (UTC)

Table 8. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

403

forbidden

방장 권한 없음 또는 방 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Table 9. /api/v1/wakeup/rooms/{roomId}
Parameter Description

roomId

방 UUID

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 10. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

forbidden

방장 권한 없음 또는 방 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Path Type Description

code

String

방 참여 코드

성공 응답

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

id

String

방 UUID

code

String

참여 코드

name

String

방 이름

activationTime

String

기상 시각 (HH:mm, Asia/Seoul)

activationDurationMin

Number

기상 버튼 활성 시간 (분)

capacity

Number

정원

activeWeekdays

Array

활성 요일 (일=0 ~ 토=6)

ownerId

String

방장 UUID

memberCount

Number

현재 멤버 수

createdAt

String

생성 시각 (UTC)

Table 11. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

404

not_found

초대 코드 또는 프로필 없음

조건을 확인한 뒤 다시 요청합니다.

409

already_in_room

다른 방에 참여 중

조건을 확인한 뒤 다시 요청합니다.

409

room_full

정원 초과

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 12. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

not_found

프로필 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Table 13. /api/v1/wakeup/rooms/{roomId}/membership
Parameter Description

roomId

방 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

notifyEnabled

Boolean

알림 수신 여부

notificationAgreementAt

String

알림 동의 시각 (null 허용)

reminderOffsetMin

Number

기상 시각 이전 알림 분 (0~60)

nickname

String

방 닉네임 (null 허용)

Table 14. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

forbidden

해당 방의 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Table 15. /api/v1/wakeup/rooms/{roomId}/membership
Parameter Description

roomId

방 UUID

Path Type Description

notifyEnabled

Boolean

알림 수신 여부

reminderOffsetMin

Number

기상 시각 이전 알림 분 (0~60)

nickname

String

1~16자 방 닉네임

clearNickname

Boolean

닉네임 삭제 여부

성공 응답

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

notifyEnabled

Boolean

알림 수신 여부

notificationAgreementAt

String

알림 동의 시각 (null 허용)

reminderOffsetMin

Number

기상 시각 이전 알림 분 (0~60)

nickname

String

방 닉네임 (null 허용)

Table 16. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

403

forbidden

해당 방의 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Table 17. /api/v1/wakeup/rooms/{roomId}/members
Parameter Description

roomId

방 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

[].userId

String

멤버 UUID

[].name

String

방 닉네임 또는 사용자 이름

Table 18. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

forbidden

해당 방의 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Table 19. /api/v1/wakeup/rooms/{roomId}/check-ins
Parameter Description

roomId

방 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

id

String

출석 UUID

userId

String

출석 사용자 UUID

userName

String

출석 당시 이름

date

String

출석 날짜 (Asia/Seoul)

pressedAt

String

서버에서 기록한 버튼 입력 시각 (UTC)

Table 20. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

forbidden

해당 방의 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

기상 클럽 JWT (Bearer)

Table 21. /api/v1/wakeup/rooms/{roomId}/check-ins
Parameter Description

roomId

방 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

[].id

String

출석 UUID

[].userId

String

출석 사용자 UUID

[].userName

String

출석 당시 이름

[].date

String

출석 날짜 (Asia/Seoul)

[].pressedAt

String

서버에서 기록한 버튼 입력 시각 (UTC)

Table 22. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

forbidden

해당 방의 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

출석 클럽

처리 흐름은 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�~[���,Oc���=|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^)�pQEQEQEW�|/��H��w"����A!F�`$����y�^s��������>�E,���P��c��؁�r=�<�G�>��8��Tߜ�E���EW�|8QEQE�>7�g�4�����)i-��\?�9�X��N3�I�[�+�����	���
2�ddzk���׼+��������v��|��\a�a�����F	M�CF}VQ��0�Q���[>�����|�Ez���b@��mQYKEx�*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�~[���,Oc���=|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^)�pQEQEQEW�|/��H��w"����A!F�`$����y�^s��������>�E,���P��c��؁�r=�<�G�>��8��Tߜ�E���EW�|8QEQE�>7�g�4�����)i-��\?�9�X��N3�I�[�+�����	���
2�ddzk���׼+��������v��|��\a�a�����F	M�CF}VQ��0�Q���[>�����|�Ez���b@��mQYKEx�*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

reference

입실 JPEG 사진, 최대 8 MiB·4,000,000 픽셀, 정확히 하나

candidate

퇴실 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

verdict

String

색 분포 판정: MATCH, NON_MATCH, UNDECIDABLE

reason

String

판정 사유: 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

type

String

문제 유형 URI. 기본 유형일 때 생략될 수 있음

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

오류 설명. 분기 조건으로 사용하지 않음

instance

String

오류가 발생한 요청 경로

code

String

클라이언트 분기용 오류 코드: 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

Authorization

출석 클럽 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

id

String

식별자 UUID

name

String

이름

createdAt

String

생성 시각 (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

Authorization

출석 클럽 JWT (Bearer)

Path Type Description

name

String

이름, 공백만인 값 제외, 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

id

String

식별자 UUID

name

String

이름

createdAt

String

생성 시각 (UTC ISO 8601)

Table 23. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

실제 처리 흐름
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

Authorization

출석 클럽 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

id

String

식별자 UUID

code

String

초대 코드

name

String

방 이름

capacity

Number

방 정원 (명)

hostId

String

방장 UUID

createdAt

String

생성 시각 (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

Authorization

출석 클럽 JWT (Bearer)

Path Type Description

name

String

이름, 공백만인 값 제외, 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

id

String

식별자 UUID

code

String

초대 코드

name

String

방 이름

capacity

Number

방 정원 (명)

hostId

String

방장 UUID

createdAt

String

생성 시각 (UTC ISO 8601)

Table 24. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

409

already_in_room

이미 방에 참여 중

조건을 확인한 뒤 다시 요청합니다.

409

profile_required

프로필 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

출석 클럽 JWT (Bearer)

Parameter Description

code

초대 코드

성공 응답

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

id

String

식별자 UUID

name

String

방 이름

memberCount

Number

현재 멤버 수

hostName

String

방장 이름

alreadyMember

Boolean

현재 참여 여부

오류와 클라이언트 처리

보호 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

Authorization

출석 클럽 JWT (Bearer)

Table 25. /api/v1/attendance/rooms/{room}/members
Parameter Description

room

방 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

[].userId

String

멤버 UUID

[].name

String

이름

[].joinedAt

String

가입 시각 (UTC ISO 8601)

Table 26. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

not_room_member

방 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

404

room_not_found

방 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

출석 클럽 JWT (Bearer)

Table 27. /api/v1/attendance/rooms/{room}/membership
Parameter Description

room

방 UUID

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 28. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

409

already_in_room

이미 방에 참여 중

조건을 확인한 뒤 다시 요청합니다.

409

profile_required

프로필 없음

조건을 확인한 뒤 다시 요청합니다.

409

room_full

정원 초과

조건을 확인한 뒤 다시 요청합니다.

404

room_not_found

방 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

출석 클럽 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

Authorization

출석 클럽 JWT (Bearer)

Path Type Description

kind

String

입실 in 또는 퇴실 out

photoPath

String

현재 방의 본인 사진 경로, 최대 256자

latitude

Number

위도, -90~90도

longitude

Number

경도, -180~180도

accuracy

Number

위치 정확도, 0 이상 (m)

placeName

String

장소 이름, 최대 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

id

String

식별자 UUID

roomId

String

방 UUID

userId

String

사용자 UUID

date

String

출석 날짜 (Asia/Seoul, YYYY-MM-DD)

placeName

String

장소 이름

checkIn

Object

입실 또는 퇴실 기록, null 허용

checkIn.photoPath

String

사진 경로

checkIn.at

String

기록 시각 (UTC ISO 8601)

checkIn.latitude

Number

위도 (도)

checkIn.longitude

Number

경도 (도)

checkIn.accuracy

Number

위치 정확도 (m)

checkOut

Object

입실 또는 퇴실 기록, null 허용

checkOut.photoPath

String

사진 경로

checkOut.at

String

기록 시각 (UTC ISO 8601)

checkOut.latitude

Number

위도 (도)

checkOut.longitude

Number

경도 (도)

checkOut.accuracy

Number

위치 정확도 (m)

verified

Boolean

출석 인증 성공 여부

verifyReason

String

판정 사유, null 허용

locationDistanceM

Number

사진 위치 거리 (m), null 허용

photoDistance

Number

내부 사진 거리 값, 확률이 아님, null 허용

updatedAt

String

갱신 시각 (UTC ISO 8601)

Table 29. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

409

already_checked_in

중복 입실

조건을 확인한 뒤 다시 요청합니다.

409

already_checked_out

성공 퇴실 또는 퇴실 단독 기록 중복

조건을 확인한 뒤 다시 요청합니다.

409

no_room

참여 방 없음

조건을 확인한 뒤 다시 요청합니다.

429

rate_limited

비교 실행 제한 초과, 트랜잭션 롤백

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

출석 클럽 JWT (Bearer)

Table 30. /api/v1/attendance/rooms/{room}/sessions
Parameter Description

room

방 UUID

Parameter Description

from

시작 날짜 (YYYY-MM-DD), 기본 최근 120일

to

종료 날짜 (YYYY-MM-DD), 기본 오늘, 최대 366일

userId

방 내 사용자 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

[].id

String

식별자 UUID

[].roomId

String

방 UUID

[].userId

String

사용자 UUID

[].date

String

출석 날짜 (Asia/Seoul, YYYY-MM-DD)

[].placeName

String

장소 이름

[].checkIn

Object

입실 또는 퇴실 기록, null 허용

[].checkIn.photoPath

String

사진 경로

[].checkIn.at

String

기록 시각 (UTC ISO 8601)

[].checkIn.latitude

Number

위도 (도)

[].checkIn.longitude

Number

경도 (도)

[].checkIn.accuracy

Number

위치 정확도 (m)

[].checkOut

Object

입실 또는 퇴실 기록, null 허용

[].checkOut.photoPath

String

사진 경로

[].checkOut.at

String

기록 시각 (UTC ISO 8601)

[].checkOut.latitude

Number

위도 (도)

[].checkOut.longitude

Number

경도 (도)

[].checkOut.accuracy

Number

위치 정확도 (m)

[].verified

Boolean

출석 인증 성공 여부

[].verifyReason

String

판정 사유, null 허용

[].locationDistanceM

Number

사진 위치 거리 (m), null 허용

[].photoDistance

Number

내부 사진 거리 값, 확률이 아님, null 허용

[].updatedAt

String

갱신 시각 (UTC ISO 8601)

Table 31. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_date_range

조회 기간 역전 또는 초과

조건을 확인한 뒤 다시 요청합니다.

403

not_room_member

방 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

출석 클럽 JWT (Bearer)

Table 32. /api/v1/attendance/sessions/{id}
Parameter Description

id

출석 UUID

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 33. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

not_session_owner

타인 기록

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

출석 클럽 JWT (Bearer)

Table 34. /api/v1/attendance/rooms/{room}/photos
Parameter Description

room

방 UUID

Parameter Description

kind

입실 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

path

String

사진 저장 경로

Table 35. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_kind

in/out이 아닌 kind

조건을 확인한 뒤 다시 요청합니다.

413

image_too_large

8 MiB 초과

조건을 확인한 뒤 다시 요청합니다.

429

rate_limited

동시 업로드 초과

조건을 확인한 뒤 다시 요청합니다.

503

storage_unavailable

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

Authorization

출석 클럽 JWT (Bearer)

Parameter Description

path

사진 저장 경로

성공 응답

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

String

서명된 사진 URL

expiresIn

Number

URL 유효기간 (초)

Table 36. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

photo_not_found

기록에 연결된 사진 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

출석 클럽 JWT (Bearer)

Parameter Description

path

미사용 본인 사진 경로

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 37. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

photo_path_mismatch

타인 사진

조건을 확인한 뒤 다시 요청합니다.

409

photo_in_use

기록에서 사용 중인 사진

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

식단 클럽

처리 흐름은 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

Authorization

식단 클럽 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

id

String

식별자 UUID

name

String

이름

targetKcal

Number

목표 칼로리, 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

Authorization

식단 클럽 JWT (Bearer)

Path Type Description

name

String

이름, 1~16자, 지정하면 이름만 변경

targetKcal

Number

목표 칼로리, 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

id

String

식별자 UUID

name

String

이름

targetKcal

Number

목표 칼로리, 500~10000 kcal, null이면 해제

Table 38. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

실제 처리 흐름
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

Authorization

식단 클럽 JWT (Bearer)

Parameter Description

from

시작 날짜 (YYYY-MM-DD)

to

종료 날짜 (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

[].id

String

식별자 UUID

[].date

String

식단 날짜 (Asia/Seoul, YYYY-MM-DD)

[].mealType

String

끼니: breakfast, lunch, dinner, snack

[].source

String

입력 출처: ai, manual, copy

[].photoPath

String

본인이 업로드한 사진 UUID, null 허용

[].memo

String

메모, 최대 200자, null 허용

[].createdAt

String

생성 시각 (UTC ISO 8601)

[].items

Array

음식 항목 배열 (1~20개)

[].items[].id

String

식별자 UUID

[].items[].name

String

음식 이름, 1~40자

[].items[].amount

String

섭취량, 최대 20자

[].items[].kcal

Number

칼로리, 0~5000 kcal

[].items[].carbG

Number

영양소, 0~99999.9 g

[].items[].proteinG

Number

영양소, 0~99999.9 g

[].items[].fatG

Number

영양소, 0~99999.9 g

[].items[].fromAi

Boolean

AI 분석 항목 여부

[].items[].edited

Boolean

사용자 수정 여부

Table 39. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_date_range

잘못된 조회 기간

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

식단 클럽 JWT (Bearer)

Table 40. /api/v1/diet/meals/{id}
Parameter Description

id

식단 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

id

String

식별자 UUID

date

String

식단 날짜 (Asia/Seoul, YYYY-MM-DD)

mealType

String

끼니: breakfast, lunch, dinner, snack

source

String

입력 출처: ai, manual, copy

photoPath

String

본인이 업로드한 사진 UUID, null 허용

memo

String

메모, 최대 200자, null 허용

createdAt

String

생성 시각 (UTC ISO 8601)

items

Array

음식 항목 배열 (1~20개)

items[].id

String

식별자 UUID

items[].name

String

음식 이름, 1~40자

items[].amount

String

섭취량, 최대 20자

items[].kcal

Number

칼로리, 0~5000 kcal

items[].carbG

Number

영양소, 0~99999.9 g

items[].proteinG

Number

영양소, 0~99999.9 g

items[].fatG

Number

영양소, 0~99999.9 g

items[].fromAi

Boolean

AI 분석 항목 여부

items[].edited

Boolean

사용자 수정 여부

Table 41. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

meal_not_found

없거나 타인 소유 식단

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

식단 클럽 JWT (Bearer)

Path Type Description

date

String

식단 날짜 (Asia/Seoul, YYYY-MM-DD)

mealType

String

끼니: breakfast, lunch, dinner, snack

source

String

입력 출처: ai, manual, copy

photoPath

String

본인이 업로드한 사진 UUID, null 허용

memo

String

메모, 최대 200자, null 허용

items

Array

음식 항목 배열 (1~20개)

items[].name

String

음식 이름, 1~40자

items[].amount

String

섭취량, 최대 20자

items[].kcal

Number

칼로리, 0~5000 kcal

items[].carbG

Number

영양소, 0~99999.9 g

items[].proteinG

Number

영양소, 0~99999.9 g

items[].fatG

Number

영양소, 0~99999.9 g

items[].fromAi

Boolean

AI 분석 항목 여부

items[].edited

Boolean

사용자 수정 여부

성공 응답

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

id

String

식별자 UUID

date

String

식단 날짜 (Asia/Seoul, YYYY-MM-DD)

mealType

String

끼니: breakfast, lunch, dinner, snack

source

String

입력 출처: ai, manual, copy

photoPath

String

본인이 업로드한 사진 UUID, null 허용

memo

String

메모, 최대 200자, null 허용

createdAt

String

생성 시각 (UTC ISO 8601)

items

Array

음식 항목 배열 (1~20개)

items[].id

String

식별자 UUID

items[].name

String

음식 이름, 1~40자

items[].amount

String

섭취량, 최대 20자

items[].kcal

Number

칼로리, 0~5000 kcal

items[].carbG

Number

영양소, 0~99999.9 g

items[].proteinG

Number

영양소, 0~99999.9 g

items[].fatG

Number

영양소, 0~99999.9 g

items[].fromAi

Boolean

AI 분석 항목 여부

items[].edited

Boolean

사용자 수정 여부

Table 42. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

400

meal_date_in_future

미래 날짜

조건을 확인한 뒤 다시 요청합니다.

400

meal_date_too_old

7일보다 오래된 날짜

조건을 확인한 뒤 다시 요청합니다.

400

photo_not_found

본인 사진 아님 또는 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

식단 클럽 JWT (Bearer)

Table 43. /api/v1/diet/meals/{id}
Parameter Description

id

식단 UUID

Path Type Description

date

String

식단 날짜 (Asia/Seoul, YYYY-MM-DD)

mealType

String

끼니: breakfast, lunch, dinner, snack

source

String

입력 출처: ai, manual, copy

photoPath

String

본인이 업로드한 사진 UUID, null 허용

memo

String

메모, 최대 200자, null 허용

items

Array

음식 항목 배열 (1~20개)

items[].name

String

음식 이름, 1~40자

items[].amount

String

섭취량, 최대 20자

items[].kcal

Number

칼로리, 0~5000 kcal

items[].carbG

Number

영양소, 0~99999.9 g

items[].proteinG

Number

영양소, 0~99999.9 g

items[].fatG

Number

영양소, 0~99999.9 g

items[].fromAi

Boolean

AI 분석 항목 여부

items[].edited

Boolean

사용자 수정 여부

성공 응답

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

id

String

식별자 UUID

date

String

식단 날짜 (Asia/Seoul, YYYY-MM-DD)

mealType

String

끼니: breakfast, lunch, dinner, snack

source

String

입력 출처: ai, manual, copy

photoPath

String

본인이 업로드한 사진 UUID, null 허용

memo

String

메모, 최대 200자, null 허용

createdAt

String

생성 시각 (UTC ISO 8601)

items

Array

음식 항목 배열 (1~20개)

items[].id

String

식별자 UUID

items[].name

String

음식 이름, 1~40자

items[].amount

String

섭취량, 최대 20자

items[].kcal

Number

칼로리, 0~5000 kcal

items[].carbG

Number

영양소, 0~99999.9 g

items[].proteinG

Number

영양소, 0~99999.9 g

items[].fatG

Number

영양소, 0~99999.9 g

items[].fromAi

Boolean

AI 분석 항목 여부

items[].edited

Boolean

사용자 수정 여부

Table 44. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

404

meal_not_found

없거나 타인 소유 식단

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

식단 클럽 JWT (Bearer)

Table 45. /api/v1/diet/meals/{id}
Parameter Description

id

식단 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

Authorization

식단 클럽 JWT (Bearer)

Parameter Description

limit

최대 항목 수, 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

[].name

String

음식 이름, 1~40자

[].amount

String

섭취량, 최대 20자

[].kcal

Number

칼로리, 0~5000 kcal

[].carbG

Number

영양소, 0~99999.9 g

[].proteinG

Number

영양소, 0~99999.9 g

[].fatG

Number

영양소, 0~99999.9 g

[].times

Number

최근 60일 기록 횟수

Table 46. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_limit

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

Authorization

식단 클럽 JWT (Bearer)

Part Description

file

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

path

String

사진 UUID

Table 47. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

unsupported_mime

JPEG 헤더 형식 아님

조건을 확인한 뒤 다시 요청합니다.

400

invalid_image

이미지 검증 실패

조건을 확인한 뒤 다시 요청합니다.

413

image_too_large

파일 크기 초과

조건을 확인한 뒤 다시 요청합니다.

503

photo_storage_unavailable

사진 저장 장애

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

식단 클럽 JWT (Bearer)

Table 48. /api/v1/diet/photos/{id}
Parameter Description

id

사진 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

Content-Type

image/jpeg

Cache-Control

no-store

Table 49. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

photo_not_found

없거나 타인 소유 사진

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

식단 클럽 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

used

Number

서울 오늘 사용 횟수

limit

Number

일일 한도, 5회

subscribed

Boolean

호환용 필드, 항상 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

Authorization

식단 클럽 JWT (Bearer)

Path Type Description

imageBase64

String

Base64 이미지, 최대 150만 자

mimeType

String

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

items

Array

분석한 음식 항목 배열, 최대 20개

note

String

AI 추정 안내

items[].name

String

음식 이름, 1~40자

items[].amount

String

섭취량, 최대 20자

items[].kcal

Number

칼로리, 0~5000 kcal

items[].carbG

Number

영양소, 0~99999.9 g

items[].proteinG

Number

영양소, 0~99999.9 g

items[].fatG

Number

영양소, 0~99999.9 g

items[].fromAi

Boolean

AI 분석 항목 여부

items[].edited

Boolean

사용자 수정 여부

Table 50. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

429

quota_exceeded

오늘 5회 한도 소진

다음 서울 날짜에 다시 요청합니다.

422

no_food

음식 없음 또는 모델 거절, 사용량 유지

조건을 확인한 뒤 다시 요청합니다.

502

analysis_unavailable

외부 호출 실패, 예약 날짜의 사용량 환급

조건을 확인한 뒤 다시 요청합니다.

503

analysis_not_configured

분석 기능 설정 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

식단 클럽 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

times

Object

끼니별 알림 시각

times.breakfast

String

서울 알림 시각 (HH:mm:ss), null이면 비활성

times.lunch

String

서울 알림 시각 (HH:mm:ss), null이면 비활성

times.dinner

String

서울 알림 시각 (HH:mm:ss), null이면 비활성

agreed

Boolean

알림 수신 동의 여부

오류와 클라이언트 처리

보호 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

Authorization

식단 클럽 JWT (Bearer)

Path Type Description

times

Object

끼니별 알림 시각

times.breakfast

String

서울 알림 시각 (HH:mm:ss), null이면 비활성

times.lunch

String

서울 알림 시각 (HH:mm:ss), null이면 비활성

times.dinner

String

서울 알림 시각 (HH:mm:ss), null이면 비활성

agreed

Boolean

알림 수신 동의 여부

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 51. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

실제 처리 흐름
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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

운동 클럽

처리 흐름은 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

Authorization

운동 클럽 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

id

String

식별자 UUID

name

String

이름

오류와 클라이언트 처리

보호 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

Authorization

운동 클럽 JWT (Bearer)

Path Type Description

name

String

이름, 공백만인 값 제외, 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

id

String

식별자 UUID

name

String

이름

Table 52. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

400

invalid_name

공백 제거 후 빈 이름

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 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

[].id

String

식별자 UUID

[].code

String

초대 코드

[].name

String

방 이름

[].capacity

Number

방 정원 (명)

[].hostId

String

방장 UUID

[].createdAt

String

생성 시각 (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

Authorization

운동 클럽 JWT (Bearer)

Path Type Description

name

String

이름, 공백만인 값 제외, 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

id

String

식별자 UUID

code

String

초대 코드

name

String

방 이름

capacity

Number

방 정원 (명)

hostId

String

방장 UUID

createdAt

String

생성 시각 (UTC ISO 8601)

Table 53. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

409

room_limit

참여 방 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

Authorization

운동 클럽 JWT (Bearer)

Parameter Description

code

초대 코드

성공 응답

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

room

Object

방 정보

memberCount

Number

현재 멤버 수

hostName

String

방장 이름

alreadyMember

Boolean

현재 참여 여부

room.id

String

식별자 UUID

room.code

String

초대 코드

room.name

String

방 이름

room.capacity

Number

방 정원 (명)

room.hostId

String

방장 UUID

room.createdAt

String

생성 시각 (UTC ISO 8601)

Table 54. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

room_not_found

초대 코드에 해당하는 방 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 55. /api/v1/workout/rooms/{room}
Parameter Description

room

방 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

members

Array

멤버 배열

checkIns

Array

최근 운동 인증 배열, 최대 1000건

members[].userId

String

멤버 UUID

members[].name

String

이름

members[].joinedAt

String

가입 시각 (UTC ISO 8601)

checkIns[].id

String

식별자 UUID

checkIns[].roomId

String

방 UUID

checkIns[].userId

String

사용자 UUID

checkIns[].date

String

운동 인증 날짜 (Asia/Seoul, YYYY-MM-DD)

checkIns[].photoPaths

Array

인증 사진 경로 배열

checkIns[].createdAt

String

생성 시각 (UTC ISO 8601)

Table 56. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

not_member

방 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

404

room_not_found

방 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 57. /api/v1/workout/rooms/{room}/members
Parameter Description

room

방 UUID

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 58. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

409

already_member

이미 참여 중

조건을 확인한 뒤 다시 요청합니다.

409

room_full

정원 초과

조건을 확인한 뒤 다시 요청합니다.

409

room_limit

참여 방 제한 초과

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 59. /api/v1/workout/rooms/{room}/members/me
Parameter Description

room

방 UUID

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 60. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

404

room_not_found

방 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 61. /api/v1/workout/rooms/{room}/check-ins
Parameter Description

room

방 UUID

Part Description

photos

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

id

String

식별자 UUID

roomId

String

방 UUID

userId

String

사용자 UUID

date

String

운동 인증 날짜 (Asia/Seoul, YYYY-MM-DD)

photoPaths

Array

인증 사진 경로 배열

createdAt

String

생성 시각 (UTC ISO 8601)

Table 62. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_photo_count

파일 수 또는 파트 구성 오류

조건을 확인한 뒤 다시 요청합니다.

400

invalid_image

JPEG 검증 실패

조건을 확인한 뒤 다시 요청합니다.

409

already_checked_in

오늘 이미 인증함

조건을 확인한 뒤 다시 요청합니다.

413

image_too_large

사진 또는 요청 크기 초과

조건을 확인한 뒤 다시 요청합니다.

429

rate_limited

동시 업로드 초과

조건을 확인한 뒤 다시 요청합니다.

503

storage_unavailable

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

Authorization

운동 클럽 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

[]

Array

오늘 운동 인증한 방 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

Authorization

운동 클럽 JWT (Bearer)

Table 63. /api/v1/workout/rooms/{room}/check-ins/me
Parameter Description

room

방 UUID

Parameter Description

from

시작 날짜 (YYYY-MM-DD)

to

종료 날짜 (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

[].id

String

식별자 UUID

[].roomId

String

방 UUID

[].userId

String

사용자 UUID

[].date

String

운동 인증 날짜 (Asia/Seoul, YYYY-MM-DD)

[].photoPaths

Array

인증 사진 경로 배열

[].createdAt

String

생성 시각 (UTC ISO 8601)

Table 64. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_date_range

날짜 역전 또는 366일 초과

조건을 확인한 뒤 다시 요청합니다.

403

not_member

방 멤버가 아님

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 65. /api/v1/workout/check-ins/{id}
Parameter Description

id

운동 인증 UUID

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 66. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

403

not_owner

타인 인증

조건을 확인한 뒤 다시 요청합니다.

404

check_in_not_found

인증 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Parameter Description

path

사진 저장 경로

성공 응답

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

String

서명된 사진 URL

expiresIn

Number

URL 유효기간 (초)

Table 67. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_photo_path

사진 경로 오류

조건을 확인한 뒤 다시 요청합니다.

404

photo_not_found

인증에 연결되지 않은 사진

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Parameter Description

date

조회 날짜 (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

enabled

Boolean

루틴 활성 여부

items

Array

운동 종목 배열

checkedItemIds

Array

조회 날짜에 체크한 종목 UUID 배열

items[].id

String

식별자 UUID

items[].weekday

Number

요일: 일요일 0~토요일 6

items[].name

String

운동 종목, 1~30자

items[].position

Number

표시 순서, 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

Authorization

운동 클럽 JWT (Bearer)

Path Type Description

enabled

Boolean

루틴 활성 여부

items

Array

운동 종목 배열, 최대 70개

items[].id

String

식별자 UUID

items[].weekday

Number

요일: 일요일 0~토요일 6

items[].name

String

운동 종목, 1~30자

items[].position

Number

표시 순서, 0~69

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 68. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

400

invalid_routine

중복 종목 ID

조건을 확인한 뒤 다시 요청합니다.

403

invalid_routine_owner

타인 종목 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

Authorization

운동 클럽 JWT (Bearer)

Table 69. /api/v1/workout/me/routine/items/{item}/checks/today
Parameter Description

item

운동 종목 UUID

Path Type Description

checked

Boolean

오늘 체크 여부

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 70. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

400

invalid_request

입력 제약 위반

입력값을 수정합니다.

403

not_owner

타인 종목

조건을 확인한 뒤 다시 요청합니다.

404

routine_item_not_found

종목 없음

조건을 확인한 뒤 다시 요청합니다.

실제 처리 흐름
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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

개인 운동 기록

사진 인증·방 참여·루틴 체크와 독립적인 개인 기록입니다. 방을 나가도 기록과 직접 만든 운동은 유지됩니다. 기본 운동은 공유하고 직접 만든 운동·즐겨찾기·기록은 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

Authorization

운동 클럽 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

[].id

String

운동 UUID

[].name

String

운동 이름

[].bodyPart

String

운동 부위

[].type

String

STRENGTH, BODYWEIGHT, CARDIO, TIMED

[].custom

Boolean

본인이 만든 운동 여부

[].favorite

Boolean

본인의 즐겨찾기 여부

Table 71. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

401

not_authenticated

JWT 누락·인증 실패

다시 인증합니다.

403

forbidden

다른 클럽 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

Authorization

운동 클럽 JWT (Bearer)

Path Type Description

name

String

운동 이름 1~60자, 공백 이름 금지

bodyPart

String

운동 부위 1~20자

type

String

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

id

String

운동 UUID

name

String

공백을 정리한 운동 이름

bodyPart

String

운동 부위

type

String

입력 유형

custom

Boolean

본인이 만든 운동 여부

favorite

Boolean

본인의 즐겨찾기 여부

Table 72. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

401

not_authenticated

JWT 누락·인증 실패

다시 인증합니다.

403

forbidden

다른 클럽 JWT

운동 클럽 계정으로 인증합니다.

400

invalid_request

필드 제약·자료형·날짜 형식 위반

입력값을 수정합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 73. /api/v1/workout/exercises/{id}/favorite
Parameter Description

id

기본 또는 본인 운동 UUID

Path Type Description

favorite

Boolean

즐겨찾기 설정 여부, 같은 값 재요청은 멱등

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 74. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

401

not_authenticated

JWT 누락·인증 실패

다시 인증합니다.

403

forbidden

다른 클럽 JWT

운동 클럽 계정으로 인증합니다.

400

invalid_request

필드 제약·자료형·날짜 형식 위반

입력값을 수정합니다.

403

not_owner

다른 사용자의 운동·기록 지정

본인 자료를 선택합니다.

404

exercise_not_found

지정한 운동이 없음

운동 목록을 다시 조회합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Parameter Description

from

조회 시작 날짜, YYYY-MM-DD

to

조회 종료 날짜, 시작일 포함 최대 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

[].id

String

기록 UUID

[].version

Number

기록 버전

[].date

String

서울 기준 운동 날짜

[].durationSeconds

Number

총 운동 시간, 초

[].note

String

메모

[].exercises

Array

운동별 세트·시간·거리, 아래 입력 계약 참조

[].createdAt

String

생성 절대 시각

[].updatedAt

String

수정 절대 시각

Table 75. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

401

not_authenticated

JWT 누락·인증 실패

다시 인증합니다.

403

forbidden

다른 클럽 JWT

운동 클럽 계정으로 인증합니다.

400

invalid_request

필드 제약·자료형·날짜 형식 위반

입력값을 수정합니다.

400

invalid_record

기간 범위·미래 날짜·중복 운동·유형별 측정값 위반

입력값과 조회 기간을 수정합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 76. /api/v1/workout/me/records/{id}
Parameter Description

id

클라이언트가 생성한 기록 UUID, 재시도에도 동일한 값

Path Type Description

version

Number

새 기록은 0, 수정은 마지막 응답의 버전

date

String

2000-01-01~서버 서울 오늘 날짜

durationSeconds

Number

총 운동 시간, 0~86400초

note

String

메모, 최대 1000자, 빈 문자열 허용

sourceRecords

Array

하루 통합 저장 시 날짜의 전체 원본 id/version 목록, 최대 100개. 빈 배열은 기록 없는 날짜의 시작. 생략/null은 기존 개별 기록 저장

exercises

Array

중복 없는 운동 1~30개

exercises[].exerciseId

String

기본 또는 본인 운동 UUID

exercises[].durationSeconds

Number

운동 시간: 근력·맨몸은 0, 유산소·시간은 1~86400초

exercises[].distanceKm

Number

유산소 거리 0~1000km, 다른 유형은 0

exercises[].sets

Array

근력·맨몸은 1~30개, 다른 유형은 빈 배열

exercises[].sets[].weightKg

Number

0~2000kg, 맨몸은 0

exercises[].sets[].reps

Number

1~1000회 정수

exercises[].sets[].warmup

Boolean

워밍업 여부, 볼륨에서 제외

성공 응답

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

id

String

기록 UUID

version

Number

저장 후 버전

date

String

운동 날짜

durationSeconds

Number

총 운동 시간, 초

note

String

메모

exercises

Array

저장한 운동 배열, 요청과 같은 측정 필드

createdAt

String

생성 절대 시각

updatedAt

String

수정 절대 시각

Table 77. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

401

not_authenticated

JWT 누락·인증 실패

다시 인증합니다.

403

forbidden

다른 클럽 JWT

운동 클럽 계정으로 인증합니다.

400

invalid_request

필드 제약·자료형·날짜 형식 위반

입력값을 수정합니다.

403

not_owner

다른 사용자의 운동·기록 지정

본인 자료를 선택합니다.

404

exercise_not_found

지정한 운동이 없음

운동 목록을 다시 조회합니다.

400

invalid_record

기간 범위·미래 날짜·중복 운동·유형별 측정값 위반

입력값과 조회 기간을 수정합니다.

404

record_not_found

수정·삭제 대상이 없음

기록 목록을 갱신합니다.

409

record_conflict

다른 내용으로 저장된 버전과 요청 버전이 다름

임시 내용을 보관하고 최신 기록을 조회합니다.

실제 처리 흐름
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

Authorization

운동 클럽 JWT (Bearer)

Table 78. /api/v1/workout/me/records/{id}
Parameter Description

id

삭제할 기록 UUID

Parameter Description

version

마지막 조회한 버전

성공 응답

HTTP 204. 본문이 없습니다.

HTTP/1.1 204 No Content
Table 79. 오류와 클라이언트 처리
HTTP 상태 code 발생 조건 클라이언트 처리

401

not_authenticated

JWT 누락·인증 실패

다시 인증합니다.

403

forbidden

다른 클럽 JWT

운동 클럽 계정으로 인증합니다.

400

invalid_request

필드 제약·자료형·날짜 형식 위반

입력값을 수정합니다.

403

not_owner

다른 사용자의 운동·기록 지정

본인 자료를 선택합니다.

404

record_not_found

수정·삭제 대상이 없음

기록 목록을 갱신합니다.

409

record_conflict

다른 내용으로 저장된 버전과 요청 버전이 다름

임시 내용을 보관하고 최신 기록을 조회합니다.

실제 처리 흐름
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

type

String

문제 유형 URI

title

String

오류 제목

status

Number

HTTP 상태 코드

detail

String

표시용 오류 설명, 분기에 사용하지 않습니다

instance

String

요청 경로

code

String

클라이언트 분기용 오류 코드

운동 기록 임시 저장

임시 기록은 완료 기록과 분리해 사용자별로 하나씩 서버에 보관합니다. 완료 기록 목록·운동 통계에 포함하지 않습니다. 같은 운동 클럽 사용자로 로그인하면 기기와 관계없이 이어 쓸 수 있습니다. 입력 중인 빈 문자열과 미완성 숫자도 문자열로 보관하며, 실제 날짜·운동·측정값 검증은 완료 기록 저장 시 수행합니다. 요청 크기는 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

revision

Number

임시 기록 버전, 변경 요청의 기대 버전으로 사용

draft

Object

현재 임시 기록, 저장 요청의 draft와 동일한 형식

updatedAt

String

서버 저장 절대 시각

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 44

{"revision":0,"draft":null,"updatedAt":null}
Table 80. 오류와 클라이언트 처리
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

revision

Number

기대 버전, 최초 생성은 0이며 이후 조회·저장 응답의 값을 사용

draft.id

String

작성 중인 운동 기록 UUID

draft.version

Number

완료 기록의 기반 버전, 신규 기록은 0

draft.date

String

작성 중인 날짜 문자열, 최대 10자, 빈 문자열 허용

draft.minutes

String

총 운동 시간 입력 문자열, 단위 분, 최대 32자

draft.note

String

메모 문자열, 최대 1000자

draft.exercises[].exerciseId

String

선택한 운동 UUID, 운동은 최대 30개

draft.exercises[].minutes

String

운동별 시간 입력 문자열, 분, 최대 32자

draft.exercises[].distanceKm

String

거리 입력 문자열, km, 최대 32자

draft.exercises[].sets[].weightKg

String

중량 입력 문자열, kg, 최대 32자, 세트 최대 30개

draft.exercises[].sets[].reps

String

횟수 입력 문자열, 최대 32자

draft.exercises[].sets[].warmup

Boolean

워밍업 여부

draft.sourceRecords

Null

하루 통합 대상 원본 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

revision

Number

저장 후 버전, 같은 본문의 재시도는 증가하지 않음

draft

Object

서버에 보관한 작성 내용

updatedAt

String

서버 저장 절대 시각

Table 81. 오류와 클라이언트 처리
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

id

삭제할 임시 기록 UUID

revision

기대 임시 기록 버전

성공 응답

204이며 본문이 없습니다. 이미 임시 기록이 없으면 동일한 성공을 반환합니다. 내용은 삭제하고 revision은 증가시켜 늦은 저장의 복원을 막습니다. 삭제 후 조회한 revision으로 새 기록을 작성합니다. 완료 기록 저장은 같은 Workout 트랜잭션에서 일치하는 ID와 기반 version의 임시 기록을 정리합니다. 이전 완료 요청의 재시도는 이후 새로 작성한 편집 초안을 지우지 않습니다.

HTTP/1.1 204 No Content
Table 82. 오류와 클라이언트 처리
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