Skip to content

Travel Architecture

wcorn edited this page Sep 20, 2026 · 11 revisions

시스템 아키텍처: 여행 (Travel)

확정 명세 v2.2 · v2.1 · v2.0 · 유스케이스 · 데이터 모델 · API 설계 · 화면 설계 · 결정 기록

1. 개요

여행은 독립 도메인이다. 노트·메모·플래너 어느 것도 재사용하지 않는다. 재사용하는 것은 셋뿐이다 — 앱 셸(AppLayout/Sidebar), 사진 presigned 업로드 파이프라인, 디자인 시스템.

[FE React 19 + Vite 7]  ── PWA (Service Worker 신규)
  ├─ /select 워크스페이스 선택 + 사이드바 스위처
  ├─ features/travel — 보드·지도·장소·상세·도구
  ├─ SW: ① 오프라인 조회 캐시(Workbox)  ② 웹푸시 수신·클릭 라우팅
  └─ 사진: canvas 재인코딩(EXIF 제거)+썸네일 → presigned PUT (바이트 BE 미경유)
        │  (인증 API: JWT)                                        │
        ▼                                                         │
[orino BE / orino-app-api]                                        │
  ├─ Trip / Activity / Log CRUD (RDB)                             │
  ├─ 외부 프록시 + Redis 캐시                                      │
  │    ├─ Google Places (New)  검색·상세·사진                      │
  │    ├─ Open-Meteo           일자별·시간대별 예보                 │
  │    └─ ECB                  환율                                │
  ├─ presigned URL 발급 (AWS SDK v2 S3Presigner) ──────────────────┤
  └─ 알림: 예약 테이블 + @Scheduled 폴링 → Web Push(VAPID)          │
        │                                                          ▼
[MySQL] trip · trip_activity · travel_place · travel_move ·  [MinIO note-images 버킷]
        trip_activity_log · trip_activity_photo ·             travel/ prefix
        push_subscription · push_notification                (img.orino.dev 공개 read)
