From 9643994e2cd174ae0e5098ea9169dd1d36e8f181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Thu, 12 Mar 2026 09:42:55 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[equipment]=20=EC=84=A4=EB=B9=84?= =?UTF-8?q?=EA=B4=80=EB=A6=AC=20R&D=20=ED=98=84=ED=99=A9=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - MNG 완료된 전체 구현 현황 상세 문서화 - DB 테이블 6개, ERD, 주요 컬럼 명세 - 모델/서비스/컨트롤러/뷰/라우트 구조 - InspectionCycle 6주기, 비즈니스 규칙 - API+React 서비스 구축을 위한 참조 문서 --- features/equipment/README.md | 320 ++++++++++++++++++++++++++++++++--- 1 file changed, 300 insertions(+), 20 deletions(-) diff --git a/features/equipment/README.md b/features/equipment/README.md index 7f0274d..175568d 100644 --- 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