diff --git a/docs/PREDICTION-GUIDE.md b/docs/PREDICTION-GUIDE.md deleted file mode 100644 index 9b90b98..0000000 --- a/docs/PREDICTION-GUIDE.md +++ /dev/null @@ -1,191 +0,0 @@ -# 확산 예측 기능 가이드 - -> 대상: 확산 예측(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) — 인증·상태관리 공통 로직