2.0 KiB
2.0 KiB
document_type, priority
| document_type | priority |
|---|---|
| backend | 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를 통해 원자적 업데이트로 보호되어야 한다.