# B02_ProjRegister 프로젝트 생성 기능 코드 작업 완료 보고서

**작성일:** 2026-07-09  
**대상 계획서:** `.agent/plan_b02_project_creation.md`  
**작업 범위:** B02 프로젝트 등록 프론트엔드, 백엔드 API, DB 저장, 프로젝트 저장소 초기화

---

## 1. 작업 완료 요약

B02 프로젝트 등록 화면의 TODO 제출 흐름을 실제 API 연동으로 교체하고, FastAPI 백엔드에 `POST /api/b02/project` 엔드포인트를 추가했습니다.

프로젝트 생성 시 다음 작업이 수행됩니다.

1. 프론트엔드 1차 검증
   - 프로젝트명 필수값 검증
   - 사업 지역 필수값 검증
   - 사업 연도 범위 검증
   - 예상 연장 숫자/음수 검증
2. 백엔드 Pydantic 2차 검증
   - `name`, `region`, `road_type`, `project_year`, `estimated_length_m`, `memo`
3. DB 저장
   - `projects` 테이블 신규 레코드 생성
   - 초기 상태 `NEW`
   - 기본 좌표계 `crs_epsg = 5178`
   - `storage_path = storage/{company_id}/{user_id}/{project_id}`
4. 저장소 초기화
   - `storage/{company_id}/{user_id}/{project_id}/` 생성
   - B03~B09 단계별 하위 폴더 생성
   - `workflow.json` 초기화
   - `project_manifest.json` 생성
5. 프론트 상태 반영
   - 응답받은 `project_id`를 `CURRENT_PROJECT_ID_KEY`에 저장
   - 성공 토스트 표시
   - B03_FileInput 페이지로 이동

---

## 2. 생성 및 수정 파일

### 신규 파일

- `B02_ProjRegister/B02_ProjRegister_Schema.py`
  - 프로젝트 생성 요청/응답 Pydantic 스키마 추가

- `B02_ProjRegister/B02_ProjRegister_Repository.py`
  - 프로젝트 UUID 생성
  - `projects` Raw SQL INSERT
  - 단계별 저장소 폴더 생성
  - `workflow.json`, `project_manifest.json` 초기화

- `B02_ProjRegister/B02_ProjRegister_Router.py`
  - `POST /api/b02/project` 엔드포인트 추가
  - 세션/회사 연결 검증
  - 저장소/DB 예외 처리

### 수정 파일

- `B02_ProjRegister/B02_ProjRegister_UI_Page.ts`
  - TODO 제출 로직 제거
  - `fetch("/api/b02/project")` 연동
  - `credentials: "include"` 적용
  - 로딩 오버레이 및 에러 토스트 처리
  - `localStorage`에 현재 프로젝트 ID 저장

- `main.py`
  - B02 라우터 import 추가
  - `app.include_router(b02_proj_register_router)` 등록

---

## 3. 저장소 생성 구조

프로젝트 생성 시 실제 파일시스템에 다음 구조를 생성합니다.

```text
storage/{company_id}/{user_id}/{project_id}/
├── B03_FileInput/input/
├── B04_wf1_Surface/processed/
├── B05_wf2_Route/route/
├── B06_wf3_ProfileCross/profiles/
├── B07_wf4_DesignDetail/structures/
├── B08_wf5_Quantity/quantities/
├── B09_wf6_Estimation/v1/
├── workflow.json
└── project_manifest.json
```

DB에는 기존 B03 업로드 로직이 해석 가능한 상대 경로 형식인 `storage/{company_id}/{user_id}/{project_id}`를 저장합니다.

---

## 4. 검증 결과

### 통과

- `venv\Scripts\ruff.exe format B02_ProjRegister main.py`
- `venv\Scripts\ruff.exe check --fix B02_ProjRegister main.py`
- `venv\Scripts\ruff.exe check B02_ProjRegister main.py`
- `venv\Scripts\python.exe -m compileall B02_ProjRegister main.py`
- `npx prettier --write B02_ProjRegister/B02_ProjRegister_UI_Page.ts`
- `npx prettier --check B02_ProjRegister/B02_ProjRegister_UI_Page.ts`

### 미통과

- `npx tsc --noEmit`

실패 원인은 B02 작업 범위 밖의 기존 오류입니다.

- `B01_Dashboard/B01_Dashboard_UI_Helper.ts`: 미사용 매개변수
- `B01_Dashboard/B01_Dashboard_UI_Modals.ts`: 미사용 import
- `B01_Dashboard/B01_Dashboard_UI_Page.ts`: `RoutePath` 타입 누락
- `ui_template/ui_template_locale.ts`: 중복 locale key

---

## 5. 참고 및 주의사항

- `.agent/db_schema_simple.md` 파일은 현재 저장소에서 찾을 수 없어, 실제 `db_management/001_create_schema.sql`, 기존 B03 저장 경로 유틸, `config_system.py` 기준으로 구현했습니다.
- `npm install`은 타입 검사 확인 중 1회 실행했으나, 추적 중인 `node_modules`에 불필요한 변경이 발생하여 `node_modules`만 복원했습니다.
- 실제 DB INSERT와 세션 기반 API 호출은 MariaDB/로그인 세션이 필요한 통합 환경에서 추가 확인이 필요합니다.