# 구역 관련 데이터 구조 가이드

## 개요

작업장(구역) 관련 데이터는 여러 테이블에 분산 저장됩니다. 이 문서는 각 테이블의 역할과 관계를 정리합니다.

---

## 테이블 구조

### 1. 설비 정보 (`equipments`)

**용도**: 회사 소유 설비/장비의 마스터 데이터

**등록 경로**: 설비 관리 페이지 (`/pages/equipment/`)

| 주요 컬럼 | 설명 |
|-----------|------|
| `equipment_id` | PK |
| `equipment_code` | 관리번호 (예: TKP-001) |
| `equipment_name` | 설비명 |
| `equipment_type` | 유형 (용접기, 턴테이블 등) |
| `workplace_id` | 원래 배치된 작업장 |
| `status` | 상태 (active, repair_needed, maintenance 등) |
| `map_x_percent`, `map_y_percent` | 지도상 위치 (%) |
| `is_temporarily_moved` | 임시 이동 여부 |
| `current_workplace_id` | 현재 위치 (이동 시) |

**특징**:
- 영구적인 자산 관리 목적
- 설비 관리 페이지에서 CRUD
- 구역 상세 페이지에서는 **조회만** 가능

---

### 2. 구역 현황 (`workplace_zone_items`)

**용도**: 작업장 내 일시적/상시적 현황 기록 (적치물, 작업중 물품, 미신고품 등)

**등록 경로**: 구역 상세 페이지 (`/pages/inspection/zone-detail.html`)

| 주요 컬럼 | 설명 |
|-----------|------|
| `item_id` | PK |
| `workplace_id` | 작업장 ID |
| `item_name` | 명칭 |
| `item_type` | 상태/유형 (working, temp_storage, moved_equipment, unreported) |
| `warning_level` | 주의 수준 (good, caution, needs_management) |
| `project_type` | 프로젝트 여부 (project, non_project, unknown) |
| `project_id` | 연결된 프로젝트 ID |
| `x_percent`, `y_percent` | 지도상 위치 (%) |
| `width_percent`, `height_percent` | 영역 크기 (%) |
| `color` | 표시 색상 |
| `description` | 상세 설명 |
| `created_by` | 등록자 |

**특징**:
- 순회점검 중 또는 수시로 등록
- 사진 첨부 가능 (`zone_item_photos` 테이블)
- 해소되면 삭제 또는 비활성화

---

### 3. 구역 현황 사진 (`zone_item_photos`)

**용도**: 구역 현황에 첨부된 사진

| 주요 컬럼 | 설명 |
|-----------|------|
| `photo_id` | PK |
| `item_id` | 연결된 현황 ID (FK → workplace_zone_items) |
| `photo_url` | 사진 경로 |
| `created_at` | 업로드 시간 |

---

### 4. 구역 현황 이력 (`zone_item_history`)

**용도**: 구역 현황의 등록/수정/삭제 이력 추적

| 주요 컬럼 | 설명 |
|-----------|------|
| `history_id` | PK |
| `item_id` | 현황 ID (FK → workplace_zone_items) |
| `action_type` | 행위 (created, updated, deleted) |
| `changed_fields` | 변경된 필드명 (JSON) |
| `old_values` | 이전 값 (JSON) |
| `new_values` | 새 값 (JSON) |
| `changed_by` | 변경자 ID |
| `changed_at` | 변경 시간 |

**특징**:
- 모든 변경사항 자동 기록
- 누가, 언제, 무엇을 변경했는지 추적 가능
- 삭제된 항목의 마지막 상태도 보존

---

### 5. 순회점검 세션 (`patrol_sessions`)

**용도**: 일일순회점검 수행 기록

**등록 경로**: 일일순회점검 페이지 (`/pages/inspection/daily-patrol.html`)

