docs: [equipment] 설비관리 R&D 현황 문서 업데이트

- MNG 완료된 전체 구현 현황 상세 문서화 - DB 테이블 6개, ERD, 주요 컬럼 명세 - 모델/서비스/컨트롤러/뷰/라우트 구조 - InspectionCycle 6주기, 비즈니스 규칙 - API+React 서비스 구축을 위한 참조 문서
2026-03-12 09:42:55 +09:00
parent f6374867ac
commit 9643994e2c
1 changed files with 300 additions and 20 deletions
--- a/features/equipment/README.md
+++ b/features/equipment/README.md
@@ -1,42 +1,321 @@
 # 설비관리 (Equipment Management)

-> **상태**: MNG 전용 (API 미구현)
-> **최종 갱신**: 2026-02-27
+> **작성일**: 2026-02-27
+> **상태**: MNG R&D 완료 / API+React 미구현
+> **최종 갱신**: 2026-03-12

 ---

 ## 1. 개요

-MNG 관리자 패널에서만 사용 가능한 설비 관리 기능. REST API 엔드포인트는 없으며, Blade/HTMX 기반 웹 인터페이스로 운영된다.
+### 1.1 목적

-**핵심 기능:**
- 설비 등록/수정/삭제 (생산 설비, 검사 장비 등)
- 설비 점검 이력 관리
- 설비별 상태 추적
+생산 설비의 등록, 점검, 수리이력을 체계적으로 관리한다. MNG 관리자 패널에서 Blade/HTMX 기반으로 R&D가 완료되었으며, 본 시스템(API + React)으로의 서비스 구축이 필요하다.
+
+### 1.2 핵심 기능
+
+| 기능 | 설명 | MNG 구현 |
+|------|------|:--------:|
+| 설비 대시보드 | 현황 카드(총/가동/유휴/폐기), 유형별 통계, 최근 수리 | ✅ |
+| 설비 대장 (CRUD) | 등록/수정/삭제/복원, SoftDeletes | ✅ |
+| 설비 점검 | 6주기(일일~반년), 그리드 셀 토글, 종합판정 | ✅ |
+| 점검 템플릿 | 설비별 점검항목 정의, 주기간 복사 | ✅ |
+| 수리이력 | 사내/외주, 비용, 시간, 업체 관리 | ✅ |
+| 설비 사진 | GCS 업로드, 압축(1MB), 최대 10장 | ✅ |
+| 엑셀 Import | 미리보기 + 일괄등록, 이미지 포함 | ✅ |
+| 모바일 점검 | QR 스캔 → 모바일 점검 화면 | ✅ |
+| 설비-공정 매핑 | N:N 관계, 주 설비 여부 | ✅ |

 ---

-## 2. 구현 위치
+## 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` |
+
+### 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`
+
+| 컬럼 | 타입 | 설명 |
 |------|------|------|
-| Models | `mng/app/Models/Equipment/` | MNG 전용 |
-| Controllers | `mng/app/Http/Controllers/Equipment/` | Blade 렌더링 |
-| Views | `mng/resources/views/equipment/` | HTMX + DaisyUI |
-| Routes | `mng/routes/web.php` → equipment 그룹 | 웹 라우트만 |
+| `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 | 내용연수 |
+| `sort_order` | int | 정렬순서 |

-**참고:** API(`api/`)에는 Equipment 관련 모델·서비스·컨트롤러·라우트가 없음. 모바일/외부 연동이 필요하면 API 개발 필요.
+#### `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 | 수리자 |

 ---

-## 3. DB 테이블
+## 3. MNG 구현 현황

-마이그레이션은 `api/` 측에 존재하지만 모델은 `mng/`에만 구현됨.
+### 3.1 모델 (`mng/app/Models/Equipment/`)

