Aislo/.agent/backend.md

백엔드 제어 명세서 (backend.md)

1. 아키텍처 및 라우팅 (Architecture)

• 수직 통합: 백엔드 로직은 페이지 폴더(A01_, B01_ 등)별로 격리. 거대 단일 모듈 금지.
• 파일 분할: 파일 수 제한 없음. 코드 집중 방지를 위해 기능별 분할 자율화.
• 파일명 규칙: [폴더명]_Router.py, [폴더명]_Engine.py, [폴더명]_Schema.py 형태 준수.
• 루트 main.py: 라우터 등록(include_router)만 수행. 비즈니스 로직 작성 금지.

---

2. DB 및 PostGIS (Database)

• 비동기 통신: async/await 및 asyncpg 드라이버 사용 강제.
• 공간 연산: ORM 사용 금지. ST_Volume, ST_Distance 등 PostGIS 기반 Raw SQL 작성 원칙.

---

3. 설정 및 저장소 (Config & Storage)

• 하드코딩 금지: 제어 변수/파라미터 하드코딩 금지. config/config_system.py에서 import 필수.
• 물리 파일 격리: 포인트 클라우드, 분석 중간 파일, 메쉬, 임시 커서는 DB 저장 금지.
• 저장 경로: storage/[고객사명]/[사용자명]/[프로젝트ID]/에 물리 파일 저장 후 DB에는 경로만 기록.

---

4. 검증 및 예외 처리 (Error Handling)

• 데이터 검증: 모든 JSON 요청은 라우터 진입 전 Pydantic 모델로 타입/범위 필수 검증.
• 예외 포획: 모든 지형/메쉬 연산은 try-except 필수 처리.
• 반환 포맷: 에러 발생 시 {"status": "error", "message": "원인"} 표준 포맷 반환.