# 04. Local Agent Guide

## 설치

```powershell
cd frontend-prod/flownco-exam-annotation-solution/local-agent
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

## 실행

```powershell
python main.py --host 0.0.0.0 --port 8787 --token dev-local-token
```

## IP/Port 설정

SaaS 설정 화면에서 다음 값을 입력한다.

- protocol: `http` 또는 `https`
- host: `127.0.0.1`, `localhost`, `192.168.0.25`, 유동 공인 IP
- port: `8787`
- agent token: 실행 시 지정한 token

## 유동 IP 사용 시 주의사항

공인 IP가 바뀌면 SaaS 설정에 저장된 host 값을 수정해야 한다. 외부망에서 접근할 경우 방화벽, 공유기 포트포워딩, HTTPS 구성을 별도로 확인해야 한다.

`https://www.flownco.co.kr`에서 공인 IP의 `http://IP:8787`로 직접 요청하면 브라우저 mixed content 정책에 의해 차단될 수 있다. 외부망 운영은 Local Agent를 HTTPS로 열거나, 사내 VPN, Tailscale, Cloudflare Tunnel, ngrok 같은 안전한 터널을 사용한다. 로컬 PC 같은 브라우저에서 `localhost` 또는 내부망 IP로 테스트할 때도 CORS 허용 origin을 확인한다.

## Health Check

```http
GET http://127.0.0.1:8787/health
Authorization: Bearer dev-local-token
```

응답 예시:

```json
{
  "ok": true,
  "agentVersion": "0.1.0",
  "localOnlyMode": true,
  "externalApiAllowed": false
}
```

## 시험지 파일 처리 요청

웹 업로드 화면은 먼저 Flownco SaaS API에 프로젝트와 업로드 파일 메타데이터를 저장한 뒤, 브라우저에서 사용자가 입력한 Local Agent 주소로 시험지 파일을 직접 전송한다. 공개 SaaS 요청 본문 제한을 피하기 위해 원본 파일 base64는 SaaS 문서 저장 API로 보내지 않는다. Flownco 서버가 사용자가 입력한 IP로 proxy 요청하지 않는다.

```http
POST http://127.0.0.1:8787/scan/upload-and-recognize
Authorization: Bearer dev-local-token
Content-Type: application/json
```

요청 본문은 프로젝트 ID, providerKey, 최대 5장 제한을 통과한 파일 목록을 포함한다. MVP mock mode에서는 Local Agent가 원본 파일을 장기 저장하지 않고 인식 후보 JSON만 반환한다. 반환된 `recognitionResults`와 `unreadableAreas`는 웹 브라우저가 다시 SaaS API로 저장하므로 관리자 페이지에서 조회할 수 있다.