sam-docs/features/equipment

설비관리 (Equipment Management)

작성일: 2026-02-27 상태: MNG R&D 완료 / API Phase 1 완료 / React 미구현 최종 갱신: 2026-03-12

---

1. 개요

1.1 목적

생산 설비의 등록, 점검, 수리이력을 체계적으로 관리한다. MNG 관리자 패널에서 Blade/HTMX 기반으로 R&D가 완료되었으며, API 백엔드 구현이 완료되어 React 프론트엔드 연동을 진행할 수 있다.

1.2 핵심 기능

기능	설명	MNG	API
설비 대시보드	현황 카드(총/가동/유휴/폐기), 유형별 통계	✅	✅
설비 대장 (CRUD)	등록/수정/삭제/복원, SoftDeletes	✅	✅
설비 점검	6주기(일일~반년), 그리드 셀 토글, 종합판정	✅	✅
점검 템플릿	설비별 점검항목 정의, 주기간 복사	✅	✅
수리이력	사내/외주, 비용, 시간, 업체 관리	✅	✅
설비 사진	파일 업로드/삭제	✅	✅
엑셀 Import	미리보기 + 일괄등록, 이미지 포함	✅	—
모바일 점검	QR 스캔 → 모바일 점검 화면	✅	—
설비-공정 매핑	N:N 관계, 주 설비 여부	✅	✅

---

2. DB 테이블

마이그레이션: api/database/migrations/ (MNG에서 생성 금지)

2.1 테이블 목록

테이블	설명	마이그레이션
equipments	설비 마스터	2026_02_25_100000
equipment_inspection_templates	점검항목 템플릿	2026_02_25_100100
equipment_inspections	점검 헤더 (설비+주기+기간)	2026_02_25_100200
equipment_inspection_details	점검 상세 (셀 단위 결과)	2026_02_25_100300
equipment_repairs	수리이력	2026_02_25_100400
equipment_process	설비-공정 매핑 (N:N pivot)	2026_02_25_100500

추가 마이그레이션:

마이그레이션	설명
2026_02_28_100000	sub_manager_id 컬럼 추가
2026_02_28_100100	templates에 inspection_cycle 추가 + 유니크 변경
2026_02_28_100200	inspections에 inspection_cycle 추가 + 유니크 변경
2026_03_12_100000	equipments, equipment_repairs에 options JSON 추가
2026_03_12_100001	기본 DB에 테이블 존재 보장 (hasTable 체크)

DB 연결 참고: 기존 MNG 마이그레이션이 codebridge DB에 테이블을 생성했으나, API에서는 기본 DB(sam/sam_prod)에 테이블이 필요하다. 2026_03_12_100001 마이그레이션이 기본 DB에 테이블이 없으면 최신 스키마로 생성한다.

2.2 ERD 개요

equipments (설비 마스터)
├── 1:N → equipment_inspection_templates (점검항목 정의)
├── 1:N → equipment_inspections (점검 헤더)
│         └── 1:N → equipment_inspection_details (점검 상세)
├── 1:N → equipment_repairs (수리이력)
├── N:N → processes (via equipment_process)
└── 1:N → files (사진, document_type='equipment')

2.3 주요 컬럼

equipments

컬럼	타입	설명
tenant_id	bigint	테넌트 ID
equipment_code	varchar(20)	설비코드 (UNIQUE per tenant)
name	varchar(100)	설비명
equipment_type	varchar(50)	유형: 포밍기/미싱기/샤링기/V컷팅기/절곡기/프레스/드릴/기타
production_line	varchar(50)	라인: 스라트/스크린/절곡/기타
status	varchar(20)	active/idle/disposed
manager_id	FK → users	정 담당자
sub_manager_id	FK → users	부 담당자
purchase_date	date	구입일
install_date	date	설치일
purchase_price	decimal(15,2)	구입가격
useful_life	int	내용연수
options	json	확장 속성 JSON
sort_order	int	정렬순서

equipment_inspection_templates

