TK-FB-Project/docs/zone-data-guide.md

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

개요

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

---

테이블 구조

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