-| 테이블 | 설명 |
+| 모델 | 파일 | 특이사항 |
+|------|------|---------|
+| `Equipment` | `Equipment.php` | BelongsToTenant, SoftDeletes, `connection='codebridge'` |
+| `EquipmentInspection` | `EquipmentInspection.php` | BelongsToTenant |
+| `EquipmentInspectionDetail` | `EquipmentInspectionDetail.php` | 결과 순환 로직 (`getNextResult`) |
+| `EquipmentInspectionTemplate` | `EquipmentInspectionTemplate.php` | BelongsToTenant |
+| `EquipmentRepair` | `EquipmentRepair.php` | BelongsToTenant, SoftDeletes |
+| `EquipmentProcess` | `EquipmentProcess.php` | pivot 모델 |
+
+### 3.2 서비스 (`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()` — 엑셀 헤더 매핑, 이미지 추출, 중복 처리 |
+
+### 3.3 Enum (`mng/app/Enums/InspectionCycle.php`)
+
+6개 점검주기를 관리하는 헬퍼 클래스:
+
+| 주기 | 코드 | 라벨 | period 형식 | 그리드 열 |
+|------|------|------|------------|----------|
+| 일일 | `daily` | 일일 | `2026-03` (년-월) | 1~31일 |
+| 주간 | `weekly` | 주간 | `2026` (년) | 1~52주 |
+| 월간 | `monthly` | 월간 | `2026` (년) | 1~12월 |
+| 2개월 | `bimonthly` | 2개월 | `2026` (년) | 1~6 (2개월 단위) |
+| 분기 | `quarterly` | 분기 | `2026` (년) | 1~4분기 |
+| 반년 | `semiannual` | 반년 | `2026` (년) | 상/하반기 |
+
+주요 메서드: `columnLabels()`, `resolveCheckDate()`, `resolvePeriod()`, `isNonWorkingDay()`, `getHolidayDates()`
+
+### 3.4 컨트롤러
+
+| 컨트롤러 | 경로 | 역할 |
+|---------|------|------|
+| `EquipmentController` | `app/Http/Controllers/` | 웹 뷰 렌더링 (dashboard, index, create, show, edit, inspections, repairs, import, guide) |
+| `Api\Admin\EquipmentController` | `app/Http/Controllers/Api/Admin/` | CRUD + 사진 + 템플릿 조회 + 엑셀 Import |
+| `Api\Admin\EquipmentInspectionController` | 위 동일 | 점검 그리드 조회, 셀 토글, 결과 설정, 노트, 초기화, 템플릿 CRUD, 주기 복사 |
+| `Api\Admin\EquipmentRepairController` | 위 동일 | 수리이력 CRUD |
+
+### 3.5 Request 클래스 (`mng/app/Http/Requests/`)
+
+| 클래스 | 용도 |
 |--------|------|
