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 모두 체크하도록 개선

// 변경 전
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 테이블

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

equipments 테이블 (신규)

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 테이블

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 전용으로 설정됨