컬럼	타입	설명
equipment_id	FK → equipments	설비
inspection_cycle	varchar	점검주기 (daily/weekly/monthly/bimonthly/quarterly/semiannual)
item_no	int	항목번호
check_point	varchar(50)	점검개소
check_item	varchar(100)	점검항목
check_timing	varchar(20)	시기: operating/stopped
check_method	text	점검방법 및 기준

equipment_inspections

컬럼	타입	설명
equipment_id	FK → equipments	설비
inspection_cycle	varchar	점검주기
year_month	varchar(7)	기간 (daily: 2026-03, 그 외: 2026)
overall_judgment	varchar(10)	종합판정: OK/NG
inspector_id	FK → users	점검자
repair_note	text	수리내역
issue_note	text	이상내용

equipment_inspection_details

컬럼	타입	설명
inspection_id	FK → inspections	점검 헤더
template_item_id	FK → templates	점검항목
check_date	date	점검일
result	varchar(10)	good(○)/bad(X)/repaired(△)

equipment_repairs

컬럼	타입	설명
equipment_id	FK → equipments	설비
repair_date	date	수리일
repair_type	varchar(20)	internal(사내)/external(외주)
repair_hours	decimal(5,1)	수리시간
cost	decimal(15,2)	수리비용
vendor	varchar(100)	외주업체
repaired_by	FK → users	수리자
options	json	확장 속성 JSON

---

3. API 구현 현황 (Phase 1 완료)

3.1 모델 (api/app/Models/Equipment/)

모델	Traits	특이사항
Equipment	Auditable, BelongsToTenant, ModelTrait, SoftDeletes	options cast, getOption()/setOption()
EquipmentInspection	Auditable, BelongsToTenant, ModelTrait	—
EquipmentInspectionDetail	ModelTrait	getNextResult(), getResultSymbol() static
EquipmentInspectionTemplate	Auditable, BelongsToTenant, ModelTrait	—
EquipmentRepair	Auditable, BelongsToTenant, ModelTrait, SoftDeletes	options cast, getOption()/setOption()
EquipmentProcess	—	pivot 모델

3.2 Enum (api/app/Enums/InspectionCycle.php)

6개 점검주기를 관리하는 헬퍼 클래스:

주기	코드	period 형식	그리드 열
일일	daily	2026-03 (년-월)	1~31일
주간	weekly	2026 (년)	1~52주
월간	monthly	2026 (년)	1~12월
2개월	bimonthly	2026 (년)	1~6
분기	quarterly	2026 (년)	1~4분기
반년	semiannual	2026 (년)	상/하반기

주요 메서드: columnLabels(), resolveCheckDate(), resolvePeriod(), isNonWorkingDay(), getHolidayDates(int $tenantId)

MNG→API 변환: getHolidayDates()가 session('selected_tenant_id') 대신 명시적 $tenantId 매개변수를 받는다.

3.3 서비스 (api/app/Services/Equipment/)

모든 서비스는 extends Service (base class)를 사용하며, 쓰기 작업은 DB::transaction()으로 감싼다.

서비스	핵심 메서드
EquipmentService	index(), show(), store(), update(), destroy(), restore(), toggleActive(), stats(), options()
EquipmentInspectionService	getInspections(), toggleDetail(), setResult(), updateNotes(), resetInspection(), saveTemplate(), updateTemplate(), deleteTemplate(), copyTemplates(), getActiveCycles()
EquipmentRepairService	index(), store(), update(), destroy()
EquipmentPhotoService	index(), store(), destroy()

3.4 컨트롤러 (api/app/Http/Controllers/V1/Equipment/)

컨트롤러	DI	메서드
EquipmentController	EquipmentService	index, show, store, update, destroy, restore, toggleActive, stats, options
EquipmentInspectionController	EquipmentInspectionService	index, toggleDetail, setResult, updateNotes, resetInspection, templates, storeTemplate, updateTemplate, deleteTemplate, copyTemplates
EquipmentRepairController	EquipmentRepairService	index, store, update, destroy
EquipmentPhotoController	EquipmentPhotoService	index, store, destroy

3.5 FormRequest (api/app/Http/Requests/V1/Equipment/)