-| `equipments` | 설비 마스터 (이름, 유형, 상태, 위치) |
-| `equipment_inspections` | 설비 점검 이력 |
+| `StoreEquipmentRequest` | 설비 등록 (코드 unique per tenant) |
+| `UpdateEquipmentRequest` | 설비 수정 (코드 unique ignore self) |
+| `StoreEquipmentRepairRequest` | 수리이력 등록 |
+| `StoreEquipmentInspectionRequest` | 점검 기록 |
+
+### 3.6 라우트 구조
+
+**웹 라우트** (`routes/web.php`):
+
+```
+/equipment                      → dashboard
+/equipment/registry             → index (목록)
+/equipment/registry/create      → create (등록)
+/equipment/registry/{id}        → show (상세)
+/equipment/registry/{id}/edit   → edit (수정)
+/equipment/inspections          → inspections (점검)
+/equipment/repairs              → repairs (수리이력)
+/equipment/repairs/create       → repairCreate
+/equipment/import               → import (엑셀)
+/equipment/guide                → guide (가이드)
+```
+
+**API 라우트** (`routes/api.php`, prefix: `/admin/equipment`):
+
+```
+설비 CRUD:
+  GET    /admin/equipment           → index
+  POST   /admin/equipment           → store
+  GET    /admin/equipment/{id}      → show
+  PUT    /admin/equipment/{id}      → update
+  DELETE /admin/equipment/{id}      → destroy
+  POST   /admin/equipment/{id}/restore → restore
+
+점검 템플릿:
+  GET    /admin/equipment/{id}/templates          → templates
+  POST   /admin/equipment/{id}/templates          → storeTemplate
+  PUT    /admin/equipment/templates/{templateId}  → updateTemplate
+  DELETE /admin/equipment/templates/{templateId}  → deleteTemplate
+  POST   /admin/equipment/{id}/templates/copy     → copyTemplates
+
+점검:
+  GET    /admin/equipment/inspections             → index
+  PATCH  /admin/equipment/inspections/detail      → toggleDetail
+  PATCH  /admin/equipment/inspections/notes       → updateNotes
+  PATCH  /admin/equipment/inspections/set-result  → setResult
+  DELETE /admin/equipment/inspections/reset        → resetInspection
+  DELETE /admin/equipment/inspections/reset-all    → resetAllInspections
+
+수리이력:
+  GET    /admin/equipment/repairs      → index
+  POST   /admin/equipment/repairs      → store
+  PUT    /admin/equipment/repairs/{id} → update
+  DELETE /admin/equipment/repairs/{id} → destroy
+
+사진:
+  POST   /admin/equipment/{id}/photos           → uploadPhotos
+  GET    /admin/equipment/{id}/photos           → photos
+  DELETE /admin/equipment/{id}/photos/{fileId}  → deletePhoto
+
+Import:
+  POST   /admin/equipment/import/preview → importPreview
+  POST   /admin/equipment/import         → importExecute
+```
+
+### 3.7 뷰 파일 (`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  # 수리이력 탭
+```
+
+모바일: `mng/resources/views/mobile/inspection/show.blade.php`
+
+---
+
+## 4. 비즈니스 규칙
+
+### 4.1 설비 상태
+
+| 상태 | 코드 | 설명 |
+|------|------|------|
+| 가동 | `active` | 정상 운영 중 |
+| 유휴 | `idle` | 일시 정지 |
+| 폐기 | `disposed` | 사용 중단 |
+
+### 4.2 점검 권한
+
+- 관리자(`isAdmin`): 모든 설비 점검 가능
+- 일반 사용자: `manager_id` 또는 `sub_manager_id`와 일치하는 설비만 점검 가능
+- 권한 없는 사용자가 점검 시도 시 403 응답
+
+### 4.3 점검 결과 순환
+
+셀 클릭 시 결과가 순환한다:
+
+```
+(빈칸) → good(○) → bad(X) → repaired(△) → (빈칸)
+```
+
+### 4.4 휴일/주말 점검 제한
+
+- 일일 점검(`daily`)에서 주말(토/일) 및 `holidays` 테이블 등록 휴일에는 점검 기록 불가
+- 다른 주기(weekly/monthly 등)에는 제한 없음
+
+### 4.5 설비 사진
+
+- 최대 10장
+- 업로드 시 자동 압축 (장축 2048px, JPEG 품질 85→40 점진 감소, 1MB 이하)
+- PNG 투명도 있으면 PNG 유지, 없으면 JPEG 변환
+- GCS(Google Cloud Storage)에 저장, Signed URL로 조회
+
+### 4.6 엑셀 Import
+
+- 한글/영문 헤더 자동 매핑 (설비코드↔equipment_code 등)
+- 상태 한글 변환 (가동→active, 유휴→idle 등)
+- 중복 처리: skip(건너뜀) 또는 overwrite(덮어쓰기) 선택
+- 엑셀 내 이미지(Drawing) 자동 추출 후 GCS 업로드
+
+---
+
+## 5. 참고: MNG에서의 DB 연결
+
+MNG 모델은 `$connection = 'codebridge'`를 사용한다. 본 시스템(API)에서는 기본 connection을 사용하므로 모델 이관 시 이 속성을 제거해야 한다.

 ---

@@ -44,7 +323,8 @@ MNG 관리자 패널에서만 사용 가능한 설비 관리 기능. REST API

 - [MNG 구조](../../system/mng-structure.md)
 - [DB 스키마 — 공통](../../system/database/commons.md)
+- [options 컬럼 정책](../../dev/standards/options-column-policy.md) — 신규 테이블 생성 시 참고

 ---

-**최종 업데이트**: 2026-02-27
+**최종 업데이트**: 2026-03-12