docs: [business-card] 명함신청 기능 문서 추가

- features/business-card-request.md 생성 (테이블, 워크플로우, 화면 구성, API) - INDEX.md에 문서 등록
2026-02-25 05:49:33 +09:00
parent 41b1e01ce4
commit 8d6fd5aee6
2 changed files with 176 additions and 0 deletions
--- a/sam/docs/INDEX.md
+++ b/sam/docs/INDEX.md
@@ -150,6 +150,8 @@ docs/

 | 문서 | 설명 |
 |------|------|
+| [SAM_ERP_Storyboard_D1.4_260116.md](plans/SAM_ERP_Storyboard_D1.4_260116.md) | ERP 전체 스토리보드 D1.4 (167p PDF → 마크다운 변환, 14개 섹션 146개 화면) |
+| [SAM_ERP_Storyboard_D1.4.md](plans/SAM_ERP_Storyboard_D1.4.md) | ERP 스토리보드 D1.4 AI 최적화 버전 (구조화된 한글 마크다운, 15개 섹션) |
 | [SAM_ERP_회계관리_Storyboard_D1.6.md](plans/SAM_ERP_회계관리_Storyboard_D1.6.md) | ERP 회계관리 스토리보드 D1.6 (65p PDF → 마크다운 변환) |
 | [SAM_General_Rule_Storyboard_D1.0.md](plans/SAM_General_Rule_Storyboard_D1.0.md) | General Rule 스토리보드 D1.0 (43p PDF → 마크다운 변환, UIUX 공통 규칙) |
 | [production-deployment-plan.md](plans/production-deployment-plan.md) | 운영 환경 배포 계획 (CI/CD, 서버 아키텍처) |
@@ -163,6 +165,7 @@ docs/
 | [boards/mng-implementation.md](features/boards/mng-implementation.md) | MNG 게시판 구현 상세 |
 | [hr/hr-api-analysis.md](features/hr/hr-api-analysis.md) | HR API 분석 (근태/직원/부서) |
 | [quotes/README.md](features/quotes/README.md) | 견적 시스템 분석 (BOM 계산, 10단계 로직) |
+| [business-card-request.md](features/business-card-request.md) | 명함신청 관리 (3단계 워크플로우: 요청→제작의뢰→처리완료) |
 | [academy/fire-shutter-image-prompts.md](features/academy/fire-shutter-image-prompts.md) | 방화셔터 백과사전 이미지 생성 프롬프트 (Gemini용) |

 ### projects/ - 프로젝트별 문서
--- a/sam/docs/features/business-card-request.md
+++ b/sam/docs/features/business-card-request.md
@@ -0,0 +1,173 @@
+# 명함신청 관리
+
+> **작성일**: 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