260706_0_회사싱크 후 커밋

.agent/test/03_Backend_Logic_and_Storage.md

@@ -0,0 +1,44 @@
+---
+document_type: backend
+priority: HIGH
+---
+# 백엔드 제어 및 저장소/워크플로우 명세
+
+## 1. 물리 파일 및 저장소 구조 (Workflow Mapping)
+프로젝트 저장소 내부는 워크플로우 단계와 1:1로 매핑됩니다. 백엔드에서 파일을 다룰 때는 DB에 직접 Blob을 저장하지 않고 이 구조를 따라 저장 후 DB에 상대 경로만 기록합니다.
+
+```text
+storage/{company_slug}/{user_slug}/{project_id}/
+├── B03_FileInput/
+│   └── input/ (원본 업로드 파일들: .las, .tif)
+├── B04_wf1_Surface/
+│   ├── processed/ (변환된 데이터: cloud_filtered.las 등)
+│   └── models/ (DEM, TIN 결과물: dem_2m.tif, layer.geojson)
+├── B05_wf2_Route/
+│   └── route/ (최적 경로: route_main.geojson)
+├── B06_wf3_ProfileCross/
+│   ├── longitudinal/ (종단면: longitudinal.json)
+│   └── cross_sections/ (횡단면 배열: cross_0020m.json 등)
+├── B07_wf4_DesignDetail/
+│   └── structures/ (구조물 객체: struct_0020m_001.json)
+├── B08_wf5_Quantity/
+│   └── quantities/ (수량 집계: items.json)
+└── B09_wf6_Estimation/
+    └── v1/, v2/ (버전별 최종 엑셀, PDF, DXF)
+```
+**규칙:** 페이지별 백엔드 모듈은 자기 단계의 폴더만 제어합니다. 하위 단계의 파일을 강제로 지우거나 덮어쓰지 않고 `stale_from` 상태를 통해 제어합니다.
+
+## 2. 워크플로우 상태 동기화 (workflow.json)
+다중 브라우저 동시 작업을 지원하기 위해 서버 측 상태 파일(`workflow.json`)을 원자적(Atomic)으로 관리합니다.
+
+* **Stale (상태 무효화) 발생:** 
+  상위 단계(예: 지표면 분석 B04)가 재계산되면, 그에 의존하는 하위 단계(경로 B05, 횡단 B06 등) 결과는 신뢰할 수 없으므로 `workflow.json`에 `stale_from: "route"` 형태로 마킹됩니다.
+* **상태 업데이트 함수 (예시):**
+  ```python
+  def _patch_workflow_stale(project_id: str, stale_from: str | None) -> None:
+      # workflow.json의 stale_from 필드만 원자적 업데이트
+  ```
+
+## 3. 클라이언트 폴링 (Polling)
+- 프론트는 3초 주기로 `GET /api/projects/{project_id}/workflow` 를 폴링합니다.
+- 서버가 반환하는 `stale_from` 값을 확인하여, 만약 현재 단계와 다르다면 UI에서 사용자에게 "결과가 변경되었습니다. 재계산하시겠습니까?"를 경고합니다.