260705_2

.agent/backend.md

@@ -8,9 +8,12 @@
 
 ---
 
-## 2. DB 및 PostGIS (Database)
-* **비동기 통신:** `async/await` 및 `asyncpg` 드라이버 사용 강제.
-* **공간 연산:** ORM 사용 금지. `ST_Volume`, `ST_Distance` 등 PostGIS 기반 **Raw SQL** 작성 원칙.
+## 2. DB 및 MariaDB (Database)
+* **비동기 통신:** `async/await` 및 `aiomysql` 드라이버 사용 강제. (asyncmy는 Cython 빌드 필요로 Windows 환경 미채택)
+* **쿼리 방식:** ORM 사용 금지. **Raw SQL** 작성 원칙. 파라미터 바인딩은 `%s` 플레이스홀더 사용.
+* **커넥션/트랜잭션:** 풀에서 `pool.acquire()`로 커넥션 확보 후 `connection.cursor()`로 커서 생성. 다건 쓰기는 `connection.begin()` → `commit()` / 예외 시 `rollback()`.
+* **자동 증가 ID:** `INSERT` 후 `cursor.lastrowid`로 조회 (PostgreSQL의 `RETURNING id` 미지원).
+* **공간 데이터:** GEOMETRY 타입 미지원. 좌표, 다각형, 경로 등은 JSON 형식으로 저장 후 애플리케이션에서 처리.
 
 ---
 
@@ -18,6 +21,14 @@
 * **하드코딩 금지:** 제어 변수/파라미터 하드코딩 금지. `config/config_system.py`에서 `import` 필수.
 * **물리 파일 격리:** 포인트 클라우드, 분석 중간 파일, 메쉬, 임시 커서는 DB 저장 금지.
 * **저장 경로:** `storage/[고객사명]/[사용자명]/[프로젝트ID]/`에 물리 파일 저장 후 DB에는 경로만 기록.
+* **단계별 루트 강제:** 프로젝트 저장소 내부는 실제 워크플로우 페이지명과 동일한 `B03_FileInput/` ~ `B09_wf6_Estimation/` 폴더로 분리한다. `raw/`, `processed/`, `computed/`를 프로젝트 루트의 공용 폴더로 만들지 않는다.
+* **경로 정의 우선순위:** 단계별 세부 폴더와 DB 경로 열의 기준은 `.agent/db_schema_simple.md`의 「파일시스템 경로와 DB 링크」를 따른다.
+* **경로 생성 책임:** 페이지별 백엔드는 자기 단계 폴더만 생성·수정한다. 다른 단계의 산출물을 직접 삭제하거나 덮어쓰지 않고 stale 상태를 통해 재계산 필요성을 전파한다.
+* **DB 저장 형식:** DB에는 프로젝트 루트 기준 상대 경로를 기록하고, 실제 파일 접근 시 설정의 저장소 루트와 안전하게 결합한다. 사용자 입력 경로를 직접 결합하거나 절대 경로를 DB에 저장하지 않는다.
+* **MariaDB 특성:** 
+  - 공간 기하 데이터(좌표, 폴리곤, 경로 등)는 GEOMETRY 타입 미지원 → JSON 또는 TEXT로 저장
+  - 예: `{"type": "Point", "coordinates": [127.5, 37.5]}` (GeoJSON 형식)
+  - 애플리케이션(Python)에서 JSON 파싱 후 기하 연산 처리
 
 ---
 
@@ -33,11 +44,12 @@
 ### 5.1 다중 브라우저 동시 작업 원칙
 * **브라우저 독립성:** 같은 계정/프로젝트를 여러 브라우저에서 동시 접근 가능. 각 브라우저는 서버 데이터 기반 독립 작동.
 * **클라이언트 상태 격리:** `localStorage`는 브라우저별 격리(도메인 단위 공유). 공유 데이터는 항상 서버 영구저장소 우선.
-* **영구저장소 설계:** 단계별 계산 결과를 `storage/[고객사]/[사용자]/[프로젝트ID]/result_[단계].json` 형태로 물리 저장.
-  * `result_scan.json` — 포인트 클라우드 필터링 결과
-  * `result_surface.json` — 지표면 모델 선택
-  * `result_route.json` — 경로 설계 결과
-  * `result_section.json` — 종횡단 생성 결과
+* **영구저장소 설계:** 계산 결과는 `.agent/db_schema_simple.md`에 정의된 페이지별 단계 폴더에 저장한다.
+  * `B03_FileInput/` — 원본 입력 및 파일 메타데이터
+  * `B04_wf1_Surface/` — 변환 포인트클라우드, 지표면 모델 및 분석 결과
+  * `B05_wf2_Route/` — 경로, 경로점 및 설계 파라미터
+  * `B06_wf3_ProfileCross/` — 종단·횡단 결과 및 인덱스
+* **워크플로우 상태:** 여러 단계가 공유하는 `workflow.json`의 실제 위치는 저장소 경로 유틸에서 단일하게 정의하며, 원자적 쓰기를 적용한다. 단계별 결과 파일의 위치를 프로젝트 루트의 `result_*.json` 이름으로 추정하지 않는다.
 
 ### 5.2 Stale 상태 감지 및 전파
 * **workflow.json 구조:**
@@ -56,7 +68,7 @@
   ```python
   def _patch_workflow_stale(project_id: str, stale_from: str | None) -> None:
       """workflow.json의 stale_from 필드만 원자적 업데이트"""
-      wf_path = storage_path / project_id / "workflow.json"
+      wf_path = get_project_workflow_path(project_id)
       # 기존 상태 유지하며 stale_from만 변경
   ```
 
@@ -88,4 +100,4 @@
     "changed_by": "other_browser"
   }
   ```
-* **마이그레이션 시기:** 사용자 수 증가 또는 실시간성 요구 시 적용
+* **마이그레이션 시기:** 사용자 수 증가 또는 실시간성 요구 시 적용