---
type: concept
status: stable
related_pages: ["[[B01_Dashboard/B01_frontend]]", "[[B02_ProjRegister/B02_backend]]", "[[B03_FileInput/B03_backend]]", "[[B04_PreProcess/B04_backend]]", "[[B05_Profile/B05_backend]]", "[[B06_Section/B06_backend]]", "[[B07_Quantity/B07_backend]]", "[[B08_DesignDetail/B08_backend]]", "[[B09_Estimation/B09_frontend]]", "[[architecture/implementation_status]]", "[[architecture/shared_resources]]"]
last_updated: 2026-08-16
source: ["docs/raw/verification/2026-07-19_verify_webcad_poc.md", "docs/raw/verification/2026-07-19_verify_B06_사이드바_버튼_폭_및_확정_후_B07_이동.md", "docs/raw/verification/2026-07-21_verify_B06_default_design_B07_gating.md", "docs/raw/verification/2026-08-04_verify_b05_b06_profile_ui_chain.md", "docs/raw/verification/2026-08-08_verify_R1_R2_features.md", "docs/raw/verification/2026-07-17_verify_workflow_stepbar.md"]
---

# Workflow 상태 관리

> DB 상태 유틸은 구현돼 있다. 그러나 B07은 임시 완료 우회, B09는 셸이므로 일곱 단계 전체가 업무 기능으로 완료된 것은 아니다.

## SSOT: `project_workflow_stages` 테이블 (실 DB 확인)
| 컬럼 | 타입 |
| --- | --- |
| id | INT PK |
| project_id | CHAR(36), FK |
| stage_no | TINYINT (0~6) |
| stage_key | VARCHAR(30) — FILE_INPUT/PREPROCESS/PROFILE/SECTION/QUANTITY/DESIGN_DETAIL/ESTIMATION |
| state | ENUM('NOT_STARTED','IN_PROGRESS','COMPLETE','FAILED','STALE') |
| progress_percent | TINYINT |
| params | LONGTEXT(JSON) — 재실행 시 폼 프리필용 |
| message, started_at, completed_at, updated_at | 진행/이력 |

생성 SQL: `db_management/006_workflow_state.sql`, 백필: `db_management/migrate_workflow_state.py`

## R1 워크플로우 단계 재편 (2026-08-08 반영)
- **B04_PreProcess** (stage 1: 지표면 분석)
- **B05_Profile** (stage 2: 경로 및 종단)
- **B06_Section** (stage 3: 횡단 및 유토곡선)
- **B07_Quantity** (stage 4: 수량 셸 신설, `confirm_quantity`로 stage 4 COMPLETE 전이)
- **B08_DesignDetail** (stage 5: CAD 도면/OpenWebCAD 이동, 정적 마운트 `/b08-cad`)
- **B09_Estimation** (stage 6: 설계도서 및 견적)

## 백그라운드 자동 계산 체인 및 사용자 설정 이월
*   **업로드 후 자동 계산 체인 (B04 ➡️ B05 ➡️ B06)**: WF1(B04 지표면) 확정 성공 시 서버 백그라운드 태스크로 B05 기본 경로 계산·저장 ➡️ B06 일괄 횡단 설계를 연속 실행하여 대시보드/B05 진입 시 로딩 상태를 즉시 제공합니다.
*   **B05/B06 자유 이동 및 동시 확정**: B06 전체 확정 시 stage 2와 3을 함께 COMPLETE 처리하고 B07 임시 셸로 이동한다.
*   **B04 재확정 사용자 설정 이월 (`B03_FileInput_Service_Chain.py`)**: `run_redesign_chain`을 통해 B04 지표면이 재확정되어도 B05 사용자 제어점/경사 파라미터 및 B06 측점별 단면 설계를 이월하여 새 경로에 매칭 재계산 후 확정 전이시킵니다.

## 공통 유틸 `common_util/common_util_workflow_state.py`
| 함수 | 역할 |
|---|---|
| `initialize_project_stages(cursor, project_id)` | 프로젝트 생성 시 7행 NOT_STARTED 시드 |
| `start_stage(cursor, project_id, stage_no, params)` | IN_PROGRESS 전이 + N+1~6의 COMPLETE를 STALE로 전파 + `projects.status` 캐시 갱신 |
| `complete_stage(cursor, project_id, stage_no)` | COMPLETE 전이 (stage 6 완료 시 `projects.status='DONE'`) |
| `fail_stage(cursor, project_id, stage_no, message)` | FAILED 전이 |
| `update_stage_progress(cursor, project_id, stage_no, progress)` | 진행률만 갱신 |
| `get_workflow_state(cursor, project_id)` | 단건 조회, `current_stage` 계산 포함 |
| `reset_stages_after_input_change(cursor, project_id)` | B03 입력 변경 시 stage 1~6을 NOT_STARTED로 초기화 |

## 무효화의 실제 범위

| 처리 | 범위 |
|---|---|
| `start_stage()` | 뒤쪽 단계 중 `COMPLETE`만 `STALE`로 변경 |
| 공통 상태 유틸 | 단계 산출 파일·캐시를 삭제하지 않음 |
| 산출물 정리 | B03/B04/B05/B08 등 단계별 로직에 의존 |
| `workflow.json` | 초기 파일과 일부 호환 용도; DB workflow의 SSOT가 아님 |

## 조회 API
`GET /api/projects/{project_id}/workflow-state`

## 프론트엔드 게이팅 및 스텝바 연동
*   **스텝바 일원화**: `createStepBar` 컴포넌트(`ui_template_workflow_layout.ts`)를 승격하여 B01 및 B03~B09에서 통합 관리.
*   **게이팅 규칙**: B06 확정 후 B07로 이동한다. B07은 산출물 검사 없이 stage 4를 완료 처리하는 임시 우회다.
*   **네비게이션**: `b_workflow_nav.ts` 모듈을 통해 `fetchWorkflowState`, `goToWorkflowStage` 공통 헬퍼 이용.