# 채번규칙 (Numbering Rules)

> **상태**: 내부 서비스 (직접 API 없음)
> **최종 갱신**: 2026-02-27

---

## 1. 개요

문서 번호(견적번호, 수주번호 등)를 규칙 기반으로 자동 생성하는 내부 서비스. 테넌트별로 채번 규칙을 설정하면, 해당 규칙에 따라 일련번호가 자동 생성된다. 규칙이 없는 경우 레거시 포맷으로 폴백.

**핵심 기능:**
- 유연한 패턴 기반 번호 생성 (6가지 세그먼트 유형)
- Atomic UPSERT로 동시성 안전 시퀀스 관리
- 기간별 자동 리셋 (일/월/년/무제한)
- 미리보기 기능 (DB 업데이트 없음)

---

## 2. 모델

| 모델 | 테이블 | 설명 |
|------|--------|------|
| `NumberingRule` | `numbering_rules` | 채번 규칙 정의 (document_type, pattern, reset_period) |
| `NumberingSequence` | `numbering_sequences` | 일련번호 카운터 (tenant + type + scope + period) |

**지원 문서 유형:** quote, order, sale, work_order, material_receipt

**리셋 주기:** daily, monthly, yearly, never

---

## 3. 패턴 구조

패턴은 JSON 배열로 세그먼트를 정의한다.

| 세그먼트 | 설명 | 예시 |
|---------|------|------|
| `static` | 고정 문자열 | `{ "type": "static", "value": "QT" }` |
| `date` | 날짜 포맷 | `{ "type": "date", "format": "ymd" }` → `260227` |
| `sequence` | 일련번호 | `{ "type": "sequence", "padding": 4 }` → `0001` |
| `separator` | 구분자 | `{ "type": "separator", "value": "-" }` |
| `param` | 외부 파라미터 | `{ "type": "param", "key": "product_category" }` |
| `mapping` | 값 매핑 | `{ "type": "mapping", "key": "category", "map": {"A": "PR"} }` |

**패턴 예시:**
```json
[
  { "type": "static", "value": "KD" },
  { "type": "separator", "value": "-" },
  { "type": "mapping", "key": "category", "map": { "A": "PR" }, "default": "XX" },
  { "type": "separator", "value": "-" },
  { "type": "date", "format": "ymd" },
  { "type": "separator", "value": "-" },
  { "type": "sequence", "padding": 2 }
]
```
→ `KD-PR-260227-01`

---

## 4. 서비스

| 서비스 | 메서드 | 설명 |
|--------|--------|------|
| `NumberingService` | `generate($documentType, $params)` | 번호 생성 (규칙 없으면 null → 레거시 폴백) |
| | `preview($documentType, $params)` | 미리보기 (시퀀스 증가 없음) |
| `QuoteNumberService` | `generate()` | 견적번호 생성 (NumberingService → 레거시 폴백) |
| | `validate()` | 형식 검증 |
| | `isUnique()` | 중복 체크 |

**레거시 포맷:** `QT{YYYYMMDD}{NNNN}` (예: `QT202602270001`)

---

## 5. 동시성 처리

```sql
INSERT INTO numbering_sequences (tenant_id, document_type, scope_key, period_key, last_sequence)
VALUES (?, ?, ?, ?, 1)
ON DUPLICATE KEY UPDATE last_sequence = last_sequence + 1
```

MySQL의 `UPSERT`를 사용하여 동시 요청에서도 시퀀스 충돌 없이 안전하게 번호 생성.

---

## 6. 호출 위치

직접 API 엔드포인트는 없으며, 아래 서비스에서 내부 호출된다:

| 서비스 | 용도 |
|--------|------|
| `QuoteNumberService` | 견적번호 생성 |
| `OrderService` | 수주번호 생성 |
| `WorkOrderService` | 작업지시번호 생성 |
| `MaterialReceiptService` | 입고번호 생성 |

---

## 관련 문서

- [DB 스키마 — 공통](../system/database/commons.md)
- [품목 정책](item-policy.md) — 품목 코드 체계

---

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