sam-docs/projects/mes/v2-analysis/site-analysis/README.md

# 현장관리 분석 결과

> 분석 일시: 2024-12-18
> 분석 대상: design/mes기획서_리액트 (디자인팀 기획 사이트)

## 분석 목적

디자인팀에서 제작한 기획 사이트의 현장관리 기능을 분석하여 API 개발에 필요한 스펙을 추출합니다.

---

## UI 스크린샷

### 1. 현장 목록 페이지
![현장 목록](screenshots/01-site-list.png)

**주요 요소:**
- 테이블 컬럼: 번호, 현장코드, 현장명, 거래처, 주소, 등록일
- 검색 기능
- 현장 등록 버튼

---

### 2. 현장 상세 페이지
![현장 상세](screenshots/02-site-detail.png)

**주요 섹션:**

**기본 정보:**
| 필드 | 설명 |
|------|------|
| 현장코드 | 자동 생성 |
| 현장명 | 현장 이름 |
| 진행상태 | 수주확정, 생산중, 출하대기, 설치중, 설치완료 |
| 거래처 | 연결된 거래처 |
| 설치예정일 | 예정 날짜 |
| 진행률 | 0~100% |
| 현장주소 | 주소 |
| 현장연락처 | 연락처 |
| 설치담당자 | 담당자명 |
| 담당자 연락처 | 담당자 연락처 |
| 특이사항 | 메모 |

**수주내역:**
- 연결된 수주 목록 표시
- 수주번호, 품목, 수량, 금액 등

**출고내역:**
- 출고된 품목 목록
- 출고일, 수량, 상태 등

**변경이력:**
- 상태 변경 이력
- 변경일, 변경내용, 변경자

**헤더 버튼:**
- 목록
- 수정
- 삭제

---

### 3. 현장 등록 폼
![현장 등록](screenshots/03-site-create.png)

**입력 섹션:**

**현장 정보:**
| 필드명 | 타입 | 필수 | 비고 |
|--------|------|------|------|
| 현장명 | text | ✅ | |
| 거래처 | select/search | ✅ | 거래처 선택 |
| 현장주소 | text | | 우편번호 검색 |
| 현장연락처 | text | | |
| 진행상태 | select | | 기본: 수주확정 |

**설치 담당자:**
| 필드명 | 타입 | 필수 | 비고 |
|--------|------|------|------|
| 담당자명 | text | | |
| 연락처 | text | | |
| 설치예정일 | date | | |
| 설치완료일 | date | | |
| 특이사항 | textarea | | |

---

## 데이터 스키마

### Site (현장)
```
sites
├── id (PK)
├── tenant_id (FK)
├── site_code (UNIQUE) - 자동 채번
├── name - 현장명
├── customer_id (FK) - 거래처
├── customer_name - 거래처명 (스냅샷)
├── status - 진행상태
├── progress_rate - 진행률 (0-100)
├── address - 현장주소
├── address_detail - 상세주소
├── phone - 현장연락처
├── installer_name - 설치담당자
├── installer_phone - 담당자 연락처
├── scheduled_date - 설치예정일
├── completed_date - 설치완료일
├── note - 특이사항
├── created_at
├── updated_at
└── deleted_at
```

### SiteHistory (현장 변경이력)
```
site_histories
├── id (PK)
├── site_id (FK)
├── changed_field - 변경 필드
├── old_value - 이전 값
├── new_value - 변경 값
├── changed_by - 변경자
├── changed_at - 변경일시
└── note - 비고
```

---

## 상태 흐름

```
수주확정 → 생산중 → 출하대기 → 설치중 → 설치완료
```

| 상태 | 설명 | 진행률 범위 |
|------|------|-------------|
| 수주확정 | 수주 완료, 생산 대기 | 0-10% |
| 생산중 | 제품 생산 진행 | 10-50% |
| 출하대기 | 생산 완료, 출하 대기 | 50-70% |
| 설치중 | 현장 설치 진행 | 70-90% |
| 설치완료 | 설치 완료 | 100% |

---

## API 스펙

### 현장 CRUD

```
GET    /api/sites                    - 현장 목록
GET    /api/sites/{id}               - 현장 상세
POST   /api/sites                    - 현장 등록
PUT    /api/sites/{id}               - 현장 수정
DELETE /api/sites/{id}               - 현장 삭제
DELETE /api/sites                    - 현장 일괄 삭제
```

### 현장 관련 조회

```
GET    /api/sites/{id}/orders        - 현장별 수주 내역
GET    /api/sites/{id}/shipments     - 현장별 출고 내역
GET    /api/sites/{id}/history       - 현장 변경 이력
```

### 현장 상태 변경

```
POST   /api/sites/{id}/status        - 상태 변경
```

**Request Body:**
```json
{
  "status": "생산중",
  "note": "생산 시작"
}
```

### 목록 조회 Query Parameters

| 파라미터 | 타입 | 설명 |
|----------|------|------|
| status | string | 진행상태 필터 |
| customer_id | number | 거래처 필터 |
| search | string | 검색어 (현장코드, 현장명) |
| page | number | 페이지 번호 |
| per_page | number | 페이지당 개수 |

---

## 채번 규칙

```
현장코드: S-{연도2자리}{월2자리}-{순번3자리}
예시: S-2412-001, S-2412-002
```

---

## 연관 관계

### 현장과 수주 연결

```
sites 1:N orders (site_id)
- 하나의 현장에 여러 수주가 연결될 수 있음
- 수주 생성 시 현장 자동 생성 또는 기존 현장 선택
```

### 현장과 거래처 연결

```
customers 1:N sites (customer_id)
- 하나의 거래처가 여러 현장을 가질 수 있음
```

---

## 진행률 자동 계산

```javascript
// 수주 품목 기준 진행률 계산
progress_rate = (완료_품목_수 / 전체_품목_수) * 100

// 또는 상태별 기본 진행률
status_progress = {
  '수주확정': 10,
  '생산중': 30,
  '출하대기': 60,
  '설치중': 80,
  '설치완료': 100
}
```