| 주요 컬럼 | 설명 |
|-----------|------|
| `session_id` | PK |
| `patrol_date` | 점검 날짜 |
| `patrol_time` | 시간대 (morning, afternoon) |
| `category_id` | 점검 공장 |
| `inspector_id` | 점검자 |
| `status` | 상태 (in_progress, completed) |
| `notes` | 특이사항 |

---

### 6. 순회점검 체크기록 (`patrol_check_records`)

**용도**: 각 작업장별 체크리스트 점검 결과

| 주요 컬럼 | 설명 |
|-----------|------|
| `record_id` | PK |
| `session_id` | 세션 ID (FK → patrol_sessions) |
| `workplace_id` | 작업장 ID |
| `checklist_item_id` | 체크항목 ID |
| `is_checked` | 점검 완료 여부 |
| `check_result` | 결과 (pass, fail, na) |
| `notes` | 비고 |

**특징**:
- 점검 세션 완료 시 일괄 저장
- 일시적인 점검 기록 (매일 새로 생성)

---

## 데이터 흐름도

```
┌─────────────────────────────────────────────────────────────┐
│                    구역 상세 페이지                           │
│                 (zone-detail.html)                          │
└─────────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │  equipments  │ │ workplace_   │ │   patrol_    │
    │   (설비)     │ │ zone_items   │ │  sessions    │
    │              │ │  (현황)      │ │  (점검)      │
    └──────────────┘ └──────────────┘ └──────────────┘
          │                 │               │
          │                 ▼               ▼
          │         ┌──────────────┐ ┌──────────────┐
          │         │ zone_item_   │ │ patrol_check │
          │         │   photos     │ │   _records   │
          │         │   (사진)     │ │  (체크기록)  │
          │         └──────────────┘ └──────────────┘
          │
          ▼
    ┌──────────────┐
    │   repair_    │
    │  requests    │
    │  (수리요청)  │
    └──────────────┘
```

---

## 사용 시나리오

### 시나리오 1: 순회점검 중 미신고품 발견

1. 일일순회점검 진행 (`patrol_sessions` 생성)
2. 체크리스트 점검 (`patrol_check_records` 저장)
3. 미신고품 발견 → 구역 현황 등록 (`workplace_zone_items`)
4. 사진 촬영 → 첨부 (`zone_item_photos`)

### 시나리오 2: 설비 상태 확인

1. 구역 상세 페이지 접근
2. 지도에 설비 표시 (`equipments` 조회)
3. 수리 필요 설비 확인 → 수리 요청 (`repair_requests`)

### 시나리오 3: 임시 적치물 관리

1. 작업 중 자재 임시 적치
2. 구역 현황 등록 (item_type: temp_storage)
3. 작업 완료 후 → 현황 삭제

---

## API 엔드포인트

| 기능 | Method | Endpoint |
|------|--------|----------|
| 설비 목록 | GET | `/api/equipments` |
| 구역 현황 목록 | GET | `/api/patrol/workplaces/:id/zone-items` |
| 구역 현황 등록 | POST | `/api/patrol/workplaces/:id/zone-items` |
| 구역 현황 수정 | PUT | `/api/patrol/zone-items/:itemId` |
| 구역 현황 삭제 | DELETE | `/api/patrol/zone-items/:itemId` |
| 현황 사진 업로드 | POST | `/api/patrol/zone-items/photos` |
| 순회점검 세션 | POST | `/api/patrol/sessions` |
| 체크기록 저장 | POST | `/api/patrol/sessions/:id/records` |

---

## 주의사항

1. **설비 vs 구역 현황**
   - 설비: 회사 자산 (영구 관리)
   - 구역 현황: 일시적 상황 기록 (수시 변경)

2. **순회점검 체크기록 vs 구역 현황**
   - 체크기록: 당일 점검 결과 (일회성)
   - 구역 현황: 해소될 때까지 유지 (지속성)

3. **프로젝트 연결**
   - 구역 현황만 프로젝트 연결 가능
   - 설비는 작업장에만 연결

---

*최종 수정: 2026-02-05*