docs: [equipment] API+React 서비스 구축 계획 수립

2026-03-12 10:09:06 +09:00
parent 9643994e2c
commit 366d51fcd1
2 changed files with 512 additions and 1 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -145,7 +145,7 @@ DB 도메인별:
 | [hr/](features/hr/) | 인사관리 |
 | [crm/README.md](features/crm/README.md) | CRM |
 | [esign/README.md](features/esign/README.md) | 전자서명 |
-| [equipment/README.md](features/equipment/README.md) | 설비관리 |
+| [equipment/README.md](features/equipment/README.md) | 설비관리 (MNG R&D 현황 + DB 스키마) |
 | [boards/README.md](features/boards/README.md) | 게시판 |
 | [ai/README.md](features/ai/README.md) | AI 분석 |
 | [card-vehicle/README.md](features/card-vehicle/README.md) | 법인카드·차량 |
--- a/dev/dev_plans/equipment-service-build-plan.md
+++ b/dev/dev_plans/equipment-service-build-plan.md
@@ -0,0 +1,511 @@
+# 설비관리 본 시스템 구축 계획
+
+> **작성일**: 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