24 lines
2.0 KiB
Markdown
24 lines
2.0 KiB
Markdown
---
|
|
document_type: backend
|
|
priority: HIGH
|
|
---
|
|
# 백엔드 & 데이터베이스 제어 명세
|
|
|
|
## 🐍 백엔드 (FastAPI / Python)
|
|
- **파일 분할:** 라우터(`_Router.py`), 비즈니스 로직(`_Engine.py`), 스키마(`_Schema.py`), DB 접근(`_Repository.py`) 형태로 세분화.
|
|
- **데이터 검증:** 모든 JSON 요청은 Pydantic 모델을 통해 라우터 진입 전 타입/범위 필수 검증.
|
|
- **예외 처리:** 지형/메쉬 연산 등 복잡한 로직 수행 시 `try-except` 필수 처리. 에러 발생 시 `{"status": "error", "message": "원인"}` 반환 표준 포맷 유지.
|
|
|
|
## 🗄️ 데이터베이스 (MariaDB)
|
|
- **[MUST]** 비동기 통신: `aiomysql` 드라이버 사용 강제. (`asyncmy` 사용 불가)
|
|
- **[DON'T]** ORM 사용 금지: 오직 **Raw SQL**만 작성한다.
|
|
- **[MUST]** 파라미터 바인딩: `%s` 플레이스홀더를 사용하여 SQL Injection 방지.
|
|
- **트랜잭션:** `pool.acquire()`로 커넥션 확보 후 다건 쓰기는 `connection.begin()` → `commit()` / 예외 시 `rollback()` 필수.
|
|
- **자동 증가 ID:** `INSERT` 후 `cursor.lastrowid`로 조회.
|
|
- **공간 데이터 처리:** MariaDB의 GEOMETRY 타입 한계로 인해, 공간 기하 데이터(좌표, 다각형, 경로 등)는 JSON (GeoJSON 형식)으로 저장 후 애플리케이션(Python Shapely/Geopandas)에서 파싱하여 기하 연산을 처리한다.
|
|
|
|
## 🔄 워크플로우 상태 동기화 (Sync)
|
|
- **공유 상태:** 다중 브라우저 대응을 위해 각 프로젝트는 `workflow.json`으로 현재 진행 단계와 'stale(무효화)' 상태를 관리한다.
|
|
- **Stale 전파:** 상위 단계(예: 지표면 분석)가 재실행되면 하위 단계들은 자동으로 `stale_from`으로 표기되며, 클라이언트는 3초 주기의 폴링(Polling)을 통해 상태를 확인하고 경고/재계산을 유도한다.
|
|
- **원자적 쓰기:** `workflow.json` 상태 업데이트는 `common_util_workflow.py`를 통해 원자적 업데이트로 보호되어야 한다.
|