TK-FB-Project/개발 log/2026-01-28-equipment-management-system.md

# 2026-01-28: 설비 관리 시스템 구축

## 📋 작업 개요
작업장별 설비 정보를 등록하고 관리할 수 있는 시스템을 구축했습니다.

## ✅ 완료된 작업

### 1. 데이터베이스 구조
**파일:** `api.hyungi.net/db/migrations/20260128000000_add_layout_image_to_workplaces.js`
- workplaces 테이블에 `layout_image` 컬럼 추가
- 작업장별 레이아웃 이미지 경로 저장

**파일:** `api.hyungi.net/db/migrations/20260128010000_create_equipments_table.js`
- equipments 테이블 생성
- 필드:
  - 기본 정보: equipment_code, equipment_name, equipment_type
  - 상세 정보: manufacturer, model_name, serial_number, installation_date
  - 작업장 연결: workplace_id (외래키)
  - 지도 위치: map_x_percent, map_y_percent, map_width_percent, map_height_percent
  - 상태 관리: status (active, maintenance, inactive)

### 2. 백엔드 API

**파일:** `api.hyungi.net/models/equipmentModel.js`
- 설비 CRUD 작업
- 필터링 기능 (작업장, 유형, 상태, 검색)
- 지도 위치 업데이트
- 설비 코드 중복 확인
- 사용 중인 설비 유형 목록 조회

**파일:** `api.hyungi.net/controllers/equipmentController.js`
- 설비 생성/조회/수정/삭제 컨트롤러
- 유효성 검사 및 에러 처리
- 작업장별/유형별 필터링

**파일:** `api.hyungi.net/routes/equipmentRoutes.js`
- `/api/equipments` 엔드포인트
- REST API 구현 (GET, POST, PUT, PATCH, DELETE)

**파일:** `api.hyungi.net/config/routes.js`
- 설비 라우트 등록 (line 44, 142)

### 3. 프론트엔드

**파일:** `web-ui/pages/admin/equipments.html`
- 설비 관리 페이지 UI
- 필터링 섹션 (작업장, 유형, 상태, 검색)
- 설비 목록 테이블
- 설비 추가/수정 모달

**파일:** `web-ui/js/equipment-management.js`
- 설비 데이터 로드 및 렌더링
- 필터링 및 검색 기능
- CRUD 작업 처리
- 작업장/유형 드롭다운 자동 채우기

### 4. 작업장 관리 개선

**파일:** `web-ui/pages/admin/workplaces.html`
- 작업장 지도 모달 추가 (line 254-329)
- 설비 위치 정의 기능 (캔버스 기반 드래그)

**파일:** `web-ui/js/workplace-management.js`
- 작업장 레이아웃 이미지 업로드 (line 828-878)
- 설비 영역 정의 및 저장 (line 943-1126)
- 백분율 기반 좌표 시스템

### 5. 권한 시스템 연동
- pages 테이블에 설비 관리 페이지 등록
- page_key: `equipments`
- 경로: `/pages/admin/equipments.html`
- Admin 전용 페이지

## 🐛 버그 수정

### 1. 이미지 보존 로직 개선
**파일:** `api.hyungi.net/controllers/workplaceController.js`
- **위치:** line 130-136 (updateCategory), line 310-316 (updateWorkplace)
- **문제:** `null` 값으로 인한 이미지 삭제
- **해결:** `undefined`와 `null` 모두 체크하도록 개선

```javascript
// 변경 전
layout_image: categoryData.layout_image !== undefined
  ? categoryData.layout_image
  : existingCategory.layout_image

// 변경 후
layout_image: (categoryData.layout_image !== undefined && categoryData.layout_image !== null)
  ? categoryData.layout_image
  : existingCategory.layout_image
```

### 2. 작업장 레이아웃 이미지 업로드 경로 수정
**파일:** `api.hyungi.net/routes/workplaceRoutes.js`
- **위치:** line 11
- **문제:** Docker 볼륨 마운트와 업로드 경로 불일치
- **해결:** `../public/uploads` → `../uploads`로 변경

## 📁 파일 구조

```
api.hyungi.net/
├── controllers/
│   ├── equipmentController.js       (신규)
│   └── workplaceController.js       (수정)
├── models/
│   └── equipmentModel.js            (신규)
├── routes/
│   ├── equipmentRoutes.js           (신규)
│   └── workplaceRoutes.js           (수정)
├── config/
│   └── routes.js                    (수정)
└── db/migrations/
    ├── 20260128000000_add_layout_image_to_workplaces.js  (신규)
    └── 20260128010000_create_equipments_table.js         (신규)

web-ui/
├── pages/admin/
│   ├── equipments.html              (신규)
│   └── workplaces.html              (수정)
└── js/
    ├── equipment-management.js      (신규)
    └── workplace-management.js      (수정)
```

