지금이니? API 설계 초안
- 문서 버전: 0.97 · 작성일: 2026-09-30 · 수정일: 2026-10-19 (개인 이동 설정 저장)
- 프론트엔드: React · 백엔드: Python FastAPI
- 상태: 기획/미구현 계약과 일부 구현을 함께 기록. GET /health·공통 요청 처리/로그 및17절 기본 회원 인증은 구현, F03-01~03 장소 검색/저장/본인 조회·지도 핀/출입구·이름 수정/삭제는 구현, F03-04 출발지 입력 확인·단발 현재 위치/지도/본인 저장 장소 선택은 구현. F03-05a 수동 확인은 구현/검증 완료이며 GPS 수치/자동 일치 판정은 사용자 결정으로 보류. F04-01 depart_now 대중교통 후보 조회 API 및F04-02 공통 구간 모델은 구현, F04-03 후보 비교 화면은 구현. F06-01 루틴 저장·상세 API와 비교 화면 저장 연동, F06-02 루틴 요일·목표 도착 저장(저장 입력과 일정 PATCH 포함)은 구현. F06-03 본인 목록·선택·이름/일정/경로 수정·삭제와 F06-03a 루틴 등록 중 장소 저장·선택은 구현·검증 완료. F06-04 장소 변경/삭제 루틴 복구 안내도 구현·검증 완료. F03-02a 검색 없는 지도 핀 저장·자동 선택도 구현·검증 완료. F05-01 기존 후보 도보 근거·누락 조회 API도 구현·검증 완료. F05-02 서버 내부 프롬프트 블록·버전 로딩도 구현·검증 완료. F05-03 서버 내부 AI 최소 입력/구조화 결과 검증과 실제 합성 최소 호출도 구현·검증 완료. F05-04 내부 산정/품질 이력 저장과 본인 상세 조회도 구현·검증 완료. F05-05 서버 내부 조건별 전체/부분 재사용도 구현·검증 완료. F05-06 내부 개인 계수 재계산·경로 변경/만료 무효화도 구현·검증 완료. F05-07 루틴/후보 상세의 근거 부족·실내 이동·실패/만료 화면 안내도 구현·검증 완료. F07-01a 기반/F07-01b 경기 매핑·본인GET·사용자 승인 수신 기준 추정은 구현·검증 완료, 원천 시간/갱신지연·지원 범위 강화는 F07-01c 후속으로 F07-01 전체 미완료. F07-02 후보 첫 버스 예상 출발 계산은 사용자 승인 공급자 접근 개인화 추정으로 구현·검증 완료. F07-03 지원 경기버스의 선택적 순차 환승 검사는 구현·검증 완료이며 미지원/근거부족은unknown이다. F07-02a-1 루틴 선택→최신 첫출발 연결은 구현·검증 완료. F07-02a-2 지원 경기BUS 루틴의 누락 접근도보 보완도 구현·검증 완료. F07-05 유효 첫출발의 남은 시간/현재 기준 정류장여유 안내도 구현·검증 완료. F07-04 선택 루틴의 현재후보 오늘목표도착 평가는 구현·검증 완료. F07-02a-4 지원 BUS 루틴의 검증 접근 도보 AI 산정·저장/재사용·첫출발 연결은 구현·검증 완료. 역 내부·AI 환승/마지막 도보와 미래예약/목표기반 대체경로 자동조회는 미구현. F12 일회성 약속 코어 REST(생성/목록/상세/수정/직접 목적지 확정/상태 전이/삭제/참여 탈퇴)와 초대 발급·철회·미리보기·수락은 구현·검증 완료이며 추천 기반 확정·개인 출발지·출발 안내·공유·채팅·WS는 미구현. F08-01 루틴 안내 연결 이동 세션 및F08-02a 수동 departed 신고·본인 복구/취소는 구현·검증 완료. F07-06b 절반경과 전환은 지원 경기 BUS 루틴 범위에서 구현·검증 완료. F07-07a 첫 탑승 전 확인한 현재점의 남은 경로 안내는 구현·검증 완료. F08-02b 첫 접근 완료·탑승 수동 기록·복구도 구현·검증 완료. F07-07b-1 진행 구간·환승 현재점 안내와F08-03a 차량별 하차/다음 탑승도 구현·검증 완료. F08-03b 수동 놓침·목적지 도착/종료도 구현·검증 완료. F07-07b-2 지원 BUS의 명시 차량 확인/동일 차량 공식 하차 예측·실서버 통합/PC·모바일 검증은 완료. 실제 탑승 인증·원천 최신성/실측 정확도·미래 배차와 정정/학습·전체F07-07은후속. 세부 완료 상태는
todo.md를 따른다.
- 기준: 대화에서 확정한 요구사항 및 프로젝트
C:/projects/timeisnow 폴더의 planning.md, feature_breakdown.md, personalization.md, logging.md, ai_prompts.md.
- 이 페이지는 수동 관리하는 설계 문서다. 코드와 자동 동기화되는 상태가 아니다.
1. 읽는 방법
API는 React가 FastAPI에 요청하는 약속이다. GET은 조회, POST는 생성·처리 요청, PATCH는 일부 수정, DELETE는 삭제에 사용한다. 경로의 중괄호는 실제 ID로 바꾸는 자리다.
필수 기능: 회원가입·개인 저장, 현재 위치와 집·회사, 환승, AI 도보 산정, 저장값 재사용, 초기 5분 여유, 실제 관측과 개인화, 품질 이력과 로깅.
확정: DB는 PostgreSQL, 로컬 개발 DB는 Docker Compose 컨테이너와 영속 볼륨으로 운영한다. React는 DB에 직접 접근하지 않고 FastAPI를 통한다.
인증 확정: 이메일·비밀번호. 소셜 로그인은 후속 검토.
확정: 지원 지역은 서울특별시·경기도, 카카오맵 사용. 미정: 메일·실시간 교통 공급자, 배포 주소. 최대 환승은 첫 출시 2회로 확정(20절). AI 공급자는 OpenAI, 모델은 GPT-5.6 Luna (gpt-5.6-luna)로 사용자 확정. 사용자가 승인한 커스텀 AI 서버로 최소 연결 확인 완료. 예산·데이터 전달 조건·실제 서비스 품질 검증은 미완료. 카카오맵 선정과 실시간 ID 매핑·저장/AI 전달·실호출 검증 완료는 구분하며 상세 상태는 18절을 따른다.
2. 공통 규칙
- API 기본 경로:
/api/v1. 아래 표는 이 접두사를 생략한다. 실제 서버 URL은 미정이다.
- 요청·응답: JSON, 필드명 snake_case. ID 예시는 가상 값이며 실제 ID는 불투명 문자열로 취급한다.
- 절대 시각: 시간대가 포함된 ISO 8601. 저장·로그는 UTC, 화면은 사용자 시간대. 길이는 초, 거리는 미터.
- 성공:
{"data": ..., "meta": {"request_id": "...", "server_time": "..."}}. 204는 본문 없이 X-Request-ID 헤더만 반환한다.
- 목록:
data.items와 data.next_cursor. limit 기본 20, 최대 100으로 확정한다.
- 오류: error.code, error.message, error.details 및 meta. 잘못된 입력 전문·토큰·주소를 오류 메시지에 되돌려주지 않는다.