# 수주 등록 컴포넌트

## 개요

수주 등록 기능을 위한 전용 컴포넌트들입니다. 이 컴포넌트들은 범용 컴포넌트를 래핑하여 수주 등록에 최적화된 고정 설정을 제공합니다.

## 컴포넌트 구조

```
frontend/components/order/
├── OrderRegistrationModal.tsx      # 수주 등록 메인 모달
├── OrderCustomerSearch.tsx         # 거래처 검색 (전용)
├── OrderItemRepeaterTable.tsx      # 품목 반복 테이블 (전용)
└── README.md                        # 문서 (현재 파일)
```

## 1. OrderRegistrationModal

수주 등록 메인 모달 컴포넌트입니다.

### Props

```typescript
interface OrderRegistrationModalProps {
  /** 모달 열림/닫힘 상태 */
  open: boolean;
  /** 모달 상태 변경 핸들러 */
  onOpenChange: (open: boolean) => void;
  /** 수주 등록 성공 시 콜백 */
  onSuccess?: () => void;
}
```

### 사용 예시

```tsx
import { OrderRegistrationModal } from "@/components/order/OrderRegistrationModal";

function MyComponent() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>수주 등록</Button>
      
      <OrderRegistrationModal
        open={isOpen}
        onOpenChange={setIsOpen}
        onSuccess={() => {
          console.log("수주 등록 완료!");
          // 목록 새로고침 등
        }}
      />
    </>
  );
}
```

### 기능

- **입력 방식 선택**: 거래처 우선, 견적 방식, 단가 방식
- **거래처 검색**: 자동완성 드롭다운으로 거래처 검색 및 선택
- **품목 관리**: 모달에서 품목 검색 및 추가, 수량/단가 입력, 금액 자동 계산
- **전체 금액 표시**: 추가된 품목들의 총 금액 계산
- **유효성 검사**: 거래처 및 품목 필수 입력 체크

---

## 2. OrderCustomerSearch

수주 등록 전용 거래처 검색 컴포넌트입니다.

### 특징

- `customer_mng` 테이블만 조회 (고정)
- 거래처명, 거래처코드, 사업자번호로 검색 (고정)
- 추가 정보 표시 (주소, 연락처)

### Props

```typescript
interface OrderCustomerSearchProps {
  /** 현재 선택된 거래처 코드 */
  value: string;
  /** 거래처 선택 시 콜백 (거래처 코드, 전체 데이터) */
  onChange: (customerCode: string | null, fullData?: any) => void;
  /** 비활성화 여부 */
  disabled?: boolean;
}
```

### 사용 예시

```tsx
import { OrderCustomerSearch } from "@/components/order/OrderCustomerSearch";

function MyForm() {
  const [customerCode, setCustomerCode] = useState("");
  const [customerName, setCustomerName] = useState("");

  return (
    <OrderCustomerSearch
      value={customerCode}
      onChange={(code, fullData) => {
        setCustomerCode(code || "");
        setCustomerName(fullData?.customer_name || "");
      }}
    />
  );
}
```

### 고정 설정

| 설정 | 값 | 설명 |
|------|-----|------|
| `tableName` | `customer_mng` | 거래처 테이블 |
| `displayField` | `customer_name` | 표시 필드 |
| `valueField` | `customer_code` | 값 필드 |
| `searchFields` | `["customer_name", "customer_code", "business_number"]` | 검색 대상 필드 |
| `additionalFields` | `["customer_code", "address", "contact_phone"]` | 추가 표시 필드 |

---

## 3. OrderItemRepeaterTable

수주 등록 전용 품목 반복 테이블 컴포넌트입니다.

### 특징

- `item_info` 테이블만 조회 (고정)
- 수주에 필요한 컬럼만 표시 (품번, 품명, 수량, 단가, 금액 등)
- 금액 자동 계산 (`수량 * 단가`)

### Props

```typescript
interface OrderItemRepeaterTableProps {
  /** 현재 선택된 품목 목록 */
  value: any[];
  /** 품목 목록 변경 시 콜백 */
  onChange: (items: any[]) => void;
  /** 비활성화 여부 */
  disabled?: boolean;
}
```

### 사용 예시

```tsx
import { OrderItemRepeaterTable } from "@/components/order/OrderItemRepeaterTable";

function MyForm() {
  const [items, setItems] = useState([]);

  return (
    <OrderItemRepeaterTable
      value={items}
      onChange={setItems}
    />
  );
}
```

### 고정 컬럼 설정

| 필드 | 라벨 | 타입 | 편집 | 필수 | 계산 | 설명 |
|------|------|------|------|------|------|------|
| `id` | 품번 | text | ❌ | - | - | 품목 ID |
| `item_name` | 품명 | text | ❌ | - | - | 품목명 |
| `item_number` | 품목번호 | text | ❌ | - | - | 품목 번호 |
| `quantity` | 수량 | number | ✅ | ✅ | - | 주문 수량 (기본값: 1) |
| `selling_price` | 단가 | number | ✅ | ✅ | - | 판매 단가 |
| `amount` | 금액 | number | ❌ | - | ✅ | 자동 계산 (수량 * 단가) |
| `delivery_date` | 납품일 | date | ✅ | - | - | 납품 예정일 |
| `note` | 비고 | text | ✅ | - | - | 추가 메모 |

### 계산 규칙