## 🎯 주요 기능

### 설비 관리
- ✅ 설비 등록/수정/삭제
- ✅ 작업장별 연결
- ✅ 설비 유형별 분류
- ✅ 상태 관리 (활성/정비중/비활성)
- ✅ 상세 정보 관리 (제조사, 모델명, 시리얼 번호, 설치일)
- ✅ 필터링 및 검색

### 작업장 지도 연동
- ✅ 작업장 레이아웃 이미지 업로드
- ✅ 설비 위치 캔버스 드래그로 정의
- ✅ 백분율 기반 좌표 (반응형 지원)

## 🔗 API 엔드포인트

```
POST   /api/equipments              - 설비 생성
GET    /api/equipments              - 설비 목록 조회 (필터링 가능)
GET    /api/equipments/active/list  - 활성 설비 조회
GET    /api/equipments/types        - 설비 유형 목록
GET    /api/equipments/:id          - 설비 상세 조회
PUT    /api/equipments/:id          - 설비 수정
PATCH  /api/equipments/:id/map-position - 지도 위치 업데이트
DELETE /api/equipments/:id          - 설비 삭제
```

## 🚀 사용 방법

1. **설비 관리 페이지 접속**
   - URL: http://localhost:20000/pages/admin/equipments.html

2. **설비 추가**
   - "설비 추가" 버튼 클릭
   - 필수 정보 입력 (설비 코드, 설비명)
   - 선택 정보 입력 (유형, 작업장, 제조사 등)
   - 저장

3. **작업장 지도에서 설비 위치 정의**
   - 작업장 관리 페이지 접속
   - 작업장 카드에서 🗺️ 버튼 클릭
   - Step 1: 레이아웃 이미지 업로드
   - Step 2: 설비 영역 드래그로 정의

4. **필터링 및 검색**
   - 작업장별 필터
   - 유형별 필터
   - 상태별 필터
   - 설비명/코드 검색

## 📊 데이터베이스 변경사항

### workplaces 테이블
```sql
ALTER TABLE workplaces
ADD COLUMN layout_image VARCHAR(500) NULL COMMENT '작업장 레이아웃 이미지 경로';
```

### equipments 테이블 (신규)
```sql
CREATE TABLE equipments (
  equipment_id INT AUTO_INCREMENT PRIMARY KEY,
  equipment_code VARCHAR(50) UNIQUE NOT NULL,
  equipment_name VARCHAR(100) NOT NULL,
  equipment_type VARCHAR(50),
  model_name VARCHAR(100),
  manufacturer VARCHAR(100),
  installation_date DATE,
  serial_number VARCHAR(100),
  specifications TEXT,
  status ENUM('active', 'maintenance', 'inactive') DEFAULT 'active',
  notes TEXT,
  workplace_id INT,
  map_x_percent DECIMAL(5,2),
  map_y_percent DECIMAL(5,2),
  map_width_percent DECIMAL(5,2),
  map_height_percent DECIMAL(5,2),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  FOREIGN KEY (workplace_id) REFERENCES workplaces(workplace_id) ON DELETE SET NULL,
  INDEX idx_workplace (workplace_id),
  INDEX idx_type (equipment_type),
  INDEX idx_status (status)
);
```

### pages 테이블
```sql
INSERT INTO pages (page_key, page_name, page_path, category, description, is_admin_only, display_order)
VALUES ('equipments', '설비 관리', '/pages/admin/equipments.html', '관리',
        '작업장별 설비 정보를 등록하고 관리합니다', 1, 35);
```

## 💡 기술적 고려사항

### 1. 백분율 기반 좌표 시스템
- 반응형 지원을 위해 픽셀 대신 백분율 사용
- 다양한 화면 크기에서 일관된 표시

### 2. Docker 볼륨 마운트
- `/uploads` 폴더로 통일
- 컨테이너 재시작 시에도 파일 유지

### 3. 이미지 보존 로직
- null과 undefined 모두 처리
- 의도하지 않은 이미지 삭제 방지

## 🔄 향후 개선사항

- [ ] 설비 이력 관리 (정비 내역, 고장 이력)
- [ ] 설비 성능 지표 추적
- [ ] 설비별 작업 배정 기능
- [ ] 설비 가동률 통계
- [ ] QR 코드 스캔 기능
- [ ] 설비 이미지 업로드

## 📝 참고사항

- API 컨테이너는 자동으로 재시작되어 변경사항 반영
- 기존 작업장 레이아웃 이미지는 수동으로 이동됨
- 권한은 Admin 전용으로 설정됨