73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
---
|
|
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]]
|