sam-docs/dev/dev_plans/equipment-service-build-plan.md

# 설비관리 본 시스템 구축 계획

> **작성일**: 2026-03-12
> **상태**: 계획 수립
> **담당**: R&D실
> **R&D 출처**: MNG 설비관리 (R&D 완료)

---

## 1. 개요

### 1.1 목적

MNG에서 R&D 완료된 설비관리 기능을 본 시스템(API + React)에 서비스로 구축한다.

### 1.2 범위

| 구분 | 내용 |
|------|------|
| API (Laravel) | 모델, 서비스, 컨트롤러, Request, Swagger, 라우트 |
| React (Next.js) | 페이지 5개, 컴포넌트, Hook, 타입, API 연동 |
| DB | 테이블 이미 존재 (마이그레이션 완료) — `options` 컬럼 추가 필요 |

### 1.3 MNG → 본 시스템 차이점

| 항목 | MNG (R&D) | API + React (본 시스템) |
|------|----------|----------------------|
| 아키텍처 | Blade + HTMX | REST API + Next.js SPA |
| 인증 | 세션 기반 (`auth()`) | Sanctum 토큰 (`apiUserId()`) |
| 테넌트 | `session('selected_tenant_id')` | `tenantId()` (Service 기본클래스) |
| DB 연결 | `$connection = 'codebridge'` | 기본 connection (제거) |
| 응답 형식 | Blade View / JsonResponse | `ApiResponse::handle()` |
| 감사 로그 | 없음 | `Auditable` trait 적용 |
| 메시지 | 한글 직접 사용 | i18n 키 (`__('message.xxx')`) |
| 파일 업로드 | GCS 직접 호출 | API 파일 서비스 통합 |

---

## 2. 단계별 계획

### Phase 1: API 백엔드 (1일차)

DB 테이블은 이미 존재하므로 `options` 컬럼 추가 마이그레이션 후 모델부터 시작한다.

#### 2.1 마이그레이션 — `options` 컬럼 추가

> 정책: `docs/standards/options-column-policy.md` 준수

```
api/database/migrations/
└── YYYY_MM_DD_add_options_to_equipment_tables.php
    - equipments: options JSON nullable
    - equipment_repairs: options JSON nullable
```

#### 2.2 모델 생성

```
api/app/Models/Equipment/
├── Equipment.php
├── EquipmentInspection.php
├── EquipmentInspectionDetail.php
├── EquipmentInspectionTemplate.php
├── EquipmentRepair.php
└── EquipmentProcess.php
```

**MNG 대비 변경 사항:**

| 항목 | MNG | API |
|------|-----|-----|
| `$connection` | `'codebridge'` | 제거 (기본 connection) |
| Traits | `BelongsToTenant` | `Auditable`, `BelongsToTenant`, `ModelTrait`, `SoftDeletes` |
| `$casts` | 기본 | `'options' => 'array'` 추가 |
| 헬퍼 | 없음 | `getOption()`, `setOption()` 추가 |

#### 2.3 서비스 생성

```
api/app/Services/Equipment/
├── EquipmentService.php           # 설비 CRUD + 대시보드
├── EquipmentInspectionService.php # 점검 CRUD + 그리드
├── EquipmentRepairService.php     # 수리이력 CRUD
└── EquipmentPhotoService.php      # 사진 업로드/삭제
```

**MNG 대비 변경 사항:**

| 항목 | MNG | API |
|------|-----|-----|
| 기본 클래스 | 없음 | `extends Service` |
| 테넌트 | `session('selected_tenant_id', 1)` | `$this->tenantId()` |
| 사용자 | `auth()->id()` | `$this->apiUserId()` |
| 에러 | `throw new \Exception(...)` | `throw new HttpException(403, __('error.xxx'))` |
| 트랜잭션 | 없음 | `DB::transaction()` 적용 |

**엑셀 Import 서비스는 Phase 2에서 구현** (1차에서는 CRUD + 점검 + 수리 우선)

#### 2.4 FormRequest 생성

```
api/app/Http/Requests/V1/Equipment/
├── StoreEquipmentRequest.php
├── UpdateEquipmentRequest.php
├── StoreEquipmentRepairRequest.php
├── StoreInspectionTemplateRequest.php
├── ToggleInspectionDetailRequest.php
└── UpdateInspectionNotesRequest.php
```

