260715_0

docs/wiki/concepts/api_common.md

@@ -0,0 +1,27 @@
+---
+type: concept
+status: stable
+related_pages: ["[[B01_Dashboard/B01_backend]]", "[[B03_FileInput/B03_backend]]", "[[B04_wf1_Surface/B04_backend]]"]
+last_updated: 2026-07-12
+source: raw/plans/plan_workflow_state_management.md, raw/guidelines/backend.md + 실 코드 확인 2026-07-12
+---
+
+# API 공통 (여러 페이지가 공유하는 엔드포인트)
+
+## 공통 오류 응답 포맷 (전 라우터)
+```json
+{"status": "error", "message": "원인"}
+```
+→ [[schema_common]]
+
+## 워크플로우 상태 조회
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `GET /api/projects/{project_id}/workflow-state` | `B03_FileInput_Router.py:667` | 단일 프로젝트의 `current_stage`와 `stages[]` 조회 |
+| `get_workflow_states_for_projects()` | `B01_Dashboard_Repository.py:83` | [[B01_Dashboard/B01_backend|B01_Dashboard]] 목록용 다중 프로젝트 상태 배치 조회 |
+
+상태 모델과 사용처: [[workflow_state]].
+
+## 폴링 패턴 (legacy workflow.json 설계; 현재 구현은 workflow-state API 사용)
+- 클라이언트가 3초마다 `GET /api/projects/{project_id}/workflow` 호출
+- 과거 설계의 stale 감지 UX 참고용이며, 실제 상태 조회는 [[workflow_state]] API를 사용한다.