# 확산 예측 기능 가이드

> 대상: 확산 예측(OpenDrift) 기능 개발 및 유지보수 담당자

---

## 1. 아키텍처 개요

**폴링 방식** — HTTP 연결 불안정 문제 해결을 위해 비동기 폴링 구조를 채택했다.

```
[프론트] 실행 버튼
  → POST /api/simulation/run        즉시 { execSn, status:'RUNNING' } 반환
  → "분석 중..." UI 표시
  → 3초마다 GET /api/simulation/status/:execSn 폴링

[Express 백엔드]
  → PRED_EXEC INSERT (PENDING)
  → POST Python /run-model          즉시 { job_id } 수신
  → 응답 즉시 반환 (프론트 블록 없음)
  → 백그라운드: 3초마다 Python GET /status/:job_id 폴링
  → DONE 시 PRED_EXEC UPDATE (결과 JSONB 저장)

[Python FastAPI :5003]
  → 동시 처리 초과 시 503 즉시 반환
  → 여유 시 job_id 반환 + 백그라운드 OpenDrift 시뮬레이션 실행
  → NC 결과 → JSON 변환 → 상태 DONE
```

---

## 2. DB 스키마 (PRED_EXEC)

```sql
PRED_EXEC_SN  SERIAL PRIMARY KEY
ACDNT_SN      INTEGER NOT NULL        -- 사고 FK
SPIL_DATA_SN  INTEGER                 -- 유출정보 FK (NULL 허용)
EXEC_NM       VARCHAR(100) UNIQUE     -- EXPC_{timestamp} 형식
ALGO_CD       VARCHAR(20) NOT NULL    -- 'OPENDRIFT'
EXEC_STTS_CD  VARCHAR(20) DEFAULT 'PENDING'
              -- PENDING | RUNNING | COMPLETED | FAILED
BGNG_DTM      TIMESTAMPTZ
CMPL_DTM      TIMESTAMPTZ
REQD_SEC      INTEGER
RSLT_DATA     JSONB                   -- 시뮬레이션 결과 전체
ERR_MSG       TEXT
```

인덱스: `IDX_PRED_STTS` (EXEC_STTS_CD), `uix_pred_exec_nm` (EXEC_NM, partial)

---

## 3. Python FastAPI 엔드포인트 (포트 5003)

| 메서드 | 경로 | 설명 |
|--------|------|------|
| GET | `/get-received-date` | 최신 예보 수신 가능 날짜 |
| GET | `/get-uv/{datetime}/{category}` | 바람/해류 U/V 벡터 (`wind`\|`hydr`) |
| POST | `/check-nc` | NetCDF 파일 존재 여부 확인 |
| POST | `/run-model` | 시뮬레이션 제출 → 즉시 `job_id` 반환 |
| GET | `/status/{job_id}` | 시뮬레이션 진행 상태 조회 |

### POST /run-model 입력 파라미터

```json
{
  "startTime": "2025-01-15 12:00:00",  // KST (내부 UTC 변환)
  "runTime": 72,                        // 예측 시간 (시간)
  "matTy": "CRUDE OIL",                // OpenDrift 유류명
  "matVol": 100.0,                     // 시간당 유출량 (m³/hr)
  "lon": 126.1,
  "lat": 36.6,
  "spillTime": 12,                     // 유출 지속 시간 (0=순간)
  "name": "EXPC_1710000000000"
}
```

### 유류 코드 매핑 (DB → OpenDrift)

| DB SPIL_MAT_CD | OpenDrift 이름 |
|---------------|---------------|
| CRUD | CRUDE OIL |
| DSEL | DIESEL |
| BNKR | BUNKER |
| HEFO | IFO 180 |

---

## 4. Express 백엔드 주요 엔드포인트

파일: [backend/src/routes/simulation.ts](../backend/src/routes/simulation.ts)

| 메서드 | 경로 | 설명 |
|--------|------|------|
| POST | `/api/simulation/run` | 시뮬레이션 제출 → `execSn` 즉시 반환 |
| GET | `/api/simulation/status/:execSn` | 프론트 폴링용 상태 조회 |