클래스	용도
StoreEquipmentRequest	설비 등록 (코드 unique per tenant)
UpdateEquipmentRequest	설비 수정 (sometimes 규칙)
StoreEquipmentRepairRequest	수리이력 등록/수정
StoreInspectionTemplateRequest	점검항목 등록 (cycle enum 검증)
ToggleInspectionDetailRequest	점검 셀 토글
UpdateInspectionNotesRequest	점검 메모/판정 수정

3.6 API 라우트 (api/routes/api/v1/equipment.php)

26개 엔드포인트, prefix: /v1/equipment

설비 CRUD (9):
  GET    /v1/equipment                    → index (목록+검색+필터)
  GET    /v1/equipment/options            → options (드롭다운 데이터)
  GET    /v1/equipment/stats              → stats (대시보드 통계)
  POST   /v1/equipment                    → store
  GET    /v1/equipment/{id}               → show
  PUT    /v1/equipment/{id}               → update
  DELETE /v1/equipment/{id}               → destroy (soft delete)
  POST   /v1/equipment/{id}/restore       → restore
  PATCH  /v1/equipment/{id}/toggle        → toggleActive

점검 템플릿 (5):
  GET    /v1/equipment/{id}/templates          → templates (활성 주기 목록)
  POST   /v1/equipment/{id}/templates          → storeTemplate
  PUT    /v1/equipment/templates/{templateId}  → updateTemplate
  DELETE /v1/equipment/templates/{templateId}  → deleteTemplate
  POST   /v1/equipment/{id}/templates/copy     → copyTemplates

점검 (5):
  GET    /v1/equipment/inspections             → index (그리드 데이터)
  PATCH  /v1/equipment/inspections/toggle      → toggleDetail (셀 토글)
  PATCH  /v1/equipment/inspections/set-result  → setResult (결과 직접 설정)
  PATCH  /v1/equipment/inspections/notes       → updateNotes (메모/판정)
  DELETE /v1/equipment/inspections/reset       → resetInspection (초기화)

수리이력 (4):
  GET    /v1/equipment/repairs            → index
  POST   /v1/equipment/repairs            → store
  PUT    /v1/equipment/repairs/{id}       → update
  DELETE /v1/equipment/repairs/{id}       → destroy

사진 (3):
  GET    /v1/equipment/{id}/photos             → index
  POST   /v1/equipment/{id}/photos             → store
  DELETE /v1/equipment/{id}/photos/{fileId}    → destroy

3.7 i18n 메시지

성공 메시지 (lang/ko/message.php → equipment.*):

키	메시지
created	설비가 등록되었습니다.
updated	설비 정보가 수정되었습니다.
deleted	설비가 삭제되었습니다.
restored	설비가 복원되었습니다.
inspection_saved	점검 정보가 저장되었습니다.
inspection_reset	점검 데이터가 초기화되었습니다.
template_created	점검항목이 추가되었습니다.
template_copied	점검항목이 복사되었습니다.
repair_created	수리이력이 등록되었습니다.
photo_uploaded	사진이 업로드되었습니다.

에러 메시지 (lang/ko/error.php → equipment.*):

키	메시지
not_found	설비 정보를 찾을 수 없습니다.
template_not_found	점검항목을 찾을 수 없습니다.
inspection_not_found	점검 데이터를 찾을 수 없습니다.
repair_not_found	수리이력을 찾을 수 없습니다.
photo_not_found	사진을 찾을 수 없습니다.
invalid_cycle	유효하지 않은 점검주기입니다.
no_source_templates	복사할 점검항목이 없습니다.

3.8 MNG→API 변환 규칙 적용

MNG 패턴	API 변환
$connection = 'codebridge'	제거 (기본 connection 사용)
session('selected_tenant_id')	$this->tenantId()
auth()->id()	$this->apiUserId()
DB::connection('codebridge')	DB:: (기본 connection)
MNG 직접 validate	FormRequest 분리
직접 문자열 에러 메시지	__('error.equipment.*') i18n
—	Auditable trait 추가
—	DB::transaction() 쓰기 래핑

---

4. MNG 구현 현황

4.1 서비스 (mng/app/Services/)

