Skip to content

Lifelog API Spec

wcorn edited this page Jul 23, 2026 · 1 revision

API 설계: 일상기록 (Lifelog)

유스케이스 · 아키텍처 · 데이터 모델

Base: /api/lifelog. 인증: JWT(모든 엔드포인트). 응답은 orino 공통 envelope { code, data }(CustomResponseCode). 에러는 { code: "GLB-ERR-XXX", message }.

1. 엔드포인트 요약

그룹 메서드 경로 설명
이미지 POST /api/lifelog/images/upload-url presigned PUT URL 발급(원본/썸네일)
지오코딩 GET /api/lifelog/geocode/reverse 좌표→장소명
지오코딩 GET /api/lifelog/geocode/search 검색어→후보 좌표
기록 POST /api/lifelog/moments 기록 생성
기록 GET /api/lifelog/moments 피드(커서 페이지네이션)
기록 GET /api/lifelog/moments/{id} 단건 조회
기록 PUT /api/lifelog/moments/{id} 수정
기록 DELETE /api/lifelog/moments/{id} 삭제
태그 GET /api/lifelog/tags?q= 태그 자동완성
흐름 POST /api/lifelog/flows 흐름 생성
흐름 GET /api/lifelog/flows 흐름 목록
흐름 GET /api/lifelog/flows/{id} 흐름 상세(담긴 기록 포함)
흐름 PUT /api/lifelog/flows/{id} 흐름 수정
흐름 DELETE /api/lifelog/flows/{id} 흐름 삭제(기록 보존)
흐름 POST /api/lifelog/flows/{id}/moments 기록 담기
흐름 DELETE /api/lifelog/flows/{id}/moments/{momentId} 기록 빼기
흐름 PUT /api/lifelog/flows/{id}/moments/order 흐름 내 순서 조정

2. 이미지

POST /api/lifelog/images/upload-url

사진 1개(원본 또는 썸네일)에 대한 presigned PUT URL. 기존 노트 파이프라인과 동일 방식, lifelog prefix.

// Request
{ "contentType": "image/jpeg", "kind": "ORIGINAL" }   // kind: ORIGINAL | THUMB
// Response.data
{
  "uploadUrl": "https://minio.../note-images/lifelog/moments/tmp/uuid.jpg?X-Amz-...",
  "publicUrl": "https://img.orino.dev/lifelog/moments/tmp/uuid.jpg",
  "objectKey": "lifelog/moments/tmp/uuid.jpg"
}
  • FE는 원본·썸네일 각각 호출 → 각 uploadUrl로 직접 PUT → moment 생성 시 objectKey/thumbKey 전달.
  • 키 prefix tmp/로 올리고 moment 확정 시 최종 경로 규칙을 따르되, MVP는 objectKey를 그대로 저장(이동 없음).

3. 지오코딩 (BE 프록시 + Redis 캐시)

GET /api/lifelog/geocode/reverse?lat={}&lng={}

// Response.data
{ "placeName": "제주특별자치도 서귀포시 성산읍", "lat": 33.458, "lng": 126.942 }

GET /api/lifelog/geocode/search?q={검색어}

// Response.data
[ { "placeName": "성산일출봉", "lat": 33.458, "lng": 126.942 }, ... ]  // 상위 N개
  • Nominatim 정책 준수(캐시·rate limit·User-Agent). 캐시 히트 시 외부 호출 없음.

4. 기록 (Moment)

POST /api/lifelog/moments

// Request
{
  "occurredAt": "2026-07-20T14:30:00",      // 없으면 서버 현재시각
  "body": "성산일출봉 정상. 바람 미침",
  "mood": "excited",                          // nullable
  "lat": 33.458, "lng": 126.942,              // nullable (쌍으로)
  "placeName": "성산일출봉",                   // nullable (FE가 reverse 결과 전달, 미전달 시 BE가 조회)
  "tags": ["제주", "여행", "등산"],
  "photos": [
    { "objectKey": "lifelog/.../a.jpg", "thumbKey": "lifelog/.../a_t.jpg",
      "width": 4032, "height": 3024,
      "exifTakenAt": "2026-07-20T14:31:10", "exifLat": 33.458, "exifLng": 126.942,
      "sortOrder": 0 }
  ]
}
// Response.data → MomentCard (아래 §4 공통 스키마)