#### 2.5 컨트롤러 생성

```
api/app/Http/Controllers/V1/Equipment/
├── EquipmentController.php           # 설비 CRUD + 통계
├── EquipmentInspectionController.php # 점검 그리드 + 셀 토글
├── EquipmentRepairController.php     # 수리이력 CRUD
└── EquipmentPhotoController.php      # 사진 관리
```

**패턴** (기존 API 컨벤션):

```php
class EquipmentController extends Controller
{
    public function __construct(private readonly EquipmentService $service) {}

    public function index(Request $request): JsonResponse
    {
        return ApiResponse::handle(
            fn () => $this->service->index($request->only([...])),
            'message.fetched'
        );
    }

    public function store(StoreEquipmentRequest $request): JsonResponse
    {
        return ApiResponse::handle(
            fn () => $this->service->store($request->validated()),
            'message.created'
        );
    }
}
```

#### 2.6 라우트 등록

```
api/routes/api/v1/equipment.php (신규 파일)
```

```php
Route::prefix('equipment')->group(function () {
    // 설비 CRUD
    Route::get('', [EquipmentController::class, 'index']);
    Route::get('/options', [EquipmentController::class, 'options']);
    Route::get('/stats', [EquipmentController::class, 'stats']);
    Route::post('', [EquipmentController::class, 'store']);
    Route::get('/{id}', [EquipmentController::class, 'show'])->whereNumber('id');
    Route::put('/{id}', [EquipmentController::class, 'update'])->whereNumber('id');
    Route::delete('/{id}', [EquipmentController::class, 'destroy'])->whereNumber('id');
    Route::post('/{id}/restore', [EquipmentController::class, 'restore'])->whereNumber('id');
    Route::patch('/{id}/toggle', [EquipmentController::class, 'toggleActive'])->whereNumber('id');

    // 점검 템플릿
    Route::get('/{id}/templates', [EquipmentInspectionController::class, 'templates'])->whereNumber('id');
    Route::post('/{id}/templates', [EquipmentInspectionController::class, 'storeTemplate'])->whereNumber('id');
    Route::put('/templates/{templateId}', [EquipmentInspectionController::class, 'updateTemplate']);
    Route::delete('/templates/{templateId}', [EquipmentInspectionController::class, 'deleteTemplate']);
    Route::post('/{id}/templates/copy', [EquipmentInspectionController::class, 'copyTemplates'])->whereNumber('id');

    // 점검
    Route::get('/inspections', [EquipmentInspectionController::class, 'index']);
    Route::patch('/inspections/toggle', [EquipmentInspectionController::class, 'toggleDetail']);
    Route::patch('/inspections/set-result', [EquipmentInspectionController::class, 'setResult']);
    Route::patch('/inspections/notes', [EquipmentInspectionController::class, 'updateNotes']);
    Route::delete('/inspections/reset', [EquipmentInspectionController::class, 'resetInspection']);

    // 수리이력
    Route::get('/repairs', [EquipmentRepairController::class, 'index']);
    Route::post('/repairs', [EquipmentRepairController::class, 'store']);
    Route::put('/repairs/{id}', [EquipmentRepairController::class, 'update'])->whereNumber('id');
    Route::delete('/repairs/{id}', [EquipmentRepairController::class, 'destroy'])->whereNumber('id');

    // 사진
    Route::get('/{id}/photos', [EquipmentPhotoController::class, 'index'])->whereNumber('id');
    Route::post('/{id}/photos', [EquipmentPhotoController::class, 'store'])->whereNumber('id');
    Route::delete('/{id}/photos/{fileId}', [EquipmentPhotoController::class, 'destroy'])->whereNumber('id');
});
```

#### 2.7 Enum 이관

```
api/app/Enums/InspectionCycle.php
```

MNG의 `InspectionCycle` 그대로 이관. `Holiday` 모델 참조 경로만 API 쪽으로 변경.

#### 2.8 Swagger 문서

```
api/app/Swagger/v1/EquipmentApi.php
```

스키마: Equipment, EquipmentRepair, EquipmentInspection, InspectionTemplate, InspectionDetail

#### 2.9 i18n 메시지 추가

```php
// 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' => '설비를 찾을 수 없습니다.',
    'no_inspect_permission' => '점검 권한이 없습니다.',
    'non_working_day' => '휴일/주말에는 점검을 기록할 수 없습니다.',
],
```

