sam-docs/plans/sub/categories-plan.md

# 카테고리관리 (Categories) API 연동 계획

> **작성일**: 2026-01-08
> **상위 문서**: [construction-api-integration-plan.md](../construction-api-integration-plan.md)
> **상태**: ⏳ 대기
> **API 상태**: ✅ 기존 API 존재

---

## 1. 컴포넌트 분석

### 1.1 파일 위치
```
react/src/
├── app/[locale]/(protected)/construction/order/base-info/categories/
│   └── page.tsx
└── components/business/construction/category-management/
    ├── CategoryManagementClient.tsx
    ├── actions.ts
    └── types.ts
```

### 1.2 현재 Mock 데이터

**actions.ts 내 mockCategories:**
```typescript
let mockCategories: Category[] = [
  { id: '1', name: '슬라이드 OPEN 사이즈', order: 1, isDefault: true },
  { id: '2', name: '모터', order: 2, isDefault: true },
  { id: '3', name: '공정자재', order: 3, isDefault: true },
  { id: '4', name: '철물', order: 4, isDefault: true },
];
```

### 1.3 현재 함수 목록

| 함수명 | 용도 | Mock 상태 |
|--------|------|:--------:|
| `getCategories` | 카테고리 목록 조회 | ✅ Mock |
| `createCategory` | 카테고리 생성 | ✅ Mock |
| `updateCategory` | 카테고리 수정 | ✅ Mock |
| `deleteCategory` | 카테고리 삭제 | ✅ Mock |
| `reorderCategories` | 카테고리 순서 변경 | ✅ Mock |

---

## 2. 기존 API 분석

### 2.1 기존 엔드포인트 (api/routes/api.php line 835-880)

```php
Route::prefix('construction/categories')->group(function () {
    Route::get('/', [CategoryController::class, 'index']);
    Route::get('/tree', [CategoryController::class, 'tree']);
    Route::post('/', [CategoryController::class, 'store']);
    Route::post('/reorder', [CategoryController::class, 'reorder']);
    Route::get('/{category}', [CategoryController::class, 'show']);
    Route::put('/{category}', [CategoryController::class, 'update']);
    Route::patch('/{category}/toggle', [CategoryController::class, 'toggle']);
    Route::post('/{category}/move', [CategoryController::class, 'move']);
    Route::delete('/{category}', [CategoryController::class, 'destroy']);

    // 필드 관리
    Route::get('/{category}/fields', [CategoryController::class, 'fields']);
    Route::post('/{category}/fields', [CategoryController::class, 'storeField']);
    Route::put('/{category}/fields/{field}', [CategoryController::class, 'updateField']);
    Route::delete('/{category}/fields/{field}', [CategoryController::class, 'destroyField']);
    Route::post('/{category}/fields/reorder', [CategoryController::class, 'reorderFields']);

    // 템플릿 관리
    Route::get('/{category}/templates', [CategoryController::class, 'templates']);
    Route::post('/{category}/templates', [CategoryController::class, 'storeTemplate']);

    // 변경 로그
    Route::get('/{category}/logs', [CategoryController::class, 'logs']);
});
```

### 2.2 API-컴포넌트 매핑

| 컴포넌트 함수 | API 엔드포인트 | 매핑 상태 |
|--------------|---------------|:--------:|
| `getCategories` | `GET /construction/categories` | ✅ 매핑 가능 |
| `createCategory` | `POST /construction/categories` | ✅ 매핑 가능 |
| `updateCategory` | `PUT /construction/categories/{id}` | ✅ 매핑 가능 |
| `deleteCategory` | `DELETE /construction/categories/{id}` | ✅ 매핑 가능 |
| `reorderCategories` | `POST /construction/categories/reorder` | ✅ 매핑 가능 |

---

## 3. 작업 항목

### 3.1 Backend (API)

| # | 작업 | 상태 | 비고 |
|---|------|:----:|------|
| 1 | 기존 API 응답 형식 확인 | ⏳ | |
| 2 | 프론트 타입과 정합성 확인 | ⏳ | |
| 3 | 필요시 API 수정 | ⏳ | |

### 3.2 Frontend (React)

| # | 작업 | 상태 | 비고 |
|---|------|:----:|------|
| 1 | actions.ts Mock → API 변환 | ⏳ | |
| 2 | API 클라이언트 연동 | ⏳ | |
| 3 | 에러 핸들링 추가 | ⏳ | |
| 4 | types.ts 정합성 확인 | ⏳ | |

---

## 4. 타입 정의

### 4.1 Category 타입 (현재)

```typescript
interface Category {
  id: string;
  name: string;
  order: number;
  isDefault: boolean;
}
```

### 4.2 API 응답 타입 (확인 필요)

```typescript
// API 응답과 프론트 타입 매칭 필요
interface CategoryResponse {
  id: number | string;
  name: string;
  order: number;
  is_default: boolean; // snake_case → camelCase 변환 필요
  parent_id?: number;
  // 추가 필드 확인 필요
}
```

---

## 5. 변경 이력

| 날짜 | 작업 | 상태 |
|------|------|------|
| 2026-01-08 | 문서 초안 작성 | ✅ |

---

*상위 문서: [construction-api-integration-plan.md](../construction-api-integration-plan.md)*