README.md

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

# caanip-backend

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

## 설치 및 실행

### 사전 요구사항

- Python 3.12 이상
- uv

### 설치

```bash
uv sync
```

### 실행

```bash
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를 먼저 호출하세요." }` 반환
- 응답 예시:
```json
{
  "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": "쿠키가 성공적으로 삭제되었습니다." }`

## 테스트
```bash
uv run tests/navigation_test.py
```

## 프로젝트 구조

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