서비스	핵심 메서드
EquipmentService	getEquipments(), createEquipment(), updateEquipment(), deleteEquipment(), restoreEquipment(), getDashboardStats(), getTypeStats()
EquipmentInspectionService	getInspections(), toggleDetail(), setResult(), updateInspectionNotes(), resetEquipmentInspection(), resetAllInspections(), saveTemplate(), copyTemplatesToCycles()
EquipmentRepairService	getRepairs(), createRepair(), updateRepair(), deleteRepair(), getRecentRepairs()
EquipmentPhotoService	uploadPhotos(), uploadPhotoFromPath(), deletePhoto(), getPhotoUrls(), compressImage()
EquipmentImportService	preview(), import() — 엑셀 헤더 매핑, 이미지 추출, 중복 처리

4.2 뷰 파일 (mng/resources/views/equipment/)

equipment/
├── dashboard.blade.php              # 설비 현황 대시보드
├── index.blade.php                  # 설비 대장 목록
├── create.blade.php                 # 설비 등록
├── show.blade.php                   # 설비 상세
├── edit.blade.php                   # 설비 수정
├── import.blade.php                 # 엑셀 Import
├── guide.blade.php                  # 설비관리 가이드
├── inspections/
│   └── index.blade.php              # 점검 그리드 (6주기)
├── repairs/
│   ├── index.blade.php              # 수리이력 목록
│   └── create.blade.php             # 수리이력 등록
└── partials/
    ├── table.blade.php              # 설비 목록 테이블 (HTMX)
    ├── repair-table.blade.php       # 수리이력 테이블 (HTMX)
    ├── inspection-grid.blade.php    # 점검 그리드 (HTMX)
    ├── qr-code.blade.php            # QR 코드
    └── tabs/
        ├── basic-info.blade.php     # 설비 기본정보 탭
        ├── inspection-items.blade.php # 점검항목 탭
        └── repair-history.blade.php  # 수리이력 탭

---

5. 비즈니스 규칙

5.1 설비 상태

상태	코드	설명
가동	active	정상 운영 중
유휴	idle	일시 정지
폐기	disposed	사용 중단

5.2 점검 권한

• 관리자(isAdmin): 모든 설비 점검 가능
• 일반 사용자: manager_id 또는 sub_manager_id와 일치하는 설비만 점검 가능
• 권한 없는 사용자가 점검 시도 시 403 응답

5.3 점검 결과 순환

셀 클릭 시 결과가 순환한다:

(빈칸) → good(○) → bad(X) → repaired(△) → (빈칸)

5.4 휴일/주말 점검 제한

• 일일 점검(daily)에서 주말(토/일) 및 holidays 테이블 등록 휴일에는 점검 기록 불가
• 다른 주기(weekly/monthly 등)에는 제한 없음

5.5 설비 사진

• 최대 10장 (설비당)
• Cloudflare R2에 저장 (Storage::disk('r2'))
• 저장 경로: {tenantId}/equipment/{year}/{month}/{storedName}
• 다중 업로드 지원 (files[] multipart/form-data)
• 허용 확장자: jpg, jpeg, png, gif, bmp, webp (최대 10MB/파일)
• 삭제 시 soft delete (softDeleteFile()) 적용
• MNG는 GCS + 자동 압축, API는 R2 직접 저장

5.6 엑셀 Import (MNG 전용)

• 한글/영문 헤더 자동 매핑
• 중복 처리: skip 또는 overwrite 선택
• 엑셀 내 이미지(Drawing) 자동 추출 후 저장 (MNG: GCS, API: R2 예정)
• API에서는 미구현 (Phase 2+ 검토)

---

6. 향후 계획

단계	내용	상태
Phase 1	API 백엔드 (모델, 서비스, 컨트롤러, 라우트)	✅ 완료
Phase 2	React 프론트엔드	미착수
Phase 3	테스트 + Swagger 문서	미착수
추가	엑셀 Import API	검토 중
추가	모바일 점검 (React)	검토 중

---

관련 문서

• 서비스 구축 계획
• MNG 구조
• DB 스키마 — 공통
• options 컬럼 정책

---

최종 업데이트: 2026-03-12