[Redis] places · weather · fx 캐시   (routes 캐시는 #1208에서 사라졌다)

2. 워크스페이스 분리

앱은 일상과 여행 두 워크스페이스로 나뉜다. 데이터·API·도메인은 완전히 분리돼 있고, 공유하는 것은 인증과 앱 셸뿐이다.

파일 변경
fe/src/pages/LoginPage.tsx 성공 시 navigate("/home") → navigate("/select")
fe/src/pages/LandingPage.tsx 인증 시 <Navigate to="/home"> → "/select"
fe/src/app/router.tsx /select(PrivateRoute, AppLayout 밖), /travel/* 라우트 트리 추가
fe/src/app/layout/Sidebar.tsx 최상단 워크스페이스 스위처 + pathname.startsWith("/travel")로 NAV_ITEMS 분기
fe/src/app/routeImports.ts 여행 페이지 lazy import, prefetchRoutes에 /travel 홈·보드 추가
  • 로그인 직후 항상 /select. 마지막 선택을 기억하지 않는다.
  • /travel/* 딥링크는 선택 화면으로 리다이렉트하지 않는다(푸시 알림 클릭이 여기로 들어온다).
  • 일상 라우트는 하나도 건드리지 않는다.

2.1 라우트

/select                              WorkspaceSelectPage      (AppLayout 밖, 자체 헤더)
/travel                              TravelHomePage           S-01
/travel/trips                        TripListPage             S-02
/travel/trips/new                    TripFormPage             S-03
/travel/trips/:tripId/edit           TripFormPage             S-03 (수정)
/travel/trips/:tripId/board          BoardPage                S-04  (?day=0..N|archive)
/travel/trips/:tripId/map            BoardMapPage             S-05  (?day=)
/travel/trips/:tripId/places         PlaceSearchPage          S-06
/travel/activities/:activityId       ActivityDetailPage       S-07
/travel/tools                        ToolsPage                S-08  (?tab=fx|weather)
/travel/settings                     TravelSettingsPage       S-09

URL이 소유하는 상태: 선택 날짜(?day=) · 보드/지도 모드(경로) · 도구 탭(?tab=). 새로고침·뒤로가기에서 유지된다.

3. 코드 배치

3.1 BE (기존 멀티모듈 컨벤션)

계층 위치 내용
엔티티 orino-domain-rdb → ds.project.orino.domain.planner.travel Trip, TripActivity, TravelPlace, TripActivityLog, TripActivityPhoto + Repository
준비·경비 엔티티 ds.project.orino.domain.planner.travel TripPrepItem(v2.2) · TripExpense(v2.3) + Repository. 경비 엔티티는 없다 → 가계부 제거로 여행이 자기 장부를 갖는다(§11)
알림 엔티티 ds.project.orino.domain.planner.push PushSubscription, PushNotification (여행 전용 아님 — 공용 설계)
애플리케이션 orino-app-api → ds.project.orino.planner.travel Controller · Service · DTO (trip / activity / place / log / tool / prep · expense(v2.2) 하위 패키지)
외부 클라이언트 ds.project.orino.planner.travel.client GooglePlacesClient, OpenMeteoClient, EcbFxClient — 전부 RestClient. GoogleRoutesClient는 #1208에서 제거
푸시 ds.project.orino.planner.push WebPushSender, NotificationScheduler, NotificationPlanner
마이그레이션 orino-app-api/.../db/changelog/changes/ 047-create-travel-tables.yaml, 048-create-push-tables.yaml

패키지는 기존 관례대로 planner 우산 아래 둔다(domain.planner.note·domain.planner.lifelog처럼 앱의 모든 기능이 planner 하위에 있다). 응답/에러는 CustomResponseCode(성공) · ErrorCode(GLB-ERR-XXX, CustomException) 컨벤션 준수. 불리언 컬럼은 BIT(1) (Hibernate validate 호환 — ELOG 참고).

3.2 FE (기존 feature 관례)

fe/src/features/travel/
  api/{trips,activities,places,routes,logs,weather,fx,push}.ts
  hooks/{useTrips,useTrip,useBoard,useActivityMutations,usePlaceSearch,useWeather,useFxRate,usePush}.ts
  queryKeys.ts
  lib/{tripStatus,activityOrder,travelMode,tripClock}.ts
  board/{BoardHeader,DayTabs,ActivityRow,TravelTimeRow,AddSheet,TransportSheet,UndoSnackbar,BoardEmptyState}.tsx
  board/{BoardMap,MapMarkerCard}.tsx
  detail/{PlanSection,NotifySection,LogSection,PhotoGrid,PhotoViewer}.tsx
  place/{PlaceSearchInput,PlaceResultCard,DatePickSheet}.tsx
  tools/{FxCard,WeatherCard,TranslateCard}.tsx
fe/src/pages/travel/{TravelHomePage,TripListPage,TripFormPage,BoardPage,BoardMapPage,PlaceSearchPage,ActivityDetailPage,ToolsPage,TravelSettingsPage}.tsx
fe/src/pages/WorkspaceSelectPage.tsx

디자인 시스템 추가 2건 (여행 전용이 아니라 components/ui에 들어간다):

  • components/ui/bottom-sheet.tsx — AddSheet/TransportSheet/DatePickSheet가 공유. base-ui Dialog + 하단 정렬. 모션은 translateY(100%)→0 180ms ease-out만.
  • components/Toaster.tsx + shared/lib/toast.ts — 실행취소 액션 지원으로 확장.

서버 상태는 TanStack Query, 화면 로컬 상태만 useState. 새 전역 상태 라이브러리를 넣지 않는다.

4. 타임존 — 이 모듈에서 가장 틀리기 쉬운 곳

v2.1: 타임존의 주인이 여행 → 날짜로 바뀐다

trip.timezone은 없어진다. 모든 타임존은 trip_day.base_place_id가 가리키는 도시에서 온다. 아래 규칙은 그대로 유효하되 trip.timezone을 읽던 자리를 전부 그 날짜의 기준 도시 타임존으로 바꾼다.

발송시각(UTC) = ZonedDateTime.of(
      activity_date, start_time,
      ZoneId.of( day(activity_date).baseCity.timezone ))   // ← v2.1
    .minusMinutes(notifyMinutes).toInstant()

아침 요약만 예외다. 도시가 바뀌는 날의 요약은 그날 08:00이되 전날 도시의 시계로 나간다. 그날 도시 기준으로 계산하면 이미 이동 중일 때 도착한다.

이 줄은 원래 "전날 날짜의 타임존으로 전날 08:00"이라고 적혀 있었다(#1167에서 정정). 하루 앞당겨 보내면 본문 오늘 일정 3개가 내일 이야기가 되고, 같은 문서의 근거("이미 이동 중일 때 도착한다")와도 어긋난다 — 그 근거가 가리키는 것은 날짜가 아니라 시계다. 확정 명세 v2.1 §3.6과 설정 문구(§9.5)의 "전날 도시 08:00"이 정본이다.

파생값 v2.0 v2.1
여행 상태 trip.timezone 첫날 도시가 시작일 전이면 예정, 마지막 날 도시가 종료일을 넘겼으면 완료, 그 사이는 진행 중
D-day trip.timezone 첫날의 기준 도시 tz
화면이 여는 "오늘" trip.timezone의 오늘 아직 지나지 않은 첫 날짜
보드 헤더 현지 09:42 trip.timezone 선택한 날짜의 기준 도시 tz
알림 발송시각 trip.timezone 그 일정이 속한 날짜의 기준 도시 tz

"오늘"은 "지나갔나"로 묻는다 (#1123에서 확정). 날짜마다 자기 시계로 "나는 지나갔나"를 묻고, 아직 지나지 않은 첫 날짜가 오늘이다.

"그 날짜의 기준 도시에서 본 오늘이 그 날짜와 같은가"로 물으면 안 된다 — 날짜변경선을 넘나드는 여행에는 어느 날짜도 그 조건을 만족하지 않는 순간이 있다.

10.24 도쿄(UTC+9)      지금 도쿄는 10.25   → 10.24 아님
10.25 호놀룰루(UTC-10)  지금 호놀룰루는 10.24 → 10.25 아님   ← 오늘이 없어진다

같은 순간에 "지나갔나"로 물으면 10.24는 지났고 10.25는 아직이라 답이 하나로 정해진다. 상태를 양 끝(첫날·마지막 날)으로만 판정하는 것도 같은 이유다 — 마지막 날 도시가 늦은 시간대면 그 도시에서 끝날 때까지 진행 중이어야 한다.

lib/tripStatus.ts는 여행 단위 타임존 대신 ZoneByDate(날짜 → 타임존) 를 받는다. 여행 하나에 타임존 하나라는 가정이 남아 있는 코드는 전부 찾아 고친다 — 가정이 하나라도 남으면 그 화면만 조용히 틀린다.

§4.1이 정본이다. 일정 시각은 벽시계 시각으로 저장한다(v2.1: 그 날짜 기준 도시의 벽시계).

저장 표시 이유
일정 날짜·시각 DATE + TIME (UTC 변환 안 함) 있는 그대로 서울에서 짜든 도쿄에서 보든 10:30은 10:30이어야 한다
알림 발송 시각 DATETIME(6) = UTC Instant — 실제 발송은 절대시각이어야 한다
발송시각(UTC) = ZonedDateTime.of(activity_date, start_time, ZoneId.of(trip.timezone))
                  .minusMinutes(notifyMinutes)
                  .toInstant()
  • 기준 도시를 바꾸면 activity_date/start_time은 그대로 두고 그 날짜의 push_notification.scheduled_at만 재계산한다(v2.1 — 여행 전체가 아니라 그 날짜다).
  • 여행 상태(예정/진행 중/완료)는 저장하지 않는다. 매 조회 시 파생하며, 기준은 v2.1에서 날짜별 기준 도시다(BE TripClock · FE lib/tripStatus.ts — 같은 규칙을 양쪽에 둔다).
  • 보드 헤더의 현지 09:42는 FE가 Intl.DateTimeFormat(timeZone)으로 계산한다(lib/tripClock.ts). 타임존은 보고 있는 날짜의 기준 도시에서 온다. 기기 오프셋과 같으면 줄을 숨긴다.
  • 금지: 일정 시각을 Instant로 저장하는 것. 타임존을 바꾸는 순간 모든 일정이 밀린다.

5. 외부 연동

전부 BE 프록시다. 브라우저가 외부 API를 직접 부르지 않는다 — 키 노출 방지, 쿼터·캐시 제어, CORS 회피.

연동 용도 캐시 (Redis) 키
Google Places (New) 목적지 도시 검색, 장소 검색(Text Search), 상세(영업시간·전화), 대표 사진 검색 결과 1h / 상세·사진 30일(§4.7) API Key (SealedSecret)
Open-Meteo 일자별 요약 + 시간대별 예보 6h(§4.7) 없음 (무료)
ECB 기준 환율 24h(§4.7) 없음 (무료)

5.1 Google 비용 통제 (중요)

Places는 호출당 과금이다. orino의 비용 원칙(ELOG-008)상 무방비 호출은 허용하지 않는다.

  • 모든 호출은 BE를 통과하고 Redis 캐시를 먼저 본다. 캐시 미스만 외부로 나간다.
  • 장소는 한 번 검색해 travel_place에 영구 저장한다(이름·주소·좌표·google_place_id). 이후 조회는 DB만 본다. 영업시간·사진만 30일 만료 후 재조회.
  • 장소 사진은 MinIO에 캐시한다. Google Place Photos는 요청당 과금이 크고 URL이 단기 만료라, BE가 1회 받아 MinIO(travel/places/{placeId}.jpg)에 저장하고 이후 img.orino.dev로 서빙한다. 30일 후 갱신.
  • 이동시간에는 유료 호출이 없다(#1208). 사용자가 직접 적으므로 이 축의 비용이 0이다.
  • 일별 호출 상한을 애플리케이션 레벨에서 건다(초과 시 폴백). Google Cloud 콘솔의 예산 알림도 함께 설정한다.

5.2 이동 조립 (#1208 — 계산이 아니라 조회다)

이동시간을 앱이 계산하지 않는다. 사용자가 적어 둔 값을 읽어 보드 응답에 함께 내려준다 — FE가 구간마다 별도 호출하지 않아야 오프라인에서 보드 응답 캐시만으로 이동이 함께 보인다(§4.6).

보드 조회
  → 해당 날짜 일정을 sort_order 순으로 정렬
  → 장소 있는 일정만 남긴다 (장소 없는 일정은 건너뛴다)
  → 인접 쌍의 장소 id 목록을 만든다
  → travel_move 를 한 번에 조회 (member_id + from IN (…) + to IN (…))
       있으면  → 적어 둔 mode·name·durationMinutes·url·memo
       없으면  → 빈 값 (mode: null). 행 자체는 남긴다 — 그 자리가 입력 지점이다
  → moves[] 를 응답에 포함

좌표를 보지 않는다. 이동을 잇는 것이 장소 id이므로, 검색에 안 나와 이름만 적어 둔 장소 사이에도 이동을 적을 수 있다 — 자동 계산 시절에는 Routes에 넘길 좌표가 없어 그런 구간이 통째로 빠졌다.

구간마다 조회하지 않는다. 일정 수만큼 쿼리가 나면 유료 호출을 없애면서 DB 왕복으로 갈아탄 것일 뿐이다. 양쪽에 IN을 걸어 한 번에 받고 실제 쌍만 남긴다.

무효화가 없다. 이동은 (멤버, 출발 장소, 도착 장소)에 저장되므로 순서를 바꾸거나 기준 도시를 바꿔도 손댈 것이 없다 — 바뀌는 것은 어느 쌍이 이어지는가이고, 그건 매 조회마다 다시 정해진다.

5.3 사라진 것 (#1208 이전)

있었던 것 왜 없앴나
직선거리(Haversine) → 1.5km 임계 → WALK/DRIVE 자동 판정 도보·자동차 두 가지밖에 표현하지 못했다
travel:routes:{좌표}:{좌표}:{mode} Redis 캐시 30일 캐시할 자동 계산이 없다
crossCity — 도시를 넘으면 계산하지 않음 정작 미리 정해 두는 이동이 그 구간이다
fallback — 실패 시 약 N.Nkm 계산하지 않으니 실패해 대체할 값도 없다

도시 경계 판정(TravelPlace.crossesCity)은 남아 있다. 다만 쓰는 곳이 줄었다 — #1208에서 이동 쪽이 빠졌기 때문이다.

자리 무엇을 견주나 상태
도시 이탈 표시(outOfBaseCity) 일정 장소 ↔ 그날 기준 도시 유지
오늘 밤 숙소 배지(stayTonight.sameCity) 숙소 장소 ↔ 그날 기준 도시 유지
일정 사이 이동 · 숙소 이동 — #1208에서 빠졌다. 도시를 넘는 구간이야말로 사용자가 미리 적어 두는 이동이다

출발 알림 가능 여부(canDepartureNotify)에서도 도시 조건이 빠졌다. 이제 조건은 "직전에 장소 있는 일정이 있는가" 하나다 — 소요 시간을 사용자가 알고 있으므로 도시를 넘어도 "몇 시에 나서라"를 정할 수 있다. 판정에 외부 호출도 DB 조회도 없다는 점은 그대로다.

5.4 구글 지도 딥링크

앱 내 표시와 무관하게 항상 대중교통(§4.5). 좌표로 전달한다.

#1208 이후 이 딥링크의 역할이 커졌다. 예전에는 "앱이 계산한 도보/자동차 대신 실제 경로를 보러 가는" 보조 통로였지만, 지금은 사용자가 소요 시간을 확인하러 나가는 주 통로다. 이동 편집 시트에 구글 지도에서 시간 확인 버튼으로 남아 있고, 거기서 본 값을 시트에 적는다.

https://www.google.com/maps/dir/?api=1
  &origin={lat},{lng}&destination={lat},{lng}&travelmode=transit

6. 알림 (웹푸시)

리포에 푸시 인프라가 전혀 없다. Service Worker·VAPID·구독 저장·발송 스케줄러가 전부 신규다. 플랫폼이 Android Chrome 확정(iOS 제외)이라 표준 Web Push로 충분하다.

[등록]  FE: SW 등록 → Notification.requestPermission()
            → pushManager.subscribe({ applicationServerKey: VAPID 공개키 })
            → POST /api/travel/push/subscriptions { endpoint, keys }
        BE: push_subscription 저장 (endpoint SHA-256 해시로 유니크)

[예약]  일정 저장/수정/정렬/타임존 변경 시 (§4.2 트리거)
        BE: 해당 일정의 PENDING 알림 전량 CANCELED → 다시 계산해 INSERT
            · ACTIVITY   = 시작시각 − notifyMinutes
            · DEPARTURE  = 시작시각 − 적어 둔 소요시간 − 5분  (이전 장소 + 적힌 분 필요)
            · MORNING    = 여행 기간 매일 현지 08:00   (일정 0건인 날은 생성 안 함)

[발송]  @Scheduled(fixedDelay = 30s)
        BE: status=PENDING AND scheduled_at <= now() 조회
            → 발송 시점에 payload 조립(제목·시각은 최신 DB 값)
            → 구독별 Web Push 전송 → SENT / FAILED
            → 410 Gone·404 응답이면 구독 삭제

[수신]  SW: push 이벤트 → showNotification(deepLink)
            notificationclick → clients.openWindow('/travel/activities/{id}')
  • payload는 저장하지 않고 발송 시점에 조립한다. §4.2 재계산 트리거에 "제목 변경"이 없으므로, 저장해두면 제목만 고친 일정이 옛 제목으로 알림된다.
  • 스케줄러는 HolidayScheduler 선례를 따른다. replica 1 전제 — 다중 replica가 되면 중복 발송하므로 그때 락(DB 조건부 UPDATE)을 넣는다(결정 기록 참조).
  • VAPID 키쌍은 SealedSecret으로 관리하고 원본은 .secrets에 기록한다.
  • 아침 요약(§4.3)은 여행 생성·기간 변경 시 기간 전체를 한 번에 예약하고, 발송 직전 그날 일정 수를 다시 세어 0건이면 스킵한다.
  • (v2.1) 아침 요약은 날짜에 걸려 있어 재계산 경로가 일정 알림과 다르다. 일정 단위 재계산(rescheduleDate)은 일정 id로 대기 알림을 접고 다시 만드는데, 요약은 어느 일정에도 붙어 있지 않아 그 그물에 걸리지 않는다. 기준 도시 변경 트리거는 요약을 위한 경로(rescheduleMorningSummary)를 따로 태운다.
    • 그 날짜만 다시 잡으면 틀린다. 발송 시각이 "도시가 바뀌는 날인가"에 걸려 있고, 그 판정은 앞 날짜와의 비교다 — N일차 도시를 바꾸면 N일차뿐 아니라 N+1일차의 판정도 뒤집힌다. 두 날짜를 함께 잡는다.
    • 발송 시각과 본문 문구가 같은 판정(MorningCity)을 쓴다. 두 벌이면 오사카 시각에 보내면서 본문은 교토라고 말하는 날이 생긴다.

7. 오프라인 (§4.6)

조회 전용이다. 편집 큐잉·나중 동기화는 하지 않는다. 이것이 설계를 극적으로 단순하게 만든다 — 충돌 해소가 아예 없다.

  • Service Worker는 웹푸시와 공유한다. vite-plugin-pwa(Workbox)를 도입해 앱 셸 precache + 커스텀 SW로 push 핸들러를 함께 담는다.
  • GET /api/travel/** 는 NetworkFirst + 캐시 폴백. 진행 중·예정 여행의 보드/상세는 온라인일 때 자연스럽게 캐시에 적재된다.
  • 편집 mutation은 진입 자체를 막는다(navigator.onLine + online/offline 이벤트). 버튼 비활성 + 배너. 요청이 나가지 않으므로 실패 복구 로직도 없다.
  • 지도·장소 검색·시간대별 예보 갱신은 오프라인에서 진입 불가(§4.6).
  • SW 도입은 일상 워크스페이스에도 영향을 준다(앱 전체가 SW 아래로 들어간다). 배포 후 stale 캐시 리스크가 있으므로 skipWaiting + 버전 갱신 시 새로고침 유도를 함께 넣는다.

8. 사진 — 기존 파이프라인 재사용

일상기록이 이미 쓰는 경로를 그대로 쓴다. 버킷·인프라 변경 없이 travel/ prefix만 추가.

  • FE POST /api/travel/images/upload-url → { uploadUrl, publicUrl, objectKey }
  • FE가 presigned URL로 바이트를 MinIO에 직접 PUT(BE는 데이터 경로 밖)
  • EXIF 제거는 canvas 재인코딩으로 자연 달성된다(§2.5). 원본을 그대로 올리지 않는다.
  • 썸네일도 FE가 canvas로 생성해 2-key 업로드(일상기록과 동일).
  • 저장은 note-images 버킷 travel/activities/{activityId}/{uuid}.jpg
  • 기록 저장과 사진 업로드를 분리한다 — 사진이 실패해도 평점·메모는 이미 저장돼 있어야 한다(§5.1 단계 4 위험 대응).
  • MinIO는 클러스터 내부라 요청 과금이 없다(ELOG-008의 S3 요청료는 AWS S3 이야기). 용량만 모니터링.

⚠️ HEIC는 브라우저 canvas가 디코드하지 못한다(Safari 제외). 타깃이 Android Chrome이라 실사용상 문제되지 않지만, 디코드 실패 시 "지원하지 않는 형식" 안내로 처리한다.

9. 지도

일상기록의 features/lifelog/flow/FlowMap.tsx와 같은 방식(react-leaflet + OSM 타일). 새 지도 라이브러리를 넣지 않는다.

  • 타일: https://tile.openstreetmap.org/{z}/{x}/{y}.png — attribution 필수
  • 마커: var(--primary) 토큰 사용 (FlowMap의 #8b00ff 하드코딩은 레거시, 따라하지 않는다)
  • 연결선: Polyline 직선, vector-effect: non-scaling-stroke
  • fitBounds 여백 10%(§1.4)

10. 단계별 도입 순서

확정 명세 §5의 단계에 인프라 도입 시점을 매핑한 것이다.

단계 신규 인프라 비고
1 (8/7–8/24) 없음 순수 CRUD. 목적지는 수동 입력 + 타임존·통화 Select로 시작하고 Places 연동은 2단계
2 (8/25–9/14) Google Cloud 프로젝트 · Places 키 · Redis 캐시 여기서 처음 유료 API가 붙는다 (Routes는 #1208에서 제거)
3 (9/15–9/28) Service Worker · VAPID 키(SealedSecret) · 알림 스케줄러 가장 무거운 단계. 실기기 3일 연속 검증 필수
4 (9/29–10/12) Workbox 오프라인 캐시 · MinIO travel/ prefix SW는 3단계에서 이미 서 있다

1단계에서 목적지 검색을 빼는 것은 명세 §3(S-03)의 "목적지 검색 → …" 순서를 어기지 않는다 — 화면 순서는 그대로 두고 입력 수단만 2단계에 교체한다. 1단계 마감 기준이 "도쿄 일정을 텍스트만으로 끝까지 만들 수 있다"이므로 정합한다. (결정 기록 D-6)


11. (v2.3) 여행이 자기 경비를 갖는다

2026-09-20에 뒤집혔다. v2.2에서 이 절의 제목은 「여행이 가계부를 읽는다」였다. 경비는 ledger_transaction 위의 읽기 뷰였고, 그 근거는 「원장은 가계부 하나뿐이다」 하나였다. 가계부를 제거하므로 그 근거가 사라졌다 — D-43 · Travel-Expense-Standalone.

경비는 여행 도메인의 테이블(trip_expense)을 갖는다. 이 기능의 아키텍처는 이제 경계 문제가 아니라 **「어디까지 따라오게 두지 않을 것인가」**의 문제다.

11.1 다른 모듈을 읽지 않는다

travel.expense.TripExpenseService
    └─> TripExpenseRepository        (읽기·쓰기 — 여행이 소유한다)
    └─> Trip.budgetAmount            (예산)
    └─> tools.ExchangeRateService    (환율 — 여행/도구가 원래 갖고 있던 것)
  • v2.2에 있던 ledger.* 화살표가 전부 사라진다. 남은 바깥 참조는 ExchangeRateService 하나이고, 그것은 애초에 여행/도구 소유다(EcbRatesClient, ECB 무료)
  • 쓰기도 여행 BE가 받는다. v2.2는 FE가 POST /api/ledger/transactions로 직접 쏘는 구조였다 — 「중계하면 입력 검증·환율 확정이 두 곳에 생긴다」가 그때의 근거였는데, 두 곳 중 한 곳이 없어졌다. 이제 중계가 아니라 그냥 자기 것이다
  • FK도 여행 안에서 닫힌다: trip_expense.trip_id → trip(id) ON DELETE CASCADE

FK 방향과 의미가 함께 뒤집혔다. v2.2는 ledger_transaction.trip_id → trip(id) **SET NULL**이었다 — 「여행을 지워도 쓴 돈은 원장에 남는다」를 DB 제약으로 보장한 것이다. 남을 원장이 없어졌으므로 CASCADE가 된다. 준비 항목(trip_prep_item)과 같은 취급이다: 그 여행이 없으면 아무 뜻도 없다.

11.2 여행 안에 가계부를 다시 짓지 않는다

떼어 내면서 함께 따라오기 쉬운 것들을 명시적으로 막는다. 하나씩은 다 그럴듯하고, 다 붙이면 가계부다.

따라오지 않는 것 대신
ledger_category 고정 프리셋 여섯 (FOOD·TRANSPORT·STAY·SIGHT·SHOPPING·ETC), NULL 허용. 관리 화면·순서·삭제 시 재배정이 전부 안 생긴다
ledger_asset payment_method VARCHAR(40) 자유 텍스트. 잔액을 볼 원장이 사라져 자산이 실체를 가질 이유가 없다
ScheduledPromotionScheduler 새 스케줄러 없음. 지난 예정은 조회가 overdue로 표시하고 사람이 확정한다
자산·잔액·이체·청구서·정기 항목 아무것도. 여행 경비에는 지출만 있다
환불 상쇄 거래 그냥 고치거나 지운다(소프트 삭제). 원장이 아니다

스케줄러를 늘리지 않는 것이 이 절의 유일한 수치 약속이다. 가계부 제거로 앱의 @Scheduled가 7개 → 3개가 되는데(Periodic-Loops), 여기서 하나를 도로 늘리면 방향이 반대다.

11.3 조립은 그대로 여행 쪽에서 한다

GET /trips/{id}/expenses가 하는 일은 출처만 바뀌고 나머지는 v2.2와 같다.

  1. trip_expense에서 trip_id = ?인 행을 occurred_on 순으로 읽는다 (TRANSFER 제외 필터가 없어진다 — 이체라는 개념 자체가 없다)
  2. trip_day와 맞춰 출발 전 / N일차·기준 도시 / 다녀온 뒤로 묶는다
  3. trip.budget_amount와 합쳐 게이지·하루 사용 가능액을 만든다
  • 집계는 전부 amount(원화 환산액)로만 한다. fx_*를 읽는 집계는 하나도 없다 — 있으면 설계가 틀어진 신호다
  • 그룹 라벨을 저장하지 않는다. 기준 도시를 바꾸면 라벨이 따라 움직여야 한다
  • 환율은 저장 시점에 굳는다. 조회에서 다시 계산하지 않는다 — 다녀온 여행의 총액이 매일 바뀌면 그건 사실이 아니라 시세다
  • 「이 달 여행으로 41만」(월 예산 화면 한 줄) — 없어진다. 월 예산 화면이 사라진다

11.4 준비는 여행 안에서 끝난다

trip_prep_item 하나와 CRUD가 전부다. 외부 연동도, 다른 모듈 참조도 없다. 그래서 준비를 먼저 냈다(§16) — 당시 가계부의 어떤 것도 기다리지 않았다. 경비가 독립한 지금은 경비도 같은 모양이 됐다(§11.1).

11.5 준비 알림은 기존 스케줄러에 얹는다

새 스케줄러를 만들지 않는다. push_notification에 type='PREP_REMINDER' 행 하나를 예약하고 기존 NotificationScheduler 폴링이 가져간다.

발송 시각 출발 전날 09:00, trip_day 첫날의 기준 도시 타임존으로 환산해 UTC 저장
예약 시점 여행 생성 · 기간 변경 · 첫날 기준 도시 변경
취소 여행 삭제(CASCADE) · 기간 변경 시 CANCELED 후 재INSERT (기존 재계산 관례 그대로)
본문 발송 직전에 남은 개수를 다시 센다. 0이면 보내지 않는다 — 「내일 출발 · 준비 6개 남았어요」의 6은 예약 시점에는 알 수 없다
안 보내는 경우 ① 남은 게 0개 ② 이미 출발했다 — 「내일 출발」이 거짓이 된다. 둘 다 예약이 아니라 발송 시점에 판정한다(#1326)
  • payload를 저장하지 않는 기존 규칙(§6)이 여기서 그대로 값을 한다. 준비 항목은 알림 예약 후에도 계속 체크되기 때문에, 저장했다면 거의 반드시 틀린 숫자가 나간다
  • activity_id는 NULL이다. 일정 단위 재계산(rescheduleDate)의 그물에 걸리지 않으므로, 아침 요약처럼 자기 경로(reschedulePrepReminder)를 따로 탄다
  • 아침 요약의 재계산 경로에도 얹히지 않는다. 그쪽은 날짜 집합(targetDateIn)으로 찾는데 준비 알림이 가는 날짜는 여행 기간 밖(출발 전날)이라 그 집합에 없다. 그래서 targetDate는 여행의 날짜가 아니라 알림이 가는 날이고, 재계산은 종류로 찾는다(findAllByTripIdAndTypeAndStatus)
  • 「출발했나」의 기준도 첫날 기준 도시의 오늘이다. 여행 상태·D-day·준비 기한이 쓰는 시계와 같은 것을 쓴다
  • 알림 클릭 → /travel/trips/{id}/prep

11.6 여행 스코프 — 라우트가 갖는다

준비·경비는 여행마다 따로다. 그 여행이 어디서 정해지는지를 한 곳으로 고정한다.

정본     /travel/trips/:id/prep · /travel/trips/:id/expenses    ← URL이 여행을 소유한다
폴백     /travel/prep · /travel/expenses                        ← 여행을 고르게 하는 화면(2b)
기본값   진행 중 → 다음 예정 → localStorage(travel.lastTripId) → 폴백
  • localStorage는 진실이 아니다(D-37). 여행 id가 없는 진입에서만 읽고, 요약의 trips[]에 없는 id는 조용히 버린다
  • 사이드바 트리와 폴백 화면은 같은 배열(GET /summary의 trips[])을 읽는다. 두 곳이 다른 출처를 쓰면 사이드바에는 있는데 고를 수는 없는 여행이 생긴다
  • trips[]의 prep·expense는 여행 수에 비례하는 유일한 집계다. 진행 중·예정만 담기 때문에 두어 건으로 끝난다 — 다녀온 여행까지 세면 여행이 쌓일수록 요약이 무거워진다(D-39)

11.7 오프라인

준비·경비 모두 기존 규칙 그대로다(§7). GET /api/travel/trips/*/prep·/expenses는 NetworkFirst 캐시에 얹히고, 쓰기는 진입 자체를 막는다.

경비에만 큐잉을 열지 않는다. 지출은 신호 없는 곳에서 적고 싶은 것이 맞지만, 예외를 하나 열면 준비도 일정도 열어야 하고 그 순간 충돌 해소가 설계에 들어온다 — 이 모듈이 단순한 유일한 이유가 그것이다(확정 명세 §6.2). 대신 금액만으로 저장되는 입력이 나중에 적는 비용을 낮춘다. 리허설에서 놓친 건수를 센다.

Clone this wiki locally