```javascript
amount = quantity * selling_price
```

---

## 범용 컴포넌트 vs 전용 컴포넌트

### 왜 전용 컴포넌트를 만들었나?

| 항목 | 범용 컴포넌트 | 전용 컴포넌트 |
|------|--------------|--------------|
| **목적** | 화면 편집기에서 다양한 용도로 사용 | 수주 등록 전용 |
| **설정** | ConfigPanel에서 자유롭게 변경 가능 | 하드코딩으로 고정 |
| **유연성** | 높음 (모든 테이블/필드 지원) | 낮음 (수주에 최적화) |
| **안정성** | 사용자 실수 가능 | 설정 변경 불가로 안전 |
| **위치** | `lib/registry/components/` | `components/order/` |

### 범용 컴포넌트 (화면 편집기용)

```tsx
// ❌ 수주 등록에서 사용 금지
<AutocompleteSearchInputComponent
  tableName="???"  // ConfigPanel에서 변경 가능
  displayField="???"  // 다른 테이블로 바꿀 수 있음
  valueField="???"  // 필드가 맞지 않으면 에러
/>
```

**문제점:**
- 사용자가 `tableName`을 `item_info`로 변경하면 거래처가 아닌 품목이 조회됨
- `valueField`를 변경하면 `formData.customerCode`에 잘못된 값 저장
- 수주 로직이 깨짐

### 전용 컴포넌트 (수주 등록용)

```tsx
// ✅ 수주 등록에서 사용
<OrderCustomerSearch
  value={customerCode}  // 외부에서 제어 가능
  onChange={handleChange}  // 값 변경만 처리
  // 나머지 설정은 내부에서 고정
/>
```

**장점:**
- 설정이 하드코딩되어 있어 변경 불가
- 수주 등록 로직에 최적화
- 안전하고 예측 가능

---

## API 엔드포인트

### 거래처 검색

```
GET /api/entity-search/customer_mng
Query Parameters:
  - searchText: 검색어
  - searchFields: customer_name,customer_code,business_number
  - page: 페이지 번호
  - limit: 페이지 크기
```

### 품목 검색

```
GET /api/entity-search/item_info
Query Parameters:
  - searchText: 검색어
  - searchFields: item_name,id,item_number
  - page: 페이지 번호
  - limit: 페이지 크기
```

### 수주 등록

```
POST /api/orders
Body:
{
  inputMode: "customer_first" | "quotation" | "unit_price",
  customerCode: string,
  deliveryDate?: string,
  items: Array<{
    id: string,
    item_name: string,
    quantity: number,
    selling_price: number,
    amount: number,
    delivery_date?: string,
    note?: string
  }>,
  memo?: string
}

Response:
{
  success: boolean,
  data?: {
    orderNumber: string,
    orderId: number
  },
  message?: string
}
```

---

## 멀티테넌시 (Multi-Tenancy)

모든 API 호출은 자동으로 `company_code` 필터링이 적용됩니다.

- 거래처 검색: 현재 로그인한 사용자의 회사에 속한 거래처만 조회
- 품목 검색: 현재 로그인한 사용자의 회사에 속한 품목만 조회
- 수주 등록: 자동으로 현재 사용자의 `company_code` 추가

---

## 트러블슈팅

### 1. 거래처가 검색되지 않음

**원인**: `customer_mng` 테이블에 데이터가 없거나 `company_code`가 다름

**해결**:
```sql
-- 거래처 데이터 확인
SELECT * FROM customer_mng WHERE company_code = 'YOUR_COMPANY_CODE';
```

### 2. 품목이 검색되지 않음

**원인**: `item_info` 테이블에 데이터가 없거나 `company_code`가 다름

**해결**:
```sql
-- 품목 데이터 확인
SELECT * FROM item_info WHERE company_code = 'YOUR_COMPANY_CODE';
```

### 3. 수주 등록 실패

**원인**: 필수 필드 누락 또는 백엔드 API 오류

**해결**:
1. 브라우저 개발자 도구 콘솔 확인
2. 네트워크 탭에서 API 응답 확인
3. 백엔드 로그 확인

---

## 개발 참고 사항

### 새로운 전용 컴포넌트 추가 시

1. **범용 컴포넌트 활용**: 기존 범용 컴포넌트를 래핑
2. **설정 고정**: 비즈니스 로직에 필요한 설정을 하드코딩
3. **Props 최소화**: 외부에서 제어 가능한 최소한의 prop만 노출
4. **문서 작성**: README에 사용법 및 고정 설정 명시

### 예시: 견적 등록 전용 컴포넌트

```tsx
// QuotationCustomerSearch.tsx
export function QuotationCustomerSearch({ value, onChange }: Props) {
  return (
    <AutocompleteSearchInputComponent
      tableName="customer_mng"  // 고정
      displayField="customer_name"  // 고정
      valueField="customer_code"  // 고정
      value={value}
      onChange={onChange}
    />
  );
}
```

---

## 관련 파일

- 범용 컴포넌트:
  - `lib/registry/components/autocomplete-search-input/`
  - `lib/registry/components/entity-search-input/`
  - `lib/registry/components/modal-repeater-table/`

- 백엔드 API:
  - `backend-node/src/controllers/entitySearchController.ts`
  - `backend-node/src/controllers/orderController.ts`

- 계획서:
  - `수주등록_화면_개발_계획서.md`