검증: lat/lng는 함께 오거나 함께 없음. photos[].objectKey 필수. body·photos 둘 다 비면 400(GLB-ERR-XXX 빈 기록 불가).

GET /api/lifelog/moments?cursor={}&size=20&tag={}&from={}&to={}

역시간순 피드. 필터: tag, 기간 from/to(occurred_at).

// Response.data
{
  "items": [ /* MomentCard[] */ ],
  "nextCursor": "2026-07-20T14:30:00_1234"   // null이면 마지막
}

GET /api/lifelog/moments/{id} → MomentCard

PUT /api/lifelog/moments/{id}

POST와 동일 바디. photos는 전체 치환(추가/삭제/순서변경을 최종 배열로 표현). 제거된 사진 key는 BE가 MinIO best-effort delete.

DELETE /api/lifelog/moments/{id} → 204. 담긴 모든 흐름에서 자동 제거(CASCADE), 사진 MinIO 정리.

MomentCard 공통 스키마

{
  "id": 1234,
  "occurredAt": "2026-07-20T14:30:00",
  "body": "...", "mood": "excited",
  "lat": 33.458, "lng": 126.942, "placeName": "성산일출봉",
  "tags": ["제주","여행"],
  "photos": [
    { "id": 1, "url": "https://img.orino.dev/lifelog/.../a.jpg",
      "thumbUrl": "https://img.orino.dev/lifelog/.../a_t.jpg",
      "width": 4032, "height": 3024, "sortOrder": 0 }
  ],
  "flows": [ { "id": 7, "title": "제주 여행 2박3일" } ],   // 이 기록이 담긴 흐름(요약)
  "createdAt": "2026-07-20T14:35:00"
}

GET /api/lifelog/tags?q={접두어} → ["제주","제주도","제주여행"]

DISTINCT name WHERE name LIKE 'q%' 상위 N개(자동완성).


5. 흐름 (Flow)

POST /api/lifelog/flows

{ "title": "제주 여행 2박3일", "description": "2026 여름" }
// Response.data → FlowSummary

GET /api/lifelog/flows?status=ACTIVE

// Response.data → FlowSummary[]
[ { "id": 7, "title": "제주 여행 2박3일",
    "coverUrl": "https://img.orino.dev/...",   // cover 없으면 담긴 첫 사진
    "startedAt": "2026-07-20T09:00:00", "endedAt": "2026-07-22T18:00:00",
    "momentCount": 42, "status": "ACTIVE" } ]

GET /api/lifelog/flows/{id} → FlowDetail

{
  "id": 7, "title": "...", "description": "...", "status": "ACTIVE",
  "startedAt": "...", "endedAt": "...", "coverUrl": "...",
  "moments": [ /* MomentCard[] — 정렬: sort_order 우선, 없으면 occurredAt ASC */ ]
}

지도 뷰는 이 응답의 moments[].lat/lng를 그대로 사용(별도 엔드포인트 없음).

PUT /api/lifelog/flows/{id}

{ "title": "...", "description": "...", "coverObjectKey": "lifelog/...", "status": "ARCHIVED" }

DELETE /api/lifelog/flows/{id} → 204. flow_moment만 제거, 기록 보존.

POST /api/lifelog/flows/{id}/moments

{ "momentId": 1234 }        // 또는 { "momentIds": [1,2,3] } 다건
// 이미 담겨 있으면 멱등(중복 무시)

DELETE /api/lifelog/flows/{id}/moments/{momentId} → 204. 기록 보존, 소속만 제거.

PUT /api/lifelog/flows/{id}/moments/order

{ "momentIds": [1234, 1200, 1301] }   // 이 순서로 flow_moment.sort_order 재기록

6. 에러 코드 (신규, ErrorCode enum에 추가)

코드(예시) 상황
GLB-ERR-LIFELOG-001 존재하지 않는 moment
GLB-ERR-LIFELOG-002 존재하지 않는 flow
GLB-ERR-LIFELOG-003 빈 기록(본문·사진 모두 없음)
GLB-ERR-LIFELOG-004 좌표 lat/lng 짝 불일치
GLB-ERR-LIFELOG-005 지오코딩 외부 호출 실패(캐시 미스 + Nominatim 오류)

실제 코드 번호·prefix는 기존 ErrorCode 컨벤션에 맞춰 구현 시 확정.

7. 관련 문서

Clone this wiki locally