---

### Phase 2: React 프론트엔드 (2~3일차)

#### 2.10 타입 정의

```
react/src/types/equipment.ts
```

```typescript
interface Equipment {
  id: number;
  equipment_code: string;
  name: string;
  equipment_type: string | null;
  production_line: string | null;
  status: 'active' | 'idle' | 'disposed';
  manager?: { id: number; name: string };
  sub_manager?: { id: number; name: string };
  purchase_date: string | null;
  install_date: string | null;
  purchase_price: number | null;
  useful_life: number | null;
  memo: string | null;
  options: Record<string, any> | null;
}

interface EquipmentRepair { ... }
interface InspectionTemplate { ... }
interface InspectionData { ... }
interface InspectionDetail { ... }

interface EquipmentStats {
  total: number;
  active: number;
  idle: number;
  disposed: number;
}
```

#### 2.11 API 서비스

```
react/src/lib/api/equipment.ts
```

`buildApiUrl()` + `/api/proxy/equipment/*` 패턴 사용.

#### 2.12 페이지 구조

```
react/src/app/[locale]/(protected)/equipment/
├── page.tsx                    # 설비 대시보드
├── registry/
│   ├── page.tsx                # 설비 대장 목록 (UniversalListPage)
│   ├── create/page.tsx         # 설비 등록
│   └── [id]/
│       ├── page.tsx            # 설비 상세
│       └── edit/page.tsx       # 설비 수정
├── inspections/
│   └── page.tsx                # 점검 그리드
└── repairs/
    ├── page.tsx                # 수리이력 목록
    └── create/page.tsx         # 수리이력 등록
```

#### 2.13 컴포넌트 구조

```
react/src/components/equipment/
├── EquipmentDashboard.tsx      # 대시보드 (통계 카드 + 차트)
├── EquipmentListClient.tsx     # 설비 목록 (UniversalListPage)
├── EquipmentDetailClient.tsx   # 설비 상세 (탭: 기본정보/점검항목/수리이력/사진)
├── EquipmentForm.tsx           # 등록/수정 폼 (Zod + React Hook Form, 등록 시 사진 대기열+자동업로드)
├── InspectionGrid.tsx          # 점검 그리드 (6주기, 셀 토글)
├── InspectionCycleSelector.tsx # 주기/기간 선택
├── RepairListClient.tsx        # 수리이력 목록
├── RepairForm.tsx              # 수리이력 등록/수정 폼
└── EquipmentPhotoGallery.tsx   # 사진 갤러리 (업로드/삭제)
```

#### 2.14 Hook

```
react/src/hooks/
├── useEquipmentList.ts         # 설비 목록 (검색, 필터, 페이징)
├── useEquipmentDetail.ts       # 설비 상세 로딩
├── useInspectionGrid.ts        # 점검 그리드 데이터 + 셀 토글
└── useEquipmentRepairs.ts      # 수리이력 목록
```

#### 2.15 페이지별 구현 상세

**설비 대시보드** (`/equipment`):
- 통계 카드 4개 (총/가동/유휴/폐기) → `StatCards` 재사용
- 유형별 분포 차트 (Recharts `PieChart`)
- 최근 수리이력 테이블 (5건)
- 이번 달 점검 현황

**설비 대장** (`/equipment/registry`):
- `UniversalListPage<Equipment>` 적용
- 탭: 전체 / 가동 / 유휴 / 폐기
- 검색: 코드, 설비명
- 필터: 생산라인, 설비유형
- 엑셀 다운로드

**설비 상세** (`/equipment/registry/[id]`):
- 탭 구조: 기본정보 | 점검항목 | 수리이력 | 사진
- 기본정보: FormField 그리드 (읽기모드/수정모드 전환)
- 점검항목: 템플릿 CRUD (주기별)
- 수리이력: 해당 설비 필터 적용된 테이블
- 사진: 갤러리 + 업로드 + 삭제

**점검 그리드** (`/equipment/inspections`):
- 주기 선택 탭 (일일~반년)
- 기간 선택 (월/년)
- 생산라인 필터
- 그리드: 설비×점검항목 → 날짜/기간별 셀
- 셀 클릭 → API 호출 → 결과 순환 (○→X→△→빈칸)
- 종합판정, 수리내역, 이상내용 편집

