README.md

metadata

title: CAAINP Backend
emoji: 🧭
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit

caanip-backend

개요

이 프로젝트는 실내 네비게이션을 위한 백엔드 API를 제공합니다. 사용자의 자연어 요청과 현장 이미지를 받아 네비게이션 안내를 생성합니다.

설치 및 실행

사전 요구사항

• Python 3.12 이상
• uv

설치

uv sync

실행

uvicorn server:app --reload

서버는 기본적으로 http://localhost:8000에서 실행됩니다.

API 문서는 http://localhost:8000/docs에서 확인할 수 있습니다.

API 엔드포인트

POST /api/navigation/start

• 자연어 요청과 시작 방, 현장 이미지를 받아 네비게이션 세션을 생성하고 첫 안내를 반환
• Form 데이터: request_text(자연어 요청), start_room(시작 방 번호), File: image(현장 이미지)
• 응답: 첫 네비게이션 안내(JSON). 세션 상태가 CAAINP-NAVIGATION-COOKIE에 저장됨.

POST /api/navigation/step

• 쿠키에 저장된 세션 상태(plan, prev_node)를 사용해 다음 단계 안내를 반환
• File: image(현장 이미지)
• 세션이 없으면 { "status": "error", "message": "/api/navigation/start를 먼저 호출하세요." } 반환
• 응답 예시:

{
  "schema_version": 1,
  "current_node": 4106,
  "next_node": 4103,
  "move_instruction": {
    "direction_type": "STRAIGHT",
    "angle_deg": 0.0,
    "text_ko": "직진하세요."
  },
  "route_summary": {
    "current_step": 1,
    "total_steps": 3,
    "remaining_steps_text": "엘리베이터 → 4층 410호 → 7층 7201호 순으로 이동",
    "via_nodes": [4150, 410, 7201]
  }
}

POST /api/navigation/reset

• 저장된 네비게이션 쿠키 삭제 후 세션 초기화
• 응답: { "status": "success", "message": "네비게이션 세션이 초기화되었습니다." }

POST /api/navigation/mock

• 실제 엔진 대신 모의 응답 반환(디버깅/프론트엔드 연동용)
• Form: request_text, File: image
• 응답: 모의 네비게이션 JSON

GET /api/cookie/get

• 현재 요청의 CAAINP-NAVIGATION-COOKIE 값을 조회
• 응답: { "cookie": {plan, prev_node} | null }

GET /api/cookie/delete

• 네비게이션 쿠키 삭제
• 응답: { "status": "success", "message": "쿠키가 성공적으로 삭제되었습니다." }

테스트

uv run tests/navigation_test.py

프로젝트 구조

caanip-backend/
├── server.py              # FastAPI 애플리케이션 메인 파일
├── mock_responses.py      # 모의 네비게이션 응답 생성 모듈
├── pyproject.toml         # 프로젝트 설정 및 의존성
└── README.md             # 프로젝트 문서