Skip to content

Travel API Spec

wcorn edited this page Oct 19, 2026 · 36 revisions

API 설계: 여행 (Travel)

확정 명세 v2.2 · v2.1 · v2.0 · 유스케이스 · 아키텍처 · 데이터 모델

Base: /api/travel. 인증: JWT(전 엔드포인트). 응답은 orino 공통 envelope { code, data }(CustomResponseCode), 에러는 { code: "GLB-ERR-XXX", message }. 날짜는 YYYY-MM-DD, 시각은 HH:mm — 둘 다 벽시계 값이며 UTC 오프셋을 붙이지 않는다(§4.1). 절대시각(scheduledAt 등)만 ISO-8601 UTC. v2.1: 벽시계의 기준이 여행 타임존 → 그 날짜의 기준 도시 타임존이다. 값의 형식은 바뀌지 않는다.

v2.1 변경 요약

변경 내용
여행 생성·수정 destinationName·timezone·currency·lat·lng 제거 → legs[](도시 + 일수) 입력
신규 GET/PUT /trips/{id}/days · PUT /days/{dayId} · GET /trips/{id}/city-legs
신규 숙소 CRUD /trips/{id}/stays · /stays/{stayId}
보드 응답 trip.timezone 제거, days[]에 baseCity·stay·cityMemo 추가, legs[] → travelTimes[]
재명명 GET /trips/{id}/legs → GET /trips/{id}/travel-time (구간 Leg와 이름이 충돌한다 — v2.1 §2.4)

