---
status: stable
page_id: B02_ProjRegister
related_pages: ["[[B02_ProjRegister/B02_frontend]]", "[[B02_ProjRegister/B02_db]]", "[[B01_Dashboard/B01_backend]]", "[[B03_FileInput/B03_backend]]", "[[workflow_state]]", "[[storage_paths]]"]
last_updated: 2026-07-12
---

# B02_ProjRegister — Backend

신규 임도 설계 프로젝트 생성. DB 저장 + 저장소 폴더 초기화 + 워크플로우 7단계 시드 + 감사 로그.

> ⚠️ raw structure.md에는 B02가 프론트만 있는 것으로 기재됐으나, 실 코드에 백엔드가 이미 구현됨 (2026-07-12 확인).

## 파일 구조

| 파일 | 위치 | 역할 |
|---|---|---|
| `B02_ProjRegister_Router.py` | `B02_ProjRegister/B02_ProjRegister_Router.py:1-44` | 프로젝트 생성 API (prefix `/api/b02`) |
| `B02_ProjRegister_Schema.py` | `B02_ProjRegister/B02_ProjRegister_Schema.py:1-30` | 요청/응답 Pydantic 모델 2종 |
| `B02_ProjRegister_Repository.py` | `B02_ProjRegister/B02_ProjRegister_Repository.py:1-136` | Raw SQL 저장소 + 저장소 초기화 |

## API 엔드포인트

| 엔드포인트 | 위치 | 역할 |
|---|---|---|
| `POST /api/b02/project` | `B02_ProjRegister/B02_ProjRegister_Router.py:15` | 신규 프로젝트 생성. `require_company`로 회사 연결 확인 |

## 함수

| 함수 | 위치 | 역할 |
|---|---|---|
| `post_project()` | `B02_ProjRegister/B02_ProjRegister_Router.py:15` | 세션 company_id 검증 → create_project 호출, ValueError→400, 기타→500 |
| `create_project()` | `B02_ProjRegister/B02_ProjRegister_Repository.py:44` | 트랜잭션: projects INSERT + 워크플로우 시드 + 감사로그 + 저장소 초기화 |
| `get_project_by_id()` | `B02_ProjRegister/B02_ProjRegister_Repository.py:120` | 프로젝트 단건 조회(deleted_at IS NULL) |
| `_build_project_storage()` | `B02_ProjRegister/B02_ProjRegister_Repository.py:20` | 저장 경로 생성 + 저장소 루트 이탈 방지 검증 |
| `_initialize_project_storage()` | `B02_ProjRegister/B02_ProjRegister_Repository.py:29` | 단계별 폴더 생성 + workflow.json/project_manifest.json 원자적 기록 |

## 요청/응답 스키마 (Pydantic)

| 모델 | 위치 | 필드 |
|---|---|---|
| `CreateProjectRequest` | `B02_ProjRegister/B02_ProjRegister_Schema.py:6` | name(1~255), region(1~100), road_type(main/branch/fire/stream), project_year(2000~2100), estimated_length_m?(≥0), memo?(≤1000) |
| `CreateProjectResponse` | `B02_ProjRegister/B02_ProjRegister_Schema.py:17` | project_id, name, region, road_type, project_year, estimated_length_m, memo, status, storage_path, created_at |

## 생성 로직 (create_project 트랜잭션)

1. `project_id = uuid4()`, 저장 경로 생성·검증(`_build_project_storage`)
2. **트랜잭션 시작**:
   - `projects` INSERT (status `'NEW'`, crs_epsg `5178` 고정)
   - `initialize_project_stages(cursor, project_id)` — 워크플로우 7단계 시드 → [[workflow_state]]
   - `system_audit_logs` INSERT (`PROJECT_CREATE`, resource_type `project`)
   - `_initialize_project_storage()` — 저장소 폴더 + workflow.json + project_manifest.json
   - commit (실패 시 rollback)
3. 생성된 프로젝트 재조회 후 반환

## DB 저장 컬럼 (projects INSERT)

`id, user_id, company_id, name, region, road_type, project_year, estimated_length_m, memo, status('NEW'), crs_epsg(5178), storage_path, created_at, updated_at`
→ 테이블 정의 → [[db_schema/projects]]

## 의존성 (공통 유틸)

- [[common_util]] — `common_util_auth`(`require_company`), `common_util_json`(`atomic_write_json`), `common_util_storage`(`PROJECT_STORAGE_LAYOUT_V2`), `common_util_workflow`(`load_project_workflow`), `common_util_workflow_state`(`initialize_project_stages`)
- 워크플로우 시드 → [[workflow_state]]
- 저장소 경로 규칙 → [[storage_paths]]
- `config_system` — `STORAGE_BASE_DIR`
- DB → [[db_schema/projects]], `system_audit_logs` → [[db_schema/logs_monitoring]]

## 참고

- 프로젝트 생성이 워크플로우 진입점: 생성 직후 프론트는 B03_FileInput으로 이동
- `workflow.json`은 저장소에 기록되나 실제 단계 판정은 `project_workflow_stages`(DB)가 SSOT → [[workflow_state]]