파일: [backend/src/prediction/predictionService.ts](../backend/src/prediction/predictionService.ts)

- `fetchPredictionList()` — PRED_EXEC 목록 조회
- `fetchTrajectoryResult()` — 저장된 결과 조회 (`RSLT_DATA` JSONB 파싱)

---

## 5. 프론트엔드 주요 파일

| 파일 | 역할 |
|------|------|
| [frontend/src/tabs/prediction/components/OilSpillView.tsx](../frontend/src/tabs/prediction/components/OilSpillView.tsx) | 예측 탭 메인 뷰, 시뮬레이션 실행·폴링 상태 관리 |
| [frontend/src/tabs/prediction/hooks/](../frontend/src/tabs/prediction/hooks/) | `useSimulationStatus` 폴링 훅 |
| [frontend/src/tabs/prediction/services/predictionApi.ts](../frontend/src/tabs/prediction/services/predictionApi.ts) | API 요청 함수 + 타입 정의 |
| [frontend/src/tabs/prediction/components/RightPanel.tsx](../frontend/src/tabs/prediction/components/RightPanel.tsx) | 풍화량·잔류량·오염면적 표시 (마지막 스텝 실제 값) |
| [frontend/src/common/components/map/HydrParticleOverlay.tsx](../frontend/src/common/components/map/HydrParticleOverlay.tsx) | 해류 파티클 Canvas 오버레이 |

### 핵심 타입 (predictionApi.ts)

```typescript
interface HydrGrid {
  lonInterval: number[];
  latInterval: number[];
  boundLonLat: { top: number; bottom: number; left: number; right: number };
  rows: number; cols: number;
}
interface HydrDataStep {
  value: [number[][], number[][]];  // [u_2d, v_2d]
  grid: HydrGrid;
}
```

### 폴링 훅 패턴

```typescript
useQuery({
  queryKey: ['simulationStatus', execSn],
  queryFn: () => api.get(`/api/simulation/status/${execSn}`),
  enabled: execSn !== null,
  refetchInterval: (data) =>
    data?.status === 'DONE' || data?.status === 'ERROR' ? false : 3000,
});
```

---

## 6. Python 코드 위치 (prediction/)

```
prediction/opendrift/
├── api.py            FastAPI 진입점 (수정 필요: 폴링 지원 + CORS)
├── config.py         경로 설정 (수정 필요: 환경변수화)
├── createJsonResult.py  NC → JSON 변환 (핵심 후처리)
├── coastline/        TN_SHORLINE.shp (한국 해안선)
├── startup.sh / shutdown.sh
├── .env.example      환경변수 샘플
└── environment-opendrift.yml  conda 환경 재현용
```

---

## 7. 환경변수

### backend/.env

```bash
PYTHON_API_URL=http://localhost:5003
```

### prediction/opendrift/.env

```bash
MPR_STORAGE_ROOT=/data/storage    # NetCDF 기상·해양 데이터 루트
MPR_RESULT_ROOT=./result          # 시뮬레이션 결과 저장 경로
MAX_CONCURRENT_JOBS=4             # 동시 처리 최대 수
```

---

## 8. 위험 요소

| 위험 | 내용 |
|------|------|
| NetCDF 파일 부재 | `MPR_STORAGE_ROOT` 경로에 KMA GDAPS·MOHID NC 파일 필요. 없으면 시뮬레이션 불가 |
| conda 환경 | `opendrift` conda 환경 설치 필요 (`environment-opendrift.yml`) |
| Workers 포화 | 동시 4개 초과 시 503 반환 → `MAX_CONCURRENT_JOBS` 조정 |
| 결과 용량 | 12시간 결과 ≈ 1500KB/건. 90일 주기 `RSLT_DATA = NULL` 정리 권장 |

---

## 9. 관련 문서

- [CRUD-API-GUIDE.md](./CRUD-API-GUIDE.md) — Express API 개발 패턴
- [COMMON-GUIDE.md](./COMMON-GUIDE.md) — 인증·상태관리 공통 로직