(#1208) 이동은 다시 한 번 바뀐다. 자동 계산이 사라지면서 travelTimes[] → moves[], GET /travel-time → PUT·DELETE /moves. 아래 본문은 최신 상태다. | 날씨 | 여행 좌표 1곳 → 도시 단위 조회·캐시 | | 환율 | 기준 통화를 오늘 날짜의 기준 도시에서 파생 |

v2.2 변경 요약 (경비 · 준비)

변경 내용
신규 준비 /trips/{id}/prep · /prep/items/{itemId} · 순서 PUT /trips/{id}/prep/order
신규 경비 GET /trips/{id}/expenses · 예산 PUT /trips/{id}/budget
(v2.3) 신규 POST·PATCH·DELETE /trips/{id}/expenses{/id} — 경비가 여행 소유가 되면서 쓰기가 여행으로 온다(§11)
신규(가계부) POST /api/ledger/transactions에 tripId — (v2.3) 폐기. 가계부가 없어진다
신규(여행) POST /trips/{tripId}/expenses/attach·/detach(#1327) — (v2.3) 폐기. 붙일 원장이 없다
요약·보드 summary.ongoing에 prep(진행률·기한 지남) · expense(예산·쓴 돈) 추가. 예산 미설정이면 budget: null — 0을 내리지 않는다
요약 trips[](진행 중·예정) + completedCount — 사이드바 여행 트리와 폴백 화면이 함께 읽는다(§2.1)
알림 push_notification.type에 PREP_REMINDER

경비는 쓰기 엔드포인트를 갖지 않는다. — (v2.3) 뒤집혔다. v2.2는 지출 입력·수정·삭제를 전부 가계부 API로 보냈고 여행이 가진 쓰기는 예산 하나뿐이었다. 가계부 제거로 경비 쓰기가 전부 여행으로 온다(D-43).

1. 엔드포인트 요약

그룹 메서드 경로 단계
요약 GET /api/travel/summary 1
여행 GET /api/travel/trips?status= 1
여행 POST /api/travel/trips 1
여행 GET /api/travel/trips/{tripId} 1
여행 PUT /api/travel/trips/{tripId} 1
여행 DELETE /api/travel/trips/{tripId} 1
여행 GET /api/travel/trips/{tripId}/shrink-preview?endDate= 1
날짜 GET /api/travel/trips/{tripId}/days v2.1-1
날짜 PUT /api/travel/days/{dayId} v2.1-1
날짜 GET /api/travel/trips/{tripId}/city-legs v2.1-1
숙소 GET /api/travel/trips/{tripId}/stays v2.1-3
숙소 POST /api/travel/trips/{tripId}/stays v2.1-3
숙소 PUT /api/travel/stays/{stayId} v2.1-3
숙소 DELETE /api/travel/stays/{stayId} v2.1-3
보드 GET /api/travel/trips/{tripId}/board 1
일정 POST /api/travel/trips/{tripId}/activities 1
일정 GET /api/travel/activities/{activityId} 1
일정 PUT /api/travel/activities/{activityId} 1
일정 DELETE /api/travel/activities/{activityId} 1
일정 PUT /api/travel/trips/{tripId}/activities/order 1
일정 PUT /api/travel/trips/{tripId}/activities/swap (#1368)
장소 GET /api/travel/places/search?q=&tripId=&city= 2 (city는 v2.1-3)
장소 GET /api/travel/places/cities?q= 2
장소 GET /api/travel/places/{placeId} 2
장소 POST /api/travel/places 2
푸시 GET /api/travel/push/public-key 3
푸시 POST /api/travel/push/subscriptions 3
푸시 DELETE /api/travel/push/subscriptions 3
푸시 POST /api/travel/push/test 3
도구 GET /api/travel/trips/{tripId}/weather 4
도구 GET /api/travel/fx?base=&quote= 4
기록 PUT /api/travel/activities/{activityId}/log 4
기록 POST /api/travel/activities/{activityId}/photos 4
기록 DELETE /api/travel/photos/{photoId} 4
이미지 POST /api/travel/images/upload-url 4
준비 GET /api/travel/trips/{tripId}/prep v2.2-1
준비 POST /api/travel/trips/{tripId}/prep/items v2.2-1
준비 PATCH /api/travel/prep/items/{itemId} v2.2-1
준비 DELETE /api/travel/prep/items/{itemId} v2.2-1
준비 PUT /api/travel/trips/{tripId}/prep/order v2.2-1 (자르기 ④)
경비 GET /api/travel/trips/{tripId}/expenses v2.2-2
경비 PUT /api/travel/trips/{tripId}/budget v2.2-2

2. 요약 · 여행

GET /api/travel/summary

/select 화면의 여행 카드와 S-01 홈이 함께 쓴다.

// Response.data
{
  "ongoing": {                                 // 없으면 null
    "id": 3, "title": "일본 9박 10일", "boardPath": "/travel/trips/3/board",
    "startDate": "2026-10-24", "endDate": "2026-11-02", "activityCount": 27,
    "cities": {                                // (v2.1) 도시 요약 — 아래 참조
      "names": ["오사카", "교토"], "count": 2,
      "today": "교토", "movedFrom": "오사카",   // 오늘 옮기는 날이면 어제 도시가 온다
      "todayDayIndex": 4, "todayTimezone": "Asia/Tokyo", "todayCurrency": "JPY"
    }
  },
  "next": {                                    // 다음 예정 여행. 없으면 null
    "id": 3, "title": "도쿄 3박 4일", "destinationName": "도쿄",
    "startDate": "2026-10-24", "endDate": "2026-10-27",
    "dDay": 78, "activityCount": 13,
    "cities": { "names": ["도쿄"], "count": 1, "today": null, "movedFrom": null,
                "todayDayIndex": null, "todayTimezone": null, "todayCurrency": null }
  },
  "recentCompleted": { "id": 2, "title": "오사카 2박 3일", "endDate": "2026-05-11", "activityCount": 9 }
}
  • 세 필드가 전부 null이면 FE는 "여행 만들기" 단일 버튼만 그린다(§S-01).

2.1 trips[] — 사이드바 여행 트리 (v2.2)

사이드바가 여행을 펼치고(화면 §10.8), 여행을 못 정했을 때의 폴백 화면이 같은 배열을 그린다. 두 화면이 같은 배열을 읽는다 — 사이드바에는 있는데 폴백에는 없는 여행이 생기면 고를 수 없는 여행이 사이드바에 남는다.

// Response.data 에 추가
{
  "trips": [                                   // 진행 중 → 예정, 시작일 오름차순
    { "id": 3, "title": "일본 가을", "status": "ONGOING",
      "startDate": "2026-10-24", "endDate": "2026-10-29",
      "dDay": null, "dayNumber": 4,            // 진행 중이면 dayNumber, 예정이면 dDay
      "prep": { "done": 18, "total": 24, "overdueCount": 1 },
      "expense": { "budget": 800000, "spent": 412000 }   // 예산 미설정이면 budget: null
    }
  ],
  "completedCount": 2                          // 「다녀온 여행 2개」 한 줄
}
  • 진행 중·예정만 내린다. 다녀온 여행은 개수만 준다 — 사이드바에 늘어놓으면 시간이 갈수록 사이드바가 목록 화면이 된다(D-39)
  • prep·expense는 여행마다 집계 두 번이다. 진행 중·예정이 두어 개라 문제되지 않지만, 여행 수에 비례하는 유일한 자리라 trips[]에만 싣는다(/trips 목록 응답에는 넣지 않는다 — 다녀온 여행까지 세게 된다)
  • dDay와 dayNumber는 동시에 차지 않는다. 진행 중이면 4일차, 예정이면 D-49를 그린다
  • 준비 항목이 하나도 없는 여행은 prep: { done: 0, total: 0, overdueCount: 0 }이다. null이 아니다 — 화면이 「0/0」을 그릴지 줄을 숨길지는 화면이 정한다

cities — 도시 요약 (v2.1)

여행을 고르는 자리(/select · S-01 · S-02)가 함께 쓴다. 줄이는 규칙은 화면이 갖고 서버는 줄이기 전의 사실만 준다 — 4개 초과 생략(오사카 → 교토 → … → 도쿄)은 FE 포맷터 한 곳에 있다.

필드 뜻
names 구간 순서의 도시 이름. 연속 중복은 이미 접혀 있다(도쿄 → 닛코 → 도쿄는 셋 — 사이가 끊기면 다른 구간이다)
count 서로 다른 도시 수. 같은 도시를 다시 방문해도 하나
today · movedFrom 오늘의 기준 도시와, 오늘 바뀌었다면 어제의 도시. 진행 중이 아니면 둘 다 null
todayDayIndex · todayTimezone · todayCurrency 오늘이 며칠째이고 그 도시의 타임존·통화는 무엇인지
  • 이 값들은 목록·요약이 상태 판정을 위해 이미 읽어 둔 날짜별 기준 도시에서 나온다 — 추가 조회가 0이다. 여행마다 /city-legs를 부르면 그때부터 N+1이다.

GET /api/travel/trips?status=UPCOMING|ONGOING|COMPLETED

status 생략 시 전체. 정렬은 서버가 확정한다 — 예정·진행 중은 startDate 오름차순, 완료는 endDate 내림차순(§S-02).

// Response.data
{
  "counts": { "upcoming": 1, "ongoing": 0, "completed": 2 },   // 탭 라벨 뒤 건수
  "trips": [
    { "id": 3, "title": "도쿄 3박 4일", "destinationName": "도쿄",
      "startDate": "2026-10-24", "endDate": "2026-10-27",
      "status": "UPCOMING", "dDay": 78, "activityCount": 13,
      "cities": { "names": ["도쿄"], "count": 1, "today": null, "movedFrom": null,
                  "todayDayIndex": null, "todayTimezone": null, "todayCurrency": null } }
  ]
}

POST /api/travel/trips — v2.1 구간 입력으로 교체

// Request (v2.1)
{
  "title": "일본 9박 10일",        // 필수. 자동 기본값을 넣지 않는다
  "startDate": "2026-10-24",
  "endDate": "2026-11-02",
  "legs": [                        // 구간 = 도시 + 일수. 순서가 곧 방문 순서
    { "cityPlaceId": 21, "days": 3 },              // 이미 담아 둔 도시
    { "cityGooglePlaceId": "ChIJ_kyoto", "days": 1 },  // 검색 결과 그대로
    { "cityPlaceId": 23, "days": 1 }
  ],
  "defaultNotifyMinutes": 15
}

검증 — endDate >= startDate, title 1~50자, legs는 1개 이상, 각 days >= 1, cityPlaceId는 place_kind = CITY인 장소(아니면 400 TRAVEL-ERR-016).

  • 구간의 도시는 cityPlaceId와 cityGooglePlaceId 중 정확히 하나로 지정한다. 둘 다 없거나 둘 다 있으면 400.
    • cityGooglePlaceId는 검색 결과를 그대로 보내는 길이다. 서버가 담고(upsert) place_kind = CITY로 승격한다 — 일정 담기와 같은 패턴이다. 고르기 전에 저장부터 하라고 하면 저장했다가 취소한 도시가 쌓인다.
  • sum(days)와 기간이 달라도 저장한다(v2.1 §3.1). 부족하면 마지막 구간 도시를 남은 날짜에 이어 쓰고, 초과하면 뒤 구간이 잘린다. 400으로 막지 않는다.
  • 서버는 legs를 날짜로 전개해 기간 전체의 trip_day를 한 트랜잭션에서 생성한다.
  • 타임존·통화·좌표는 받지 않는다. 도시 장소에서 파생한다.
v2.0 요청 (참고)
{ "title": "…", "destinationName": "도쿄", "destinationPlaceId": 12,
  "startDate": "…", "endDate": "…", "timezone": "Asia/Tokyo", "currency": "JPY",
  "lat": 35.6762, "lng": 139.6503, "defaultNotifyMinutes": 15 }

PUT /api/travel/trips/{tripId}

전체 수정. 기간 단축 시 잘리는 일정은 보관함으로 이동한다(§1.9) — 클라이언트가 미리 개수를 알아야 하므로 확인 모달용 엔드포인트를 따로 둔다.

// Request (생성과 동일 + )
{ "morningSummaryEnabled": true, "confirmArchive": true }
  • 기간이 줄어드는데 confirmArchive가 false/생략이면 409로 거부하고 이동 예정 건수를 돌려준다. 실수로 일정을 잃지 않게 하는 안전장치다.
  • 타임존이 바뀌면 일정 시각은 그대로 두고 PENDING 알림을 전량 재계산한다(§4.1).

v2.1 추가 규칙

  • legs를 보내면 날짜 전체를 다시 전개한다. 기존 trip_day의 city_memo는 날짜 기준으로 보존한다(도시가 바뀌어도 그 날짜에 적어 둔 메모는 살린다).
  • 기간을 늘리면 새 날짜가 마지막 날의 기준 도시를 상속한다.
  • 기간을 줄이면 잘린 날짜의 일정이 보관함으로 가고, 걸쳐 있던 숙소의 체크아웃일을 새 종료일로 당긴다. in >= out이 되는 숙소는 삭제한다.

GET /api/travel/trips/{tripId}/shrink-preview?startDate=&endDate=

// Response.data (v2.1 — 숙소 영향 추가)
{ "movedActivityCount": 4, "shrunkStayCount": 1, "removedStayCount": 0 }

ConfirmDialog 본문: "잘리는 날짜의 일정 4개가 미배정 보관함으로 이동하고, 걸쳐 있던 숙소는 기간이 줄어듭니다."

DELETE /api/travel/trips/{tripId}

일정·기록·사진·예약 알림이 함께 정리된다(FK CASCADE + MinIO 정리).


3. 보드

GET /api/travel/trips/{tripId}/board

주 화면의 단일 조회. 날짜 탭·일정·이동·날씨 요약을 한 번에 내려준다. 화면이 N+1 호출을 하지 않게 하고, 오프라인 캐시가 응답 하나로 성립하게 하려는 설계다(§4.6).

// Response.data — v2.1
{
  "trip": {
    "id": 3, "title": "일본 9박 10일",
    "startDate": "2026-10-24", "endDate": "2026-11-02",
    "status": "ONGOING", "recordMode": false,        // status=COMPLETED 이면 true
    "cityCount": 6, "countryCount": 1,               // 카드 메타 (v2.1)
    "singleCity": false                              // true 면 날짜 탭을 "N일차"로 그린다 (v2.1)
  },
  "days": [                                          // 기간 전체. 마지막에 보관함이 붙는다(FE 처리)
    { "dayId": 501, "dayIndex": 4, "date": "2026-10-27", "weekday": "화", "activityCount": 4,
      "baseCity": {                                  // (v2.1) 그날의 기준 도시 — 모든 파생의 출처
        "placeId": 22, "name": "교토", "timezone": "Asia/Tokyo", "currency": "JPY",
        "countryCode": "JP", "cityPlaceRef": "ChIJ_kyoto",  // 도시 식별자 — 보관함 그룹·담기 시트가 이 값으로 묶는다
        "lat": 35.0116, "lng": 135.7681
      },
      "cityChanged": true,                           // (v2.1) 직전 날짜와 도시가 다름 → 탭 왼쪽 구분선
      "arrivingFrom": {                              // (D-25) 그날 떠나온 도시 — 이동일에만
        "placeId": 21, "name": "오사카", "timezone": "Asia/Tokyo", "currency": "JPY",
        "countryCode": "JP", "cityPlaceRef": "ChIJ_osaka", "lat": 34.6937, "lng": 135.5023
      },
      "legIndex": 2,                                 // (v2.1) 이 날짜가 속한 구간 번호
      "cityMemo": "체크아웃 후 교토역 코인로커에 짐 보관",
      "stayTonight": { "stayId": 77, "name": "교토 게스트하우스", "sameCity": true,
                       "checkInTime": "15:00", "isCheckInDay": true },
      "stayCheckout": { "stayId": 76, "name": "도톤보리 호텔", "checkOutTime": "11:00" },
      "weather": { "icon": "CLEAR", "tempMax": 15, "tempMin": 8, "precipProbability": 20 },
      "arrivingFromWeather": {                       // (D-25) 떠나온 도시의 그날 날씨 — 이동일에만
        "cityName": "오사카", "icon": "RAIN", "tempMax": 18, "tempMin": 11,
        "precipProbability": 70 } },
    { "dayId": 502, "dayIndex": 5, "date": "2026-10-28", "weekday": "수", "activityCount": 3,
      "baseCity": { "placeId": 23, "name": "나고야", "timezone": "Asia/Tokyo", "currency": "JPY",
                    "countryCode": "JP", "cityPlaceRef": "ChIJ_nagoya",
                    "lat": 35.1815, "lng": 136.9066 },
      "cityChanged": true, "legIndex": 3, "cityMemo": null,
      "stayTonight": null, "stayCheckout": null,
      "weather": null }                              // 예보 범위 밖 → 3행 비움
  ],
  "archiveCount": 3,
  "activities": [                                    // 요청한 날짜의 일정만. sort_order 순
    { "id": 91, "title": "숙소 체크아웃", "startTime": "09:00",
      "place": { "id": 12, "name": "도톤보리 호텔", "address": "…", "lat": 34.6, "lng": 135.5,
                 "cityName": "오사카", "cityPlaceRef": "ChIJ…" },    // (v2.1) 도시 판정용
      "outOfBaseCity": true,                         // (v2.1) 그날 있어도 되는 어느 도시에도 안 속함 → "· 오사카" 경고색
      "notifyEnabled": true, "departureNotifyEnabled": false,
      "canDepartureNotify": true,                    // (#1208) 직전에 장소 있는 일정이 있을 때 true
      "hasLog": false, "sortOrder": 0 },
    { "id": 92, "title": "기념품 사기", "startTime": null, "place": null,
      "notifyEnabled": false, "departureNotifyEnabled": false,
      "canDepartureNotify": false, "hasLog": false, "sortOrder": 1 }
  ],
  "moves": [                                         // (#1208) 구 travelTimes[] — 사용자가 적은 값
    { "fromActivityId": 91, "toActivityId": 93, "toStayId": null,
      "mode": "TRAIN", "name": "나리타 익스프레스 3호", "durationMinutes": 53,
      "url": "https://www.jreast.co.jp/", "memo": "5호차 12A" },
    { "fromActivityId": 93, "toActivityId": 94, "toStayId": null,      // 아직 안 적은 구간
      "mode": null, "name": null, "durationMinutes": null,
      "url": null, "memo": null }
  ],
  "stayMove": {                                      // 리스트 맨 아래 숙소 이동 — 같은 모양이다
    "fromActivityId": 94, "toActivityId": null, "toStayId": 77,
    "mode": "WALK", "name": null, "durationMinutes": 8, "url": null, "memo": null
  }
}

v2.1 추가 규칙

  • moves[]는 사용자가 적은 값이다(#1208). 서버가 계산하지 않으므로 crossCity·fallback·distanceM이 없다 — 계산하지 않으니 계산을 막을 경계도, 실패해 대체할 값도 없다.
    • 아직 아무것도 적지 않은 구간도 행으로 내려간다(mode: null). 그 빈 행이 곧 입력 지점이라, 응답에서 빼면 화면에 누를 곳이 없어진다.
    • durationMinutes는 null일 수 있다 — 수단만 먼저 정하고 시간은 나중에 확인하는 것이 실제 순서다.
    • name이 실제로 타는 것이다(나리타 익스프레스 3호). mode는 아이콘·묶음용 분류일 뿐이라, 나라 고유명을 enum에 넣지 않는다 — 신칸센을 값으로 박으면 일본 밖에서 쓸 수 없고 다음엔 TGV·KTX 요청이 이어진다.
    • 도시를 넘는 구간에도 값이 실린다. v2.1 §3.4의 "도시 경계는 계산하지 않는다"는 자동 계산이 있던 시절의 규칙이었다. 비행기·신칸센이야말로 미리 정해 두는 이동이다.
  • 도시 일치 판정은 place.cityPlaceRef 비교로만 한다. 좌표 거리로 추측하지 않는다.
    • 식별자가 둘 다 있고 서로 다를 때만 outOfBaseCity = true·crossCity = true다. 한쪽이라도 모르면 판정하지 않는다 — 모르는 것을 "다르다"로 답하면 멀쩡한 일정에 경고가 붙고, 멀쩡한 이동에서 시간이 사라진다.
    • 이동일(cityChanged = true)은 견주는 대상이 둘이다(D-25) — baseCity와 arrivingFrom 어디에도 안 속할 때만 outOfBaseCity가 선다. 10.28 오전의 오사카 일정은 잘못 담은 것이 아니다.
    • 그래서 직접 입력한 도시(구글 id 없음)를 기준 도시로 쓰는 여행에서는 이 표시가 뜨지 않는다. 검색으로 고른 도시라야 비교할 값이 생긴다.
  • canDepartureNotify는 직전에 장소 있는 일정이 있을 때만 true다. 보관함 일정은 날짜가 없어 항상 false다.
    • (#1208) 도시 경계 조건이 빠졌다. 자동 계산 시절에는 도시를 넘으면 소요 시간을 못 구해 스위치를 막았지만, 지금은 사용자가 적어 두면 신칸센 구간에도 출발 알림이 선다.
    • 상세(GET /activities/{id})·저장 응답도 같은 판정을 채운다 — 스위치가 있는 화면이 상세라, 목록과 답이 갈리면 못 켜는 스위치를 켤 수 있는 것처럼 보여준다.
    • 소요 시간이 비어 있어도 true다. 스위치는 저장되는 설정이라, 아직 안 적었다는 이유로 끄면 나중에 적어도 꺼진 채로 남는다. 대신 알림은 서지 않고, 상세 화면이 그 이유를 말한다.
  • stayMove는 그날 마지막 일정 → 오늘 밤 숙소 이동이고 moves[]와 같은 모양이다(toStayId가 채워진다). 숙소가 없거나, 마지막 일정이 이미 그 숙소거나, 숙소에 장소가 안 붙어 있으면 null이다 — 도착지가 없으면 적을 수도 없다.
  • days[]는 여행 전체를 항상 내려준다(날짜 탭이 전부 필요). 날씨 캐시는 도시 단위 6시간 — 같은 도시 날짜는 한 번만 조회한다.
  • trip.timezone은 없어졌다. 화면이 쓰던 자리는 days[i].baseCity.timezone으로 옮긴다.

쿼리 파라미터

파라미터 값 설명
date YYYY-MM-DD 해당 날짜의 일정
archive true 보관함(activity_date IS NULL)
(생략) 진행 중이면 여행 타임존의 오늘, 아니면 1일차
  • days[].weather는 여행 전체 기간을 항상 내려준다(날짜 탭이 전부 필요). 캐시 6시간.
  • 오프라인에서는 SW 캐시가 이 응답을 그대로 돌려주므로 이동·날씨가 함께 보인다. FE는 캐시 표시(회색) 처리를 navigator.onLine으로 판단하고, 이동 편집은 막는다(§4.6).

4. 일정

POST /api/travel/trips/{tripId}/activities

// Request
{
  "title": "시부야 스카이",
  "activityDate": "2026-10-25",   // null = 보관함
  "startTime": "10:30",           // null 허용
  "placeId": 12,                  // null 허용 (제목만으로 추가 가능 §1.5)
  "memo": null, "url": null
}
// Response.data → 생성된 활동 (sortOrder는 서버가 해당 날짜 끝에 배정)

PUT /api/travel/activities/{activityId}

계획 영역 전체 수정. activityDate·startTime·notify*가 바뀌면 알림을 재계산한다(§4.2).

{
  "title": "시부야 스카이", "activityDate": "2026-10-25", "startTime": "10:30",
  "placeId": 12, "memo": "티켓 예매함", "url": "https://…",
  "notifyEnabled": true, "notifyMinutes": 15, "departureNotifyEnabled": true
}
  • startTime이 null인데 notifyEnabled=true면 저장은 하되 알림은 만들지 않는다(§1.2). FE는 해당 영역을 비활성으로 그린다.

DELETE /api/travel/activities/{activityId}

예약 알림을 CANCELED로 전이시킨다.

삭제·보관함 이동은 누르는 즉시 요청을 보낸다(#1432). 실행취소는 없다 — 예전에는 FE가 스낵바 5초 동안 요청을 보류했는데 없앴다(결정 기록 D-5). FE는 행을 낙관적으로 먼저 빼고, 실패하면 되돌린다. 소프트 삭제·복원 API는 두지 않는다.

PUT /api/travel/trips/{tripId}/activities/order

드래그 결과를 한 번에 반영한다. 순서 변경과 날짜 이동이 같은 요청이다.

// Request — 영향받은 날짜의 전체 순서를 보낸다(부분 갱신 금지)
{
  "moves": [
    { "date": "2026-10-25", "activityIds": [93, 91, 92] },
    { "date": null,          "activityIds": [95] }        // 보관함
  ]
}
// Response.data → 다시 이어진 구간의 moves 포함(이동이 바로 갱신되도록)
{ "legs": [ … ] }
  • 서버는 각 배열 순서대로 sort_order를 0..n-1로 재부여하고, 소속 날짜를 갱신한다. 한 트랜잭션.
  • 영향받은 일정의 알림을 재계산한다(§4.2 — 순서가 바뀌면 어느 구간이 이어지는지가 바뀐다).
  • 저장된 이동은 사라지지 않는다. 이동은 장소 쌍에 붙어 있어, 순서를 되돌리면 적어 둔 값이 그대로 돌아온다(#1208).
  • legs는 건드린 날짜 전체의 구간이다(날짜 이동이면 두 날짜). 구간이 일정 id로 식별되므로 날짜가 섞여도 모호하지 않다. 보관함(date: null)은 포함하지 않는다 — 배정되지 않은 목록이라 순서에 이동 의미가 없다.

PUT /api/travel/trips/{tripId}/activities/swap (#1368)

하루의 일정을 통째로 다른 날짜와 맞바꾼다.

// Request — 둘 다 여행 기간 안의 서로 다른 날짜여야 한다
{ "date": "2026-10-26", "withDate": "2026-10-28" }
// Response.data → null (보드를 다시 읽는다)
  • 일정만 건너간다. 기준 도시·숙소·도시 메모는 날짜에 남는다. 숙소는 체크인·체크아웃 날짜에 묶여 있고, 기준 도시까지 따라가면 구간(leg)이 통째로 다시 나뉘어 숙소와 어긋난다. 바꾸려는 것은 「그날 무엇을 하는가」이지 「어디에 있는가」가 아니다.
  • 각 날짜 안의 순서는 그대로 따라간다. 3일차의 세 일정이 5일차에 가서도 같은 순서로 선다 — 맞바꾼 사람이 다시 정렬할 일이 없다. 옮긴 뒤 양쪽을 0..n-1로 정규화한다.
  • **한쪽이 비어 있으면 그대로 「그 날짜로 통째 이동」**이다. 따로 엔드포인트를 두지 않는다.
  • 두 날짜의 알림·이동을 모두 재계산한다(§4.2 — 그날 무엇이 언제 있는지가 통째로 바뀐다).
  • 보관함(null)은 받지 않는다. 거기엔 맞바꿀 하루가 없고 날짜별 순서도 없다.
  • 응답이 없다. 두 날짜와 날짜 탭 건수가 한꺼번에 바뀌어 화면은 어차피 보드를 다시 읽는다 — 반쪽짜리 응답을 이어붙이는 쪽이 더 어긋나기 쉽다.
  • 실행취소를 두지 않는다. 한 번 더 맞바꾸면 그대로 원래대로 돌아온다(삭제·보관함과 다른 점이다).

PUT /api/travel/trips/{tripId}/moves (#1208)

v2.1의 GET /travel-time을 대체한다. 그 엔드포인트는 "자동 판정되지 않은 수단을 사러 가는" 조회였다. 이동을 사용자가 적게 되면서 살 것이 없어졌다 — 조회도 없다. 이동은 보드 응답에 함께 실려 온다(오프라인 캐시가 응답 하나로 성립해야 한다, §4.6).

이동 저장. 등록·수정이 같은 요청이고, 한 구간에 이동은 하나라 덮어쓴다.

// Request
{
  "fromActivityId": 91,
  "toActivityId": 93,        // toStayId 와 정확히 하나만 보낸다
  "toStayId": null,
  "mode": "TRAIN",           // WALK BIKE BUS CAR SUBWAY TRAIN FLIGHT FERRY OTHER
  "name": "나리타 익스프레스 3호",  // 선택 — 실제로 타는 것
  "durationMinutes": 53,     // 선택 — 1~10080, 생략하면 "아직 안 찾아봤다"
  "url": "https://www.jreast.co.jp/",
  "memo": "5호차 12A"
}
// Response.data → 저장된 move (보드의 moves[] 원소와 같은 모양)
  • 양 끝을 일정 id로 받는다. 저장은 (member_id, from_place_id, to_place_id)에 하지만 화면은 일정을 보고 있고, 서버가 옮겨 준다 — 화면이 장소 id를 들고 다니면 저장 단위를 바꿀 때마다 화면이 함께 흔들린다.
  • 같은 장소 쌍을 잇는 다른 날짜의 이동도 함께 바뀐다. 그게 장소 쌍에 저장하는 이유다 — 도쿄역에서 숙소까지를 한 번 적으면 매일 다시 적지 않아도 된다.
  • 저장 뒤 그 날짜의 알림을 다시 짠다 — 출발 알림이 시작시각 − 소요 시간 − 5분이라, 시간을 고쳐 놓고 알림을 그대로 두면 예전 값으로 울린다.
  • 장소 없는 일정, 장소 없는 숙소, 같은 장소끼리, 도착지가 없거나 둘이면 400 TRAVEL-ERR-009.

DELETE /api/travel/trips/{tripId}/moves

DELETE /api/travel/trips/12/moves?from=91&to=93
DELETE /api/travel/trips/12/moves?from=94&toStay=77
  • 없는 이동을 지워도 200이다. 두 번 눌렀을 때 두 번째만 실패하면 화면은 지워지지 않았다고 읽는다.
  • 지운 뒤에도 그 구간은 보드에 빈 행으로 남는다 — 행까지 사라지면 다시 적을 곳이 없다.
  • 알림도 함께 다시 짠다 — 지워진 값으로 울리게 두지 않는다.

4.5 날짜 · 숙소 (v2.1 신규)

GET /api/travel/trips/{tripId}/days

기간 전체의 날짜와 기준 도시. 보드 응답에도 같은 내용이 들어가지만, S-03 구간 편집기와 담기 시트가 일정 없이 날짜만 필요할 때 쓴다.

// Response.data
[ { "dayId": 501, "dayIndex": 4, "date": "2026-10-27", "weekday": "화", "legIndex": 2,
    "cityChanged": true, "cityMemo": null,
    "baseCity": { "placeId": 22, "name": "교토", "timezone": "Asia/Tokyo",
                  "currency": "JPY", "countryCode": "JP", "cityPlaceRef": "ChIJ_kyoto",
                  "lat": 35.0116, "lng": 135.7681 },
    "arrivingFrom": { "placeId": 21, "name": "오사카", "timezone": "Asia/Tokyo",
                      "currency": "JPY", "countryCode": "JP", "cityPlaceRef": "ChIJ_osaka",
                      "lat": 34.6937, "lng": 135.5023 } } ]
  • arrivingFrom은 도시가 바뀌는 날에만 있다(D-25) — 구간 편집기가 구간 카드 사이에 10.27 오사카 → 교토 이동 줄을 그린다. cityChanged가 true인 날과 정확히 같은 집합이다.

PUT /api/travel/days/{dayId}

기준 도시 변경 / 도시 메모. 날짜 탭 롱프레스 시트가 부른다.

// Request — 전부 선택. 보낸 필드만 바꾼다
{ "baseCityPlaceId": 24, "cityMemo": "체크아웃 후 교토역 코인로커에 짐 보관" }

// 검색 결과를 그대로 보내도 된다(구간 입력과 같은 두 방식)
{ "baseCityGooglePlaceId": "ChIJ_kyoto" }
  • 응답은 바꾼 날짜 하나가 아니라 기간 전체의 날짜다. 하루를 바꾸면 구간이 다시 나뉘어 앞뒤 날짜의 legIndex·cityChanged까지 달라진다.
  • 도시는 baseCityPlaceId 또는 baseCityGooglePlaceId 중 하나로 지정한다(둘 다 보내면 400). 둘 다 없으면 도시를 바꾸지 않는다는 뜻이다.
    • baseCityGooglePlaceId를 받는 이유는 구간 입력(§4.2 legs[])과 같다: 여행에 아직 없는 도시로 하루를 옮길 때 화면이 먼저 장소를 만들면 도시 식별자가 없어 그날 일정이 전부 "다른 도시"(outOfBaseCity)로 표시된다. 서버가 담으면서 식별자를 붙인다.
  • baseCity.cityPlaceRef는 직접 입력한 도시에는 없다(null). 화면은 이 값이 있을 때만 도시로 묶는다 — 이름으로 묶지 않는다(D-23).
  • baseCityPlaceId는 place_kind = CITY 여야 한다. 아니면 400 TRAVEL-ERR-016. 없는 날짜는 404 TRAVEL-ERR-019.
  • 기준 도시가 바뀌면 서버가 연쇄 재계산한다(v2.1 §3.3). 다만 실제로 손댈 것은 PENDING 알림 재계산 하나뿐이다 — 통화·날씨·검색 좌표는 저장하지 않고 조회할 때 기준 도시에서 파생하므로 다음 조회부터 새 값이 나온다. 이동도 무효화할 것이 없다: 사용자가 적은 값이 장소 쌍에 붙어 있어(#1208) 도시가 바뀌어도 두 장소를 잇는 이동은 그대로다.
  • 이 날짜의 일정과 장소는 건드리지 않는다. 경고도 내려보내지 않는다.
  • 하루만 바꾸면 구간이 쪼개진다(도쿄/닛코/도쿄 → 구간 3개). 정상이며 별도 확인을 받지 않는다.

GET /api/travel/trips/{tripId}/city-legs

파생 구간. S-03 구간 편집기 초기값과 S-05 전체 지도가 쓴다.

// Response.data
[ { "legIndex": 1, "cityPlaceId": 21, "cityName": "오사카", "days": 3,
    "startDate": "2026-10-24", "endDate": "2026-10-26",
    "timezone": "Asia/Tokyo", "lat": 34.6937, "lng": 135.5023 } ]
  • 저장된 것이 아니라 trip_day에서 매번 계산한다(v2.1 §2.4).
  • 전체 지도의 마커는 도시당 1개 — 같은 도시가 여러 구간에 나오면 첫 방문 구간 번호를 쓴다.

숙소 CRUD

GET    /api/travel/trips/{tripId}/stays
POST   /api/travel/trips/{tripId}/stays
PUT    /api/travel/stays/{stayId}
DELETE /api/travel/stays/{stayId}
// POST / PUT Request
{ "name": "교토 게스트하우스", "placeId": 31,
  "checkInDate": "2026-10-27", "checkOutDate": "2026-10-28",
  "checkInTime": "15:00", "checkOutTime": "11:00",
  "bookingUrl": "https://…", "memo": null }

// Response.data — 목록은 이 객체의 배열(checkInDate 오름차순)
{ "stayId": 77, "name": "교토 게스트하우스", "placeId": 31,
  "checkInDate": "2026-10-27", "checkOutDate": "2026-10-28",
  "checkInTime": "15:00", "checkOutTime": "11:00",
  "bookingUrl": "https://…", "memo": null,
  "nights": 1 }                                  // 묵는 밤 수 — 반열린 구간이라 날짜 차이 그대로

// 겹침 거절 (409)
{ "code": "TRAVEL-ERR-017", "message": "이미 숙소가 잡힌 기간입니다.",
  "data": { "stayId": 76, "name": "도톤보리 호텔",
            "checkInDate": "2026-10-24", "checkOutDate": "2026-10-27" } }

검증

  • checkOutDate > checkInDate(400 TRAVEL-ERR-002), 둘 다 여행 기간 내(400 TRAVEL-ERR-007)
  • 기간 겹침 금지 — [in, out) 반열린 구간이 기존 숙소와 겹치면 409 TRAVEL-ERR-017 + 겹치는 숙소 이름·기간을 함께 내려준다. FE는 "기존 숙소 기간을 먼저 줄여주세요"로 안내한다
  • 체크아웃일과 다음 체크인일이 같은 것은 겹침이 아니다(이동일)
  • 수정은 자기 자신과 겹치지 않는다 — 기간을 그대로 두고 이름만 고치는 요청이 막히면 안 된다
  • 없는 숙소·남의 숙소는 404 TRAVEL-ERR-020

마지막 날 밤은 담을 수 없다. 체크아웃일도 여행 기간 안이어야 하므로, 종료일 밤에 묵으려면 여행 기간을 하루 늘려야 한다. 기간 단축 시 숙소를 종료일까지 당기는 규칙(v2.1 §3.2)과 같은 전제다.

DELETE는 ConfirmDialog(destructive) 대상 — "이 숙소가 붙어 있던 날짜에서 모두 사라집니다."

체크인·체크아웃 일정을 자동 생성하지 않는다. 숙소 시트의 일정으로 추가를 눌렀을 때만 POST /trips/{id}/activities로 만든다. 자동 생성하면 지워도 되살아나는 일정이 된다. 만든 뒤로는 숙소와 아무 관계가 없는 보통 일정이라 숙소를 지워도 남는다(DELETE는 숙소 행만 지운다).

googlePlaceId·cityPlaceId로 장소를 붙인다(#1155). 일정 담기와 같은 규칙이다 — 검색 결과를 그대로 넘기면 서버가 upsert해 placeId로 연결한다. placeId와 함께 보내지 않는다.

cityPlaceId는 기준 도시에서 가져오지 않는다. 사용자가 고른다 — 닛코 당일치기 날의 기준 도시는 닛코지만 자는 곳은 도쿄일 수 있고, "숙소는 기준 도시와 무관하다"(§3.5)를 저장 시점에 깨면 도시 표시가 그대로 틀어진다. 화면은 보던 날짜의 도시를 기본값으로만 넣는다.

도시를 안 주면 식별자도 비운다(D-23 — 좌표로 되짚지 않는다). 그때는 좌표만 붙어 소요 시간까지만 살아나고 경계 판정은 "모르면 같은 도시"로 떨어진다.


5. 장소 (2단계)

전부 BE 프록시 + 캐시. 브라우저가 Google API를 직접 부르지 않는다.

GET /api/travel/places/cities?q=도쿄

S-03 구간 도시 선택(v2.0에서는 목적지 검색). 도시 단위 결과만 돌려주고 타임존·통화·좌표를 함께 확정해서 내려준다.

// Response.data
[ { "googlePlaceId": "ChIJ…", "name": "도쿄", "address": "일본 도쿄도",
    "lat": 35.6762, "lng": 139.6503, "timezone": "Asia/Tokyo", "currency": "JPY",
    "countryCode": "JP" } ]
  • 타임존은 좌표 → IANA 매핑, 통화는 국가 코드 → ISO 4217 매핑으로 서버가 결정한다. FE는 받아서 보여주기만 한다(§S-03 Alert).
  • v2.1: 여기서 고른 장소는 place_kind = CITY로 저장되고, 그 행만 trip_day.base_place_id가 될 수 있다.
  • 행정구역 타입 필터 범위는 D-24 참조 — locality 우선, 없으면 administrative_area_level_1|2.

GET /api/travel/places/search?q=&tripId=&city=

S-06. 결과 20개(§S-06). 검색은 도시 좌표를 중심으로 편향시킨다(§1.5 "목적지 주변 우선").

(v2.1) city는 기준 도시 칩이 고른 도시의 내부 placeId다. 주면 그 도시로 편향하고, 없으면 첫날 기준 도시로 떨어진다 — 다구간 여행에서 그 폴백은 곧 "오사카 좌표로 교토 가게를 찾는" 상태라, 화면은 언제나 city를 실어 보낸다.

  • 없는 장소·남의 장소면 404 TRAVEL-ERR-008, 도시가 아닌 장소(가게)면 400 TRAVEL-ERR-016. 조용히 첫날 도시로 떨어뜨리지 않는다 — 화면이 "교토"라고 말하면서 오사카 결과를 주는 것이 없애려는 그 상태다.
  • 편향 좌표가 캐시 키에 들어간다. 도시를 바꾸면 자연히 다른 검색이다.
// Response.data
[ { "id": 12,                          // 이미 저장된 장소면 내부 id, 아니면 null
    "googlePlaceId": "ChIJ…", "name": "시부야 스카이",
    "category": "전망대", "address": "…", "rating": 4.4,
    "photoUrl": "https://img.orino.dev/travel/places/ChIJ….jpg",  // MinIO 캐시. 없으면 null
    "lat": 35.65, "lng": 139.70,
    "lng": 139.7966 }                  // photoUrl은 항상 null (장소 사진 미도입, D-16)
]
  • 검색 결과 캐시 1시간, 장소 상세·사진 캐시 30일(§4.7).
  • 담기를 누르면 FE가 이 장소를 POST /activities에 googlePlaceId로 실어 보내고, 서버가 travel_place에 upsert 후 place_id로 연결한다.
  • (v2.1) 이때 cityPlaceId(기준 도시 칩의 도시)를 함께 보낸다. 서버가 그 도시의 city_place_ref를 장소에 저장한다 — 이 값이 없으면 보관함 도시 그룹(§S-04)도 도시 이탈 표시(outOfBaseCity)도 성립하지 않고 도시 없음으로 떨어진다.
    • 구글 상세 응답은 도시 이름만 주고 도시의 장소 id는 주지 않는다. 어느 도시에서 찾았는지는 화면만 아는 정보라 요청에 실어야 한다. 좌표 거리로 되짚지 않는 이유는 D-23이다.
    • 도시 이름은 구글 것을 쓰고 식별자만 칩에서 온다. 이름은 상세 응답 쪽이 정확하다.
    • 이미 담긴 장소의 도시는 덮지 않는다. 나중에 다른 칩으로 같은 장소를 다시 담았다고 처음 알던 도시가 바뀌면, 그 장소가 붙은 다른 날짜의 판정까지 조용히 흔들린다.
    • 기준 도시가 직접 입력한 도시(구글 id 없음)면 붙일 식별자가 없어 그대로 비운다.

GET /api/travel/places/{placeId}

장소 상세(영업시간·전화번호). details_refreshed_at이 30일 지났으면 갱신 후 응답.

POST /api/travel/places

직접 입력(§S-06 "검색 결과가 없어요" → 직접 입력). manual = true로 저장.

// Request
{ "name": "울란바토르", "address": null, "lat": null, "lng": null,
  "kind": "CITY",                  // (v2.1) 생략하면 POI
  "timezone": "Asia/Ulaanbaatar",  // kind=CITY 일 때만. IANA ID가 아니면 400 TRAVEL-ERR-003
  "currency": "MNT" }              // kind=CITY 일 때만. ISO 4217이 아니면 400 TRAVEL-ERR-004
  • kind = CITY면 기준 도시로 쓸 수 있는 도시 장소가 된다(v2.1). 도시 검색이 못 찾는 곳으로 가는 여행도 기준 도시가 없으면 그 여행의 어느 날짜도 타임존을 갖지 못한다. 구글이 알려줄 수 없으므로 그때만 타임존·통화를 사용자에게 받는다.
  • 여행 생성·수정에서 없어진 타임존·통화 검증이 이 자리로 옮겨 왔다.

6. 푸시 (3단계)

GET /api/travel/push/public-key

{ "publicKey": "BKd…" }   // VAPID 공개키(base64url). SW 구독 시 applicationServerKey

POST /api/travel/push/subscriptions

// Request — PushSubscription.toJSON() 그대로
{ "endpoint": "https://fcm.googleapis.com/fcm/send/…",
  "keys": { "p256dh": "B…", "auth": "…" } }
  • endpoint SHA-256 해시로 upsert(같은 기기 재구독 시 중복 생성 방지).

DELETE /api/travel/push/subscriptions

{ "endpoint": "https://fcm.googleapis.com/fcm/send/…" }

POST /api/travel/push/test

S-09 검증용 즉시 발송. 3단계 실기기 3일 연속 검증(§5.1)에 필요하다.


7. 도구 (4단계)

GET /api/travel/trips/{tripId}/weather

Open-Meteo 프록시. 여행 좌표 → v2.1: 날짜별 기준 도시 좌표. 캐시 6시간, 키는 도시 단위. ✅ 구현 완료(#1169)

이 엔드포인트는 v2.1 명세가 나온 뒤에도 한동안 첫날 도시 하나로 답하고 있었다. 보드의 날짜 탭(days[].weather)만 도시별로 고쳐졌고 도구 화면이 쓰는 이쪽은 남아 있었다 — 같은 나라 안에서는 몇 도 차이라 화면이 멀쩡해 보였기 때문이다. #1169에서 맞췄다.

// Response.data — v2.1
{
  "source": "Open-Meteo", "license": "CC BY 4.0",   // 출처 표기 필수(§S-08)
  "fetchedAt": "2026-08-10T09:00:00Z",
  "daily": [
    { "date": "2026-10-24", "cityName": "오사카",
      "icon": "CLEAR", "tempMax": 15, "tempMin": 8, "precipProbability": 20 },
    // 도시가 바뀌는 날은 줄이 둘 — 떠나온 도시가 먼저다 (D-25)
    { "date": "2026-10-28", "cityName": "오사카",
      "icon": "RAIN", "tempMax": 18, "tempMin": 11, "precipProbability": 70 },
    { "date": "2026-10-28", "cityName": "교토",
      "icon": "CLOUD", "tempMax": 16, "tempMin": 9, "precipProbability": 30 }
  ],
  "hourly": {                                        // 선택 날짜 시간대별
    "2026-10-24": [ { "time": "09:00", "icon": "CLEAR", "temp": 14 } ]
  }
}
  • 캐시 키는 (cityPlaceRef, 날짜)이지 여행이 아니다. 오사카 3일이면 1회만 호출하고, 도쿄→닛코→도쿄면 도쿄 캐시를 공유한다.
  • 호출량 주의: 도시 수만큼 호출이 는다. 도시 단위 캐시는 선택이 아니라 필수다(ELOG-023).
  • 서버가 도시별로 묶어 한 번씩 부르고 날짜에 다시 펼쳐 내린다. 날짜 수만큼 부르지 않는다.
  • 예보 범위 밖 날짜는 daily에서 생략한다(FE가 "예보 범위 밖" 처리).
  • daily는 날짜당 한 줄이 아니다. 도시가 바뀌는 날은 (날짜, 도시) 두 줄이 오고 떠나온 도시가 앞이다(D-25) — 그날 오전은 아직 그 도시에 있다. 화면이 date로 묶거나 중복 제거하면 한쪽이 사라진다.
    • hourly는 그대로 날짜당 하나이고 그날 기준 도시(도착한 쪽) 것이다. 하루에 시계가 둘일 수는 없다.
  • daily[].cityName은 값과 함께 다닌다 — 날짜마다 다른 도시의 예보라, 화면이 날짜만 보고 짐작하면 도쿄 예보에 교토를 붙이게 된다.
    • 초안에 있던 cityPlaceRef는 넣지 않았다(#1169). 이 화면은 도시를 표시할 뿐 일치 판정을 하지 않아 쓸 곳이 없다 — 판정이 필요해지면 그때 더한다.
  • icon은 enum(CLEAR·CLOUD·RAIN·SNOW)으로 정규화해서 내린다. lucide 매핑은 FE. 강수확률 60% 이상 강조(§1.8)는 FE 규칙이다.

GET /api/travel/fx?base=JPY&quote=KRW

ECB 기준. 캐시 24시간.

{ "base": "JPY", "quote": "KRW", "rate": 9.42,
  "source": "ECB", "referenceDate": "2026-08-07", "fetchedAt": "2026-08-07T08:00:00Z" }
  • ECB는 KRW·JPY를 EUR 기준으로 고시하므로 서버가 교차환산한다.
  • 면책 문구("실제 결제 환율과 다를 수 있습니다")는 FE 고정 문구(§S-08).

8. 기록 · 사진 (4단계)

PUT /api/travel/activities/{activityId}/log

평점·메모 upsert. 사진과 분리된 요청이다(§5.1 위험 대응).

{ "rating": 4, "memo": "야경이 좋았다" }   // 둘 다 null 허용
  • 여행 시작일 이전에는 404가 아니라 400(TRAVEL-ERR-012)으로 거부한다. 일정은 실재하고, 아직 기록할 때가 아닐 뿐이다(기록 영역은 시작일 이후에만 노출 §S-07). 판정 기준은 여행 타임존의 오늘이다
  • rating 1~5, memo 2000자. 둘 다 비면 기록을 지우고 data: null을 돌려준다 — "다 지웠다"와 "빈 기록이 있다"는 다른 상태다
  • 화면은 자동 저장(1초 디바운스)이라 저장 버튼이 없다. 계획 저장(PUT /activities/{id})과 요청이 분리돼 있어 계획을 저장하지 않아도 기록만 남는다

일정 응답(ActivityResponse)에 기록이 함께 실린다.

{ "hasLog": true,
  "log": { "rating": 4, "memo": "야경이 좋았다", "updatedAt": "2026-10-24T13:20:11Z" } }
  • 보드 목록에도 log를 통째로 싣는다. 보드 응답이 곧 오프라인 캐시라(§S-04), hasLog만 내려주면 비행기 모드에서 "기록 있음"만 뜨고 내용은 못 본다

POST /api/travel/activities/{activityId}/photos/upload-url

// Request
{ "contentType": "image/jpeg", "kind": "ORIGINAL" }  // kind: ORIGINAL | THUMB
// Response.data
{ "uploadUrl": "https://minio…/note-images/travel/activities/91/uuid.jpg?X-Amz-…",
  "publicUrl": "https://img.orino.dev/note-images/travel/activities/91/uuid.jpg",
  "objectKey": "travel/activities/91/uuid.jpg" }
  • image/jpeg만 받는다 — canvas 재인코딩으로 EXIF를 떨군 결과가 JPEG이다. 원본 형식을 허용하면 재인코딩을 건너뛴 파일이 위치정보를 달고 올라온다
  • 발급 단계에서도 소유권과 여행 시작일을 본다. 남의 일정 경로에 올릴 수 없어야 하고, 어차피 등록이 거부될 사진을 올리게 하지 않는다

POST /api/travel/activities/{activityId}/photos

업로드 완료 후 메타 등록. 성공한 파일만 보낸다 — 실패한 파일은 FE가 재시도 목록에 남긴다(§2.5).

{ "photos": [ { "objectKey": "travel/…/a.jpg", "thumbKey": "travel/…/a_t.jpg",
                "width": 2560, "height": 1920 } ] }
// Response.data — 그 일정의 사진 전체(업로드 순서)
[ { "id": 1, "url": "https://img.orino.dev/…/a.jpg",
    "thumbUrl": "https://img.orino.dev/…/a_t.jpg", "width": 2560, "height": 1920 } ]
  • 기존 장수 + 요청 장수 > 10이면 400(TRAVEL-ERR-013). 부분 반영하지 않는다 — 화면과 서버 장수가 어긋난다
  • thumbKey는 null 가능(썸네일만 실패할 수 있다)
  • 평점·메모가 없으면 빈 기록을 만들어 붙인다 — 사진만 남기는 것도 기록이다
  • 여행 시작 전이면 400(TRAVEL-ERR-012)

DELETE /api/travel/photos/{photoId}

행 삭제 + MinIO 객체 삭제. 오브젝트 삭제는 best-effort다 — 실패해도 행은 지운다. 반대로 하면 화면에서 지운 사진이 새로고침에 되살아난다.


장소 사진 (캐시 규칙)

Google이 주는 것은 사진 리소스 이름(places/X/photos/Y)이고 이미지 URL은 만료된다. 그래서 URL을 저장할 수 없고, 서버가 받아 MinIO에 넣은 뒤 우리 URL을 내려준다.

  • 검색 필드마스크에 photos를 넣지 않는다. 결과 20개에 사진을 달면 화면 한 번에 유료 호출 20번이다. 사진은 담아 둔 장소에만 붙는다(담기·상세 갱신 시점)
  • 검색 응답의 photoUrl은 이미 담아 둔 장소만 채워진다. 이미 받아 둔 것을 보여주는 것은 공짜다
  • 이미 photo_object_key가 있으면 다시 받지 않는다 — 사진 호출도 건당 과금이고, 장소 사진이 바뀌는 일은 드물다. 상세 갱신 주기(30일)가 와도 사진까지 다시 사지 않는다
  • 실패해도 장소는 그대로 보인다(사진만 없음). 다음 갱신 때 다시 시도한다
  • media 호출은 skipHttpRedirect=true로 URI만 받아 두 번째 호출에서 키 없이 내려받는다 — 리다이렉트를 따라가면 API 키가 CDN 요청에 실려 나간다
  • 리소스 이름에 슬래시가 있어 URI 템플릿 변수로 넘기면 %2F로 인코딩돼 404가 난다. 경로로 붙인다

⚠️ 이 캐시는 구글 약관의 허용 범위 밖이다(#1102). ToS §3.2.3(b)는 Service Specific Terms가 명시적으로 허용한 것 외의 캐싱을 금지하고, SST §14.3이 Places에 허용하는 것은 위경도 30일뿐이다(place_id는 무기한). Place Photos 문서는 사진 이름에 대해 *"You cannot cache a photo name."*라고 못박는다.

"성능 목적 30일 캐시"라는 포괄 조항은 2018년판 §10.5(d)에 있던 것이고 현행 약관에는 없다 — API별 화이트리스트로 바뀌었다. 이 문서의 이전 판에 "허용 범위 안"이라고 적혀 있었는데 잘못된 서술이었다.

방식(무캐시 프록시 / 짧은 TTL / 감수)은 #1102에서 정한다. 확인 시점 2026-08-09.

표기 의무(캐시 방식과 무관하게 지켜야 한다)

  • 사진 저작자: authorAttributions[]는 배열이고 각 항목이 displayName·uri·photoUri를 가진다. 링크까지 포함해 이미지와 나란히 표시해야 한다 — 지금은 displayName 하나만 저장해 링크가 빠지고 다중 저작자가 유실된다(#1102)
  • 지도 없이 Places 데이터를 보여주는 화면(S-06)에는 Google 로고(공간이 좁으면 "Google Maps" 텍스트)가 있어야 한다
  • Places 콘텐츠(위경도·place_id 제외)는 비구글 지도와 함께 쓸 수 없다. 현재 OSM 지도에는 좌표만 찍어 문제없지만, 그 위에 이름·사진을 얹으면 위반이다

10. 준비 (v2.2)

GET /api/travel/trips/{tripId}/prep

화면 한 벌을 한 번에 내린다. 분류 4개는 항목이 없어도 전부 내려간다 — 화면이 빈 분류 카드를 그려야 하고, FE가 분류 목록을 따로 들고 있으면 서버와 두 벌이 된다.

{
  "tripId": 12, "startDate": "2026-10-24", "dday": 49,
  "total": 24, "done": 18, "overdueCount": 1,
  "groups": [
    { "category": "DOCUMENT", "total": 3, "done": 3, "sections": [ … ] },
    { "category": "BOOKING", "total": 5, "done": 4, "sections": [
      { "label": null, "total": 5, "done": 4, "items": [
        { "id": 91, "title": "항공권 발권", "done": true, "sectionLabel": null,
          "quantity": null, "dueDaysBefore": null, "dueDate": null,
          "overdue": false, "url": "https://…", "memo": null, "displayOrder": 0 },
        { "id": 92, "title": "숙소 잔금 결제", "done": false, "sectionLabel": null,
          "quantity": null, "dueDaysBefore": 14, "dueDate": "2026-10-10",
          "overdue": false, "url": null, "memo": null, "displayOrder": 1 }
      ] }
    ] },
    { "category": "BAG", "total": 12, "done": 9, "sections": [
      { "label": null, "total": 2, "done": 0, "items": [ … ] },
      { "label": "캐리어", "total": 8, "done": 7, "items": [ … ] },
      { "label": "기내백", "total": 2, "done": 2, "items": [ … ] }
    ] },
    { "category": "TODO", "total": 4, "done": 2, "sections": [ … ] }
  ]
}
  • dueDate·overdue·dday는 파생값이다. 저장하지 않는다(§12 · 데이터 모델 §2.11)
  • 기준 시각은 첫날 기준 도시의 오늘이다. 여행 상태·D-day와 같은 기준을 쓴다 — 여기만 서버 로컬 날짜를 쓰면 출발 전날 밤에 화면과 알림이 하루 어긋난다
  • overdueCount는 전체 기준 하나다. 사이드바 배지와 화면 상단이 같은 값을 읽는다
  • 항목은 묶음을 거쳐서만 실린다(#1358). groups[].items는 없다 — 두 벌이 되는 순간 어느 쪽이 진짜 순서인지가 매번 질문이 된다
    • label: null이 「묶음 없음」이고 항상 맨 앞이다. 묶음을 안 쓰는 분류는 이 묶음 하나만 오고, 그때 화면은 소제목을 그리지 않는다
    • 이름 붙은 묶음의 차례는 **그 안의 최소 displayOrder**다(서버가 정렬해 내린다 — 저장된 순서 값이 아니다)
    • 빈 묶음은 내려가지 않는다. 분류 카드와 다른 점이다 — 분류는 넷으로 고정이라 빈 카드도 자리를 갖지만, 묶음은 항목이 만든 것이라 마지막 항목이 나가면 사라진다
    • 묶음 이름은 항목에도 실린다(sectionLabel). 편집 시트가 항목 하나만 들고 열리고 수정 요청도 항목 단위라, 지금 무슨 묶음인지를 항목이 말할 수 있어야 한다
  • 한때 groups[].items[]가 한시로 함께 내려갔다(#1361). #1360이 그 필드를 빼면서 이미 열려 있던 탭이 깨졌기 때문이다 — 서비스워커가 새 버전을 사용자가 받아들여야 갈고(registerType: "prompt") 앱 셸이 precache라, 서버에서 옛 청크가 404가 된 뒤에도 그 탭에서는 계속 돌았다 → D-42
    • #1362에서 지웠다. 기기를 전부 새로고침한 것이 확인돼 목표일(2026-10-06)보다 앞당겼다. BE의 items와 FE의 감싸는 층(fetchPrep) 둘 다 없다

POST /api/travel/trips/{tripId}/prep/items

{ "category": "BAG", "title": "멀티어댑터", "sectionLabel": "캐리어",
  "quantity": null, "dueDaysBefore": null, "url": null, "memo": null }
  • title만 필수다. 붙박이 입력줄이 엔터 한 번으로 보내는 요청이 이것이다(§13)
  • category 생략 시 TODO. FE는 「방금 적은 분류」를 실어 보내지만, 서버 기본값도 명세와 같은 자리에 둔다(§11: 애매하면 할 일)
  • displayOrder는 서버가 정한다 — 그 분류의 맨 뒤. 클라이언트가 순서를 계산해 보내면 두 탭에서 동시에 추가할 때 겹친다
  • quantity는 category='BAG'이 아니면 무시하고 NULL로 저장한다. 400을 내지 않는다 — 분류를 바꾸다 남은 값 때문에 항목 추가가 막히는 편이 더 나쁘다
  • sectionLabel(≤30자)은 생략하면 「묶음 없음」이다. 앞뒤 공백은 다듬고, 공백뿐이면 NULL로 저장한다 — 이름 하나가 곧 묶음이라 「캐리어 」가 따로 서면 목록에 같은 이름의 소제목이 둘 생긴다. 새 항목은 분류의 맨 뒤이자 그 묶음의 맨 뒤다

응답은 PATCH와 같은 모양이다. 항목 하나가 늘면 진행률도 함께 움직이므로 집계를 다시 세어 내린다.

{ "category": "TODO",
  "item": { "id": 104, "title": "환전", "done": false, "quantity": null,
            "dueDaysBefore": null, "dueDate": null, "overdue": false,
            "url": null, "memo": null, "displayOrder": 0 },
  "summary": { "total": 25, "done": 18, "overdueCount": 1 } }

category가 응답 맨 위에 따로 있는 이유 — 분류를 생략하고 보낼 수 있으니 항목이 어디로 들어갔는지는 서버만 안다. 화면은 이 값을 보고 어느 카드를 펼칠지 정한다(§10.6: 추가된 분류는 자동으로 펼친다).

PATCH /api/travel/prep/items/{itemId}

부분 수정. 체크 토글도 이 엔드포인트다.

{ "done": true }
{ "category": "TODO", "title": "환전", "dueDaysBefore": 3 }
{ "sectionLabel": "캐리어" }
{ "clear": ["DUE_DAYS_BEFORE", "SECTION_LABEL"] }
  • 보낸 것만 바꾼다. 체크 토글이 {"done": true} 하나로 나가는데 나머지를 「안 보냈으니 지운다」로 읽으면 제목까지 날아간다
  • 그래서 비우는 것은 따로 말한다 — clear에 이름을 적은 칸만 NULL이 된다(QUANTITY·DUE_DAYS_BEFORE·URL·MEMO·SECTION_LABEL). 편집 시트에서 기한 칸을 비우는 것과 기한을 그대로 두는 것은 다른 일이고, 값만으로는 그 둘을 구별할 수 없다. 자산 수정의 clearGroup과 같은 규칙인데 지울 수 있는 칸이 넷이라 목록으로 받는다
  • 응답은 바뀐 항목 + 갱신된 집계(total·done·overdueCount)를 함께 내린다. 체크 한 번에 진행률·배지·상단 경고가 같이 움직이는데 화면이 그것을 다시 계산하면 서버와 어긋난다
  • category가 바뀌면 displayOrder를 새 분류의 맨 뒤로 다시 매긴다. 분류와 수량을 함께 보내면 분류를 먼저 적용한다 — 순서가 뒤집히면 「짐으로 옮기면서 수량 4」가 옛 분류로 판정돼 수량만 사라진다
  • sectionLabel이 바뀌면 그 묶음의 맨 뒤로 다시 매긴다 — 분류 이동과 같은 규칙이다. 옛 자리를 들고 가면 「캐리어」로 옮긴 항목이 캐리어 한가운데에 나타나 방금 누른 줄을 다시 찾게 된다. 같은 이름을 다시 보내면 자리는 그대로다(앞뒤 공백은 같은 이름으로 본다) — 제목만 고쳐 저장했는데 순서가 흔들리면 목록이 제멋대로 움직이는 것으로 읽힌다
  • 분류와 묶음을 함께 보내면 자리는 새 분류의 맨 뒤 하나다. 분류 이동이 이미 맨 뒤를 줬으므로 묶음 때문에 또 매기지 않는다
  • 분류가 바뀌어도 sectionLabel은 남는다. 수량과 반대다 — 수량은 짐 전용이라고 우리가 정의한 값이고, 묶음은 사용자가 적은 말이다
  • dueDaysBefore는 음수를 받지 않는다(400 TRAVEL-ERR-023). 「출발 3일 후」는 준비가 아니다

DELETE /api/travel/prep/items/{itemId}

즉시 삭제(하드). FE는 누르는 즉시 이 요청을 보낸다(#1432) — 예전의 5초 대기·실행취소는 없앴다. 항목은 낙관적으로 먼저 빼고 실패하면 되돌린다.

PUT /api/travel/trips/{tripId}/prep/order

{ "category": "BAG", "sections": [
  { "label": null, "itemIds": [104, 101] },
  { "label": "캐리어", "itemIds": [107, 103] }
] }

한 분류의 배치를 통째로 받는다 — 순서와 묶음을 한 번에다(#1364). 분류를 넘는 이동은 PATCH의 category 변경이지 이 엔드포인트가 아니다 — 다른 분류의 항목 id가 섞여 오면 404(TRAVEL-ERR-022)다.

  • 화면이 보낸 것이 곧 결과다. 「무엇을 옮겼는가」를 서버가 알아낼 필요가 없고, 드래그 한 번에 요청도 하나다 — 묶음 이동과 정렬을 두 요청으로 쪼개면 사이에서 실패했을 때 옮겨는 갔는데 자리는 옛것인 상태가 남는다
  • 여기 적힌 항목은 그 label의 묶음으로 옮겨진다. 묶음 없음은 label: null이다
  • 빠뜨린 항목은 지우지 않고 뒤에 붙인다. 화면이 목록 일부만 들고 있을 때(완료 숨기기·접힘) 나머지가 사라지는 것보다 순서가 뒤로 밀리는 편이 되돌리기 쉽다. 그 항목의 묶음은 건드리지 않는다 — 화면에 없던 줄을 말없이 옮기는 것은 순서가 밀리는 것과 달리 되돌릴 방법이 눈에 안 보인다

11. 경비 (v2.2 → v2.3 독립)

2026-09-20에 바뀌었다. v2.2의 경비는 가계부 원장 위의 읽기 뷰였고, 지출 쓰기는 FE가 POST /api/ledger/transactions로 직접 보냈다. 가계부를 제거하므로 경비는 여행이 소유하는 장부(trip_expense)가 된다 — D-43 · Travel-Expense-Standalone.

읽기 응답의 모양은 거의 그대로다. 그룹 규칙·게이지 2층·budget이 없으면 null·dailyAllowance 하한 0 — 전부 유지한다. 바뀐 것은 출처와 쓰기 경로다.

GET /api/travel/trips/{tripId}/expenses

여행 화면이 읽는다. 출처는 trip_expense이고, 여행은 그것을 여행의 문법(출발 전 · N일차 · 도시)으로 묶어 내린다.

{
  "tripId": 12, "status": "ONGOING", "todayDayNumber": 4,
  "budget": { "amount": 800000, "spent": 412000, "scheduled": 80000,
              "remaining": 388000, "daysLeft": 4, "dailyAllowance": 97000 },
  "totals": { "spent": 1235000, "scheduled": 80000, "days": 6, "dailyAverage": null },
  "unsortedCount": 3,
  "groups": [
    { "key": "BEFORE", "label": "출발 전", "sum": 820000, "rows": [
      { "expenseId": 4102, "title": "항공권", "amount": 640000,
        "fx": null, "status": "CONFIRMED", "category": "TRANSPORT",
        "paymentMethod": "국민 체크", "uncategorized": false,
        "overdue": false, "occurredOn": "2026-08-30" },
      { "expenseId": 4211, "title": "숙소 잔금", "amount": 80000,
        "fx": null, "status": "SCHEDULED", "category": "STAY",
        "paymentMethod": null, "uncategorized": false,
        "overdue": false, "occurredOn": "2026-10-20" }
    ] },
    { "key": "DAY-1", "label": "1일차 · 오사카", "dayNumber": 1,
      "date": "2026-10-24", "cityName": "오사카", "sum": 32000, "rows": [
      { "expenseId": 4301, "title": "점심 라멘", "amount": 11300,
        "fx": { "currency": "JPY", "amount": 1200.00, "rate": 9.4166 },
        "status": "CONFIRMED", "category": "FOOD", "paymentMethod": "현금",
        "uncategorized": false, "overdue": false, "occurredOn": "2026-10-24" }
    ] },
    { "key": "AFTER", "label": "다녀온 뒤", "sum": 0, "rows": [] }
  ]
}

v2.2에서 바뀐 필드 셋

바뀜 내용
transactionId → expenseId 가리키는 것이 ledger_transaction에서 trip_expense로 바뀌었다
category · paymentMethod 추가 편집 시트를 여행 안에서 열므로 편집용 값이 필요하다. v2.2가 「편집용 필드를 싣지 않는다」고 한 이유(편집 화면이 가계부에 있었다)가 사라졌다
overdue 추가 status='SCHEDULED'인데 occurredOn이 지났다. 화면이 「확정」 버튼을 건다. 자동 승격 스케줄러를 만들지 않는다

그룹 규칙 (v2.2 그대로)

조건 그룹
occurred_on < start_date BEFORE — 「출발 전」
start_date <= occurred_on <= end_date DAY-N — 「N일차 · 그 날짜의 기준 도시」
occurred_on > end_date AFTER — 「다녀온 뒤」
  • 날짜 그룹은 지출이 없어도 내려간다(빈 날짜는 sum: 0). BEFORE·AFTER는 비어 있으면 내리지 않는다
  • 도시가 바뀌는 날은 도착 도시 하나로 센다(명세 §4.4)
  • sum은 그 묶음에 보이는 줄의 합이라 확정과 예정을 함께 센다. totals.spent는 확정만이다 — 게이지가 두 겹인 이유이고, 묶음 합계는 사용자가 눈으로 더한 값과 같아야 한다
  • dailyAllowance는 0 아래로 내려가지 않는다. remaining은 사실대로 음수를 낸다
  • budget은 **예산이 없으면 통째로 null**이다. amount: 0을 내리지 않는다
  • 여행이 끝났으면 budget.dailyAllowance가 null이 되고 totals.dailyAverage가 채워진다. 두 값이 동시에 차지 않는다
  • uncategorized = category IS NULL. 「정리할 내역 N건」이 unsortedCount다

TRANSFER·INCOME 필터가 없어졌다. v2.2는 원장을 읽었기 때문에 카드 대금 납부와 환불을 걸러내야 했다. trip_expense에는 지출만 있으므로 거를 것이 없다 — 그 대가로 생겼던 문제(환불이 목록에 안 보이는데 총액만 줄던 것)도 함께 사라진다.

POST /api/travel/trips/{tripId}/expenses

{ "occurredOn": "2026-10-27", "amount": null, "title": null,
  "category": null, "paymentMethod": "국민 체크", "status": "CONFIRMED",
  "fx": { "currency": "JPY", "amount": 1200.00, "rate": null } }
→ 201 { "expenseId": 4402, "amount": 11300,
        "fx": { "currency": "JPY", "amount": 1200.00, "rate": 9.4166 } }
  • amount 또는 fx 중 하나는 있어야 한다. 둘 다 없으면 400(TRAVEL-ERR-027)
  • title·category 없이 저장된다. 카테고리를 고르느라 기록을 포기하느니 나중에 채운다(명세 §6.1)
  • fx.rate가 null이면 서버가 ExchangeRateService(ECB 고시)로 채우고 그 값을 거래에 고정한다. 조회 시 재계산하지 않는다
  • ECB에 못 닿아도 200이다. rate: null로 돌려주고 화면이 직접 입력 칸을 연다 — 환율 때문에 기록을 막지 않는다
  • 통화 기본값(오늘 도시)·결제수단 기본값(직전에 쓴 것)은 FE가 정한다. 서버가 「직전」을 추측하지 않는다
  • 오프라인이면 입력 자체를 막는다(D-33). 큐에 쌓아 나중에 보내지 않는다

PATCH /api/travel/trips/{tripId}/expenses/{id}

부분 수정이다. 보낸 필드만 바뀐다. 지난 예정의 「확정」 버튼도 이 통로를 쓴다({"status": "CONFIRMED"}).

fx를 다시 보내면 환율이 다시 고정된다 — 카드사가 실제로 적용한 환율이 며칠 뒤 청구서에 찍히고 고시 환율과 다른 경우를 위한 길이다(명세 §4.3).

DELETE /api/travel/trips/{tripId}/expenses/{id}

소프트 삭제. 되돌리기는 화면 토스트에서 즉시만 연다 — 휴지통 화면을 만들지 않는다.

상쇄하지 않고 지운다. 「원장은 지우지 않고 상쇄한다」는 원장이라서 있던 규칙이고, 이건 원장이 아니다.

PUT /api/travel/trips/{tripId}/budget

v2.2 그대로다.

{ "amount": 800000 }   → 200 { "amount": 800000 }
{ "amount": null }     → 200 { "amount": null }    // 예산 해제
  • amount <= 0은 400(TRAVEL-ERR-024). 예산 0은 「안 정함」과 구분되지 않는다 — 해제는 null로 한다
  • 예산은 계속 trip.budget_amount다(D-28 유지). 이번 변경에 예산은 손댈 곳이 없다

폐기 — POST /expenses/attach · /detach

삭제한다. 기간으로 걸러 기존 원장 거래를 여러 건 붙이던 통로였다. 붙일 원장이 없다.

9. 에러

기존 ErrorCode(GLB-ERR-XXX) 체계에 여행 도메인 코드를 추가한다.

상황 HTTP 비고
여행/일정 없음 또는 타 멤버 소유 404 존재 여부를 흘리지 않도록 소유권 실패도 404
종료일 < 시작일 400
기간 밖 날짜로 일정 이동 400
기간 단축인데 confirmArchive 없음 409 이동 예정 건수를 함께 반환
이동 저장에서 장소 없는 일정·숙소, 같은 장소끼리, 도착지 없음/둘 400 TRAVEL-ERR-009. 어디서 어디로인지가 없으면 이동이 아니다
사진 10장 초과 400 TRAVEL-ERR-013
15MB 초과 — FE가 고르는 순간 거른다(서버까지 오지 않는다)
없는 사진 삭제 · 남의 사진 404 TRAVEL-ERR-014
여행 시작일 이전 기록 저장 400 TRAVEL-ERR-012
(v2.1) place_kind != CITY인 장소를 기준 도시로 지정 400 TRAVEL-ERR-016
(v2.1) 숙소 기간 겹침 409 TRAVEL-ERR-017. 겹치는 숙소 이름·기간을 함께 반환
(v2.1) 도시 간 이동 일정에 출발 알림 활성화 400 TRAVEL-ERR-018. FE가 먼저 비활성으로 막지만 서버도 거른다
(v2.1) 없는 날짜 · 남의 여행 날짜 수정 404 TRAVEL-ERR-019. 리소스별 404를 두는 관례(001·006·008·014)를 따른다
(v2.2) 준비 항목 없음 · 남의 여행 항목 · 순서 요청에 다른 분류 id 404 TRAVEL-ERR-022
(v2.2) dueDaysBefore < 0 400 TRAVEL-ERR-023. 「출발 3일 후」는 준비가 아니다
(v2.2) 예산 amount <= 0 400 TRAVEL-ERR-024(경비 묶음에서 추가). 예산 해제는 null이지 0이 아니다
(v2.3) 경비 없음 · 남의 여행 경비 404 TRAVEL-ERR-026. 리소스별 404를 두는 관례(001·006·008·014·022)를 따른다
(v2.3) amount·fx 둘 다 없음 · 0 이하 400 TRAVEL-ERR-027. 금액 없는 지출은 기록이 아니다
(v2.3) 고시표에 없는 통화 400 TRAVEL-ERR-028. 사용자 입력이 틀린 것이다
(v2.3) ECB에 못 닿음 200 에러로 만들지 않는다. rate: null로 내리고 화면이 직접 입력 칸을 연다 — 환율 때문에 기록을 막지 않는다
(#1368) 같은 날짜끼리 교체 400 TRAVEL-ERR-025. 조용히 성공으로 답하면 화면이 틀린 날짜를 보내도 「바꿨어요」만 돌아온다
(#1368) 교체 대상이 기간 밖 · 보관함(null) 400 기간 밖은 TRAVEL-ERR-007, null은 요청 검증에서 걸린다
(v2.2) 오프라인에서 체크·입력 시도 — 서버까지 오지 않는다. FE가 컨트롤을 비활성으로 막는다(§6.2 · §13)
외부 API 실패(Places·날씨·환율) 200 에러로 만들지 않는다. 폴백값 + fallback: true로 화면이 계속 동작해야 한다
푸시 구독 만료(410/404) — 서버가 구독 행을 삭제하고 조용히 넘어간다

Clone this wiki locally