**수리이력** (`/equipment/repairs`):
- `UniversalListPage<EquipmentRepair>` 적용
- 필터: 설비, 보전구분, 날짜 범위
- 등록/수정 모달 또는 별도 페이지

---

### Phase 3: 통합 및 검증 (4일차)

#### 2.16 API 테스트

```bash
# Swagger UI에서 검증
docker exec sam-api-1 php artisan l5-swagger:generate
# http://api.sam.kr/api-docs
```

#### 2.17 React 연동 테스트

```
- 설비 CRUD (등록→조회→수정→삭제→복원)
- 점검 그리드 (주기 전환, 셀 토글, 노트 저장)
- 수리이력 (등록→수정→삭제)
- 사진 (업로드→조회→삭제)
- 권한 (담당자/비담당자 점검 제한)
- 모바일 반응형
```

#### 2.18 Pint + 코드 품질

```bash
cd /home/aweso/sam/api && docker exec sam-api-1 ./vendor/bin/pint
```

---

## 3. 파일 목록 총정리

### API (sam/api) — 신규 생성

| # | 파일 | 설명 |
|---|------|------|
| 1 | `database/migrations/YYYY_add_options_to_equipment_tables.php` | options 컬럼 추가 |
| 2 | `app/Models/Equipment/Equipment.php` | 설비 모델 |
| 3 | `app/Models/Equipment/EquipmentInspection.php` | 점검 모델 |
| 4 | `app/Models/Equipment/EquipmentInspectionDetail.php` | 점검 상세 모델 |
| 5 | `app/Models/Equipment/EquipmentInspectionTemplate.php` | 점검 템플릿 모델 |
| 6 | `app/Models/Equipment/EquipmentRepair.php` | 수리이력 모델 |
| 7 | `app/Models/Equipment/EquipmentProcess.php` | 설비-공정 pivot |
| 8 | `app/Enums/InspectionCycle.php` | 점검주기 Enum |
| 9 | `app/Services/Equipment/EquipmentService.php` | 설비 서비스 |
| 10 | `app/Services/Equipment/EquipmentInspectionService.php` | 점검 서비스 |
| 11 | `app/Services/Equipment/EquipmentRepairService.php` | 수리 서비스 |
| 12 | `app/Services/Equipment/EquipmentPhotoService.php` | 사진 서비스 |
| 13 | `app/Http/Controllers/V1/Equipment/EquipmentController.php` | 설비 컨트롤러 |
| 14 | `app/Http/Controllers/V1/Equipment/EquipmentInspectionController.php` | 점검 컨트롤러 |
| 15 | `app/Http/Controllers/V1/Equipment/EquipmentRepairController.php` | 수리 컨트롤러 |
| 16 | `app/Http/Controllers/V1/Equipment/EquipmentPhotoController.php` | 사진 컨트롤러 |
| 17 | `app/Http/Requests/V1/Equipment/StoreEquipmentRequest.php` | 설비 등록 검증 |
| 18 | `app/Http/Requests/V1/Equipment/UpdateEquipmentRequest.php` | 설비 수정 검증 |
| 19 | `app/Http/Requests/V1/Equipment/StoreEquipmentRepairRequest.php` | 수리 등록 검증 |
| 20 | `app/Http/Requests/V1/Equipment/StoreInspectionTemplateRequest.php` | 템플릿 등록 검증 |
| 21 | `app/Http/Requests/V1/Equipment/ToggleInspectionDetailRequest.php` | 점검 토글 검증 |
| 22 | `app/Http/Requests/V1/Equipment/UpdateInspectionNotesRequest.php` | 점검 노트 검증 |
| 23 | `app/Swagger/v1/EquipmentApi.php` | Swagger 문서 |
| 24 | `routes/api/v1/equipment.php` | 라우트 파일 |

수정 파일:
| 파일 | 변경 |
|------|------|
| `routes/api.php` | equipment.php include 추가 |
| `lang/ko/message.php` | equipment 메시지 추가 |
| `lang/ko/error.php` | equipment 에러 메시지 추가 |

### React (sam/react) — 신규 생성

