README

공사관리 ERP 시스템

공사현장 관리를 위한 통합 ERP 시스템입니다. 공사 진행 관리, 자재 관리, 공가신청/해지, OCR 문서 처리 등을 지원합니다.

기술 스택

구분	기술
백엔드	FastAPI + SQLAlchemy (async)
데이터베이스	PostgreSQL 16
캐시	Redis 7
마이그레이션	Alembic
OCR	Tesseract (별도 서비스)
프론트엔드	Nginx (정적 서빙)
배포	Docker Compose

프로젝트 구조

erp-construction/
├── backend/
│   ├── app/
│   │   ├── api/v1/
│   │   │   ├── __init__.py      # 라우터 패키지
│   │   │   ├── auth.py          # 인증 API
│   │   │   ├── companies.py     # 회사 CRUD
│   │   │   ├── users.py         # 사용자 CRUD
│   │   │   ├── projects.py      # 공사 관리 API
│   │   │   ├── materials.py     # 자재 관리 API
│   │   │   ├── plugins.py       # 플러그인 CRUD + 연결
│   │   │   ├── documents.py     # 공가신청/해지 문서 API
│   │   │   └── ocr.py           # OCR 업로드/리뷰 API
│   │   ├── models/
│   │   │   ├── __init__.py
│   │   │   └── models.py        # SQLAlchemy 모델 (14개 테이블)
│   │   ├── config.py            # 설정 (pydantic-settings)
│   │   ├── database.py          # DB 연결 및 세션
│   │   ├── enums.py             # ENUM 정의
│   │   └── main.py              # FastAPI 앱 진입점
│   ├── migrations/              # Alembic 마이그레이션
│   ├── alembic.ini
│   ├── pyproject.toml
│   ├── requirements.txt
│   └── Dockerfile
├── ocr-service/                 # OCR 처리 서비스
│   ├── main.py
│   ├── requirements.txt
│   └── Dockerfile
├── nginx/
│   └── nginx.conf               # Nginx 설정 (API 프록시)
├── docker-compose.yml
├── .env.example
└── README.md

데이터 모델

테이블	설명
companies	회사
users	사용자 (관리자/공사감독/현장대리/현장팀/공무팀)
viewer_permissions	감시인 권한
project_types	공사유형
project_type_stages	공사유형별 단계
projects	공사
project_teams	공사 팀 배정
project_stage_logs	공사 단계 로그
materials	자재 마스터
material_inputs	자재 입력 (최초/사용/반영)
plugins	플러그인
project_type_plugins	공사유형-플러그인 연결
documents	문서 (공가신청/공가해지)
ocr_uploads	OCR 업로드

API 엔드포인트

라우터	경로	설명
auth	/api/v1/auth	로그인/회원가입
companies	/api/v1/companies	회사 CRUD
users	/api/v1/users	사용자 CRUD/권한
projects	/api/v1/projects	공사/공사유형/단계 관리
materials	/api/v1/materials	자재 관리/요약
plugins	/api/v1/plugins	플러그인 CRUD + 공사유형 연결
documents	/api/v1/documents	공가신청/해지 문서 (플러그인 체크 포함)
ocr	/api/v1/ocr	OCR 업로드/리뷰 (현장대리 확인)

빠른 시작

1. 환경변수 설정

cp .env.example .env
# .env 파일을 실제 환경에 맞게 수정하세요

2. Docker Compose로 실행

# 모든 서비스 실행
docker compose up -d

# 백엔드 로그 확인
docker compose logs -f backend

# 서비스 중지
docker compose down

3. 로컬 개발 (Docker 없이)

필수 조건: Python 3.11+, PostgreSQL 16, Redis 7

# 백엔드 디렉토리로 이동
cd backend

# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 의존성 설치
pip install -e .

# 데이터베이스 마이그레이션
alembic upgrade head

# 서버 실행
uvicorn app.main:app --reload --port 8000

4. API 문서 확인

서버 실행 후 브라우저에서 접속:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

마이그레이션

cd backend

# 새 마이그레이션 생성
alembic revision --autogenerate -m "설명"

# 마이그레이션 적용
alembic upgrade head

# 마이그레이션 롤백
alembic downgrade -1

# 현재 리비전 확인
alembic current

주요 기능

플러그인 시스템

• 회사별 플러그인 생성/관리
• 공사유형에 플러그인 연결 (활성화/비활성화)
• 공가신청/해지 문서 작성 시 플러그인 활성화 검증

문서 관리 (공가신청/해지)

• 문서 상태 전이: 작성중 → 신청 → 접수 → 완료
• 플러그인 활성화 체크를 통한 권한 제어
• 상태별 검증 로직 포함

OCR 업로드/리뷰

• 현장팀의 문서/사진 업로드
• 파일 형식/크기 검증 (JPG, PNG, PDF 등, 최대 20MB)
• 현장대리 확인(리뷰) 프로세스: 대기 → 확인/수정

자재 관리

• 자재 마스터 관리 (사급/지입)
• 자재 입력: 최초/사용/반영 유형별 관리
• 자재 요약: 불용/재고 자동 계산

환경변수

변수	기본값	설명
POSTGRES_USER	erp	PostgreSQL 사용자
POSTGRES_PASSWORD	erp123	PostgreSQL 비밀번호
POSTGRES_DB	erp_construction	데이터베이스명
POSTGRES_PORT	5432	PostgreSQL 포트
REDIS_PORT	6379	Redis 포트
BACKEND_PORT	8000	백엔드 포트
FRONTEND_PORT	80	프론트엔드 포트
SECRET_KEY	change-this-in-production	JWT 시크릿 키
DATABASE_URL	postgresql+asyncpg://erp:erp123@localhost:5432/erp_construction	DB 연결 URL
UPLOAD_DIR	/tmp/erp-uploads	파일 업로드 경로

라이선스

사내 프로젝트