Aislo/docs/wiki/pages/B02_ProjRegister/B02_backend.md

status, page_id, related_pages, last_updated

status	page_id	related_pages	last_updated
stable	B02_ProjRegister	B02_ProjRegister/B02_frontend B02_ProjRegister/B02_db B01_Dashboard/B01_backend B03_FileInput/B03_backend workflow_state storage_paths	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(1255), region(1100), 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