# 명함신청 관리

> **작성일**: 2026-02-25
> **상태**: 구현 완료

---

## 1. 개요

### 1.1 목적

영업파트너가 명함을 신청하면 본사에서 제작소에 의뢰하고, 완료 후 처리하는 3단계 워크플로우를 제공한다.

### 1.2 워크플로우

```
요청(pending) ──제작의뢰──→ 제작중(ordered) ──처리완료──→ 완료(processed)
   노랑                        파랑                        초록
```

### 1.3 메뉴 구조

| 메뉴 | URL | 대상 | 설명 |
|------|-----|------|------|
| 파트너 명함신청 | `/sales/business-cards` | 모든 사용자 | 신청폼 + 내 이력 |
| 명함신청 처리 | `/sales/business-cards/manage` | 관리자 전용 | 3단계 처리 + 뱃지 |

---

## 2. 테이블 구조

### 2.1 `business_card_requests`

| 필드 | 타입 | 설명 |
|------|------|------|
| `id` | bigint | PK |
| `tenant_id` | bigint | 테넌트 ID |
| `user_id` | bigint | 신청자 ID |
| `name` | varchar(50) | 성함 |
| `phone` | varchar(20) | 전화번호 |
| `title` | varchar(50) | 직함 (nullable) |
| `email` | varchar(100) | 이메일 (nullable) |
| `quantity` | int | 수량 (기본 100) |
| `memo` | text | 비고 (nullable) |
| `status` | varchar(20) | 상태: `pending`, `ordered`, `processed` |
| `ordered_by` | bigint | 제작의뢰 처리자 ID (nullable) |
| `ordered_at` | timestamp | 제작의뢰 일시 (nullable) |
| `processed_by` | bigint | 처리완료 처리자 ID (nullable) |
| `processed_at` | timestamp | 처리완료 일시 (nullable) |
| `process_memo` | text | 처리 메모 (nullable) |
| `created_at` | timestamp | 생성일 |
| `updated_at` | timestamp | 수정일 |

**인덱스**: `(tenant_id, status)`, `user_id`

---

## 3. 상태 전이

```
pending ──→ ordered ──→ processed
  │                        ▲
  └── (역방향 전이 없음) ──┘
```

| 상태 | 라벨 | 색상 | 설명 |
|------|------|------|------|
| `pending` | 요청 | 노랑 | 파트너가 신청, 관리자 확인 대기 |
| `ordered` | 제작의뢰 | 파랑 | 관리자가 제작소에 의뢰 |
| `processed` | 처리완료 | 초록 | 제작 완료, 전달 완료 |

---

## 4. API 엔드포인트

| Method | Path | 이름 | 설명 |
|--------|------|------|------|
| GET | `/sales/business-cards` | `sales.business-cards.index` | 파트너 명함신청 (신청폼 + 이력) |
| POST | `/sales/business-cards` | `sales.business-cards.store` | 신청 등록 |
| GET | `/sales/business-cards/manage` | `sales.business-cards.manage` | 관리자 처리 화면 |
| POST | `/sales/business-cards/{id}/order` | `sales.business-cards.order` | 제작의뢰 (관리자) |
| POST | `/sales/business-cards/{id}/process` | `sales.business-cards.process` | 처리완료 (관리자) |

---

## 5. 파일 구조

### 5.1 API 프로젝트

| 파일 | 설명 |
|------|------|
| `database/migrations/2026_02_24_100000_create_business_card_requests_table.php` | 테이블 생성 |
| `database/migrations/2026_02_25_100000_add_ordered_columns_to_business_card_requests_table.php` | ordered 컬럼 추가 |

### 5.2 MNG 프로젝트

| 파일 | 설명 |
|------|------|
| `app/Models/Sales/BusinessCardRequest.php` | 모델 (상태 상수, 스코프, 헬퍼) |
| `app/Services/Sales/BusinessCardRequestService.php` | 서비스 (CRUD, 통계, 뱃지) |
| `app/Http/Controllers/Sales/BusinessCardRequestController.php` | 컨트롤러 |
| `app/Providers/ViewServiceProvider.php` | 사이드바 뱃지 연동 |
| `routes/web.php` | 라우트 5개 |
| `resources/views/sales/business-cards/admin-index.blade.php` | 관리자 뷰 |
| `resources/views/sales/business-cards/partner-index.blade.php` | 파트너 뷰 |

---

## 6. 화면 구성

### 6.1 파트너 명함신청 (`partner-index`)

```
┌─ 회사 정보 안내 (코드브릿지엑스) ──────────────┐
├─ 신청 폼 ─────────────────────────────────────┤
│  성함* │ 직함   │ 전화번호* │ 이메일            │
│  수량  │ 메모   │          [명함 신청하기]       │
├─ 내 신청 이력 ────────────────────────────────┤
│  신청일 │ 성함 │ 직함 │ 전화번호 │ 수량 │ 상태  │
│  (요청=노랑, 제작중=파랑, 처리완료=초록)        │
└───────────────────────────────────────────────┘
```

- 로그인 사용자 정보(name, phone, email)로 자동 채움
- 관리자도 동일한 화면 접근 가능

### 6.2 명함신청 처리 (`admin-index`)

```
┌─ 통계 ──────────────────────────────────────┐
│ 신규요청(노랑) │ 제작의뢰(파랑) │ 오늘처리(초록) │ 전체 │
├─────────────────┬───────────────────────────┤
│  신규 요청       │  제작 중                   │
│  [제작의뢰] 버튼 │  의뢰일 + [처리완료] 버튼   │
├─────────────────┴───────────────────────────┤
│  처리 완료 이력 (하단 스크롤 테이블)           │
└─────────────────────────────────────────────┘
```

- 사이드바 뱃지: 요청 + 제작의뢰 합산 건수 표시
- 처리 버튼 클릭 시 `showConfirm()` 확인 다이얼로그

---

## 7. 뱃지 연동

`ViewServiceProvider`에서 `BusinessCardRequestService::getPendingCount()`를 호출하여 사이드바 메뉴 뱃지에 대기 건수를 표시한다.

- **카운트 기준**: `pending` + `ordered` 합산
- **표시 위치**: "명함신청 처리" 메뉴 (`sales.business-cards.manage`)
- **0건일 때**: 뱃지 미표시

---

## 8. 메뉴 등록 정보

| ID | parent_id | 이름 | URL | sort_order |
|----|-----------|------|-----|------------|
| 15507 | 15456 | 파트너 명함신청 | `/sales/business-cards` | 5 |
| 15508 | 15456 | 명함신청 처리 | `/sales/business-cards/manage` | 6 |

> 영업파트너에게는 "파트너 명함신청"만 보이도록 메뉴 권한 설정 필요

---

## 관련 문서

- 참고 패턴: `api/app/Models/CompanyRequest.php` (상태 관리 모델)
- 참고 뷰: `mng/resources/views/sales/managers/approvals.blade.php` (2분할 레이아웃)

---

**최종 업데이트**: 2026-02-25