| # | 파일 | 설명 |
|---|------|------|
| 1 | `src/types/equipment.ts` | 타입 정의 |
| 2 | `src/lib/api/equipment.ts` | API 서비스 |
| 3 | `src/hooks/useEquipmentList.ts` | 목록 Hook |
| 4 | `src/hooks/useEquipmentDetail.ts` | 상세 Hook |
| 5 | `src/hooks/useInspectionGrid.ts` | 점검 그리드 Hook |
| 6 | `src/hooks/useEquipmentRepairs.ts` | 수리이력 Hook |
| 7 | `src/app/[locale]/(protected)/equipment/page.tsx` | 대시보드 |
| 8 | `src/app/[locale]/(protected)/equipment/registry/page.tsx` | 설비 목록 |
| 9 | `src/app/[locale]/(protected)/equipment/registry/create/page.tsx` | 설비 등록 |
| 10 | `src/app/[locale]/(protected)/equipment/registry/[id]/page.tsx` | 설비 상세 |
| 11 | `src/app/[locale]/(protected)/equipment/registry/[id]/edit/page.tsx` | 설비 수정 |
| 12 | `src/app/[locale]/(protected)/equipment/inspections/page.tsx` | 점검 그리드 |
| 13 | `src/app/[locale]/(protected)/equipment/repairs/page.tsx` | 수리이력 |
| 14 | `src/app/[locale]/(protected)/equipment/repairs/create/page.tsx` | 수리 등록 |
| 15 | `src/components/equipment/EquipmentDashboard.tsx` | 대시보드 |
| 16 | `src/components/equipment/EquipmentListClient.tsx` | 목록 |
| 17 | `src/components/equipment/EquipmentDetailClient.tsx` | 상세 |
| 18 | `src/components/equipment/EquipmentForm.tsx` | 폼 |
| 19 | `src/components/equipment/InspectionGrid.tsx` | 점검 그리드 |
| 20 | `src/components/equipment/InspectionCycleSelector.tsx` | 주기 선택 |
| 21 | `src/components/equipment/RepairListClient.tsx` | 수리 목록 |
| 22 | `src/components/equipment/RepairForm.tsx` | 수리 폼 |
| 23 | `src/components/equipment/EquipmentPhotoGallery.tsx` | 사진 갤러리 |

---

## 4. 구현 우선순위

| 순위 | 기능 | 이유 |
|------|------|------|
| 🔴 1 | 설비 CRUD (API + React) | 기본 데이터 관리 |
| 🔴 2 | 점검 그리드 (API + React) | 핵심 업무 기능, 일일 사용 |
| 🔴 3 | 수리이력 (API + React) | 설비 이력 추적 |
| 🟡 4 | 사진 관리 | GCS 연동 필요 |
| 🟡 5 | 대시보드 통계 | 조회 전용 |
| 🟢 6 | 엑셀 Import | Phase 2 (초기 데이터 입력용) |
| 🟢 7 | 모바일 점검 | Phase 2 (Capacitor 연동) |

---

## 5. 주의사항

### 5.1 DB 관련

- 마이그레이션은 API에서만 생성 (`sam/api/database/migrations/`)
- `options` 컬럼 추가 시 기존 데이터 영향 없음 (nullable)
- 테이블 이미 존재하므로 스키마 변경 최소화

### 5.2 MNG 코드 이관 시

- `$connection = 'codebridge'` → 제거
- `session('selected_tenant_id')` → `$this->tenantId()`
- `auth()->id()` → `$this->apiUserId()`
- `throw new \Exception()` → i18n 메시지 + HttpException
- `Auditable` trait 추가 (감사 로그 자동화)
- 한글 직접 문자열 → `__('message.equipment.xxx')` 변환

### 5.3 React 관련

- `'use client'` 필수 (모든 페이지 컴포넌트)
- API 호출은 `/api/proxy/equipment/*` 프록시 경로
- `buildApiUrl()` 사용 필수
- UniversalListPage 템플릿 재사용 (목록 페이지)
- Zod + React Hook Form (폼 검증)
- 모바일 반응형 필수 (ListMobileCard)

---

## 관련 문서

- [설비관리 R&D 현황](../../features/equipment/README.md)
- [API 개발 규칙](../standards/api-rules.md)
- [options 컬럼 정책](../standards/options-column-policy.md)
- [Swagger 가이드](../guides/swagger-guide.md)
- [React 구조](../../system/react-structure.md)

---

**최종 업데이트**: 2026-03-12 (설비 등록 시 사진 업로드 기능 반영)