# SAM 코드 체계 종합 관리 문서

> **작성일**: 2026-03-22
> **상태**: 운영 중
> **최종 갱신**: 2026-03-22

---

## 1. 개요

SAM에서 사용하는 모든 코드·번호 체계를 하나의 문서로 관리한다. 품목코드, 문서번호, LOT번호, 테넌트코드 등 시스템 전반의 채번 규칙을 총괄한다.

### 1.1 코드 분류 체계

| 분류 | 대상 | 관리 방식 |
|------|------|----------|
| **문서 번호** | 견적, 수주, 매출, 매입, 입고, 출고 등 | NumberingService + 레거시 폴백 |
| **품목 코드** | 완제품, 부품, 원자재, 절곡품 등 | 유형별 고유 규칙 |
| **LOT 번호** | 재공품, 원자재 LOT | 절곡 전용 규칙 + 일반 입고 |
| **시스템 코드** | 테넌트, 결재, 품질검사 등 | 서비스별 자체 생성 |

### 1.2 아키텍처

채번 시스템은 **2계층**으로 동작한다:

```
┌─────────────────────────────────┐
│  NumberingService (채번규칙)     │ ← MNG 관리 메뉴에서 설정
│  numbering_rules + sequences    │
└───────────┬─────────────────────┘
            │ 규칙 있으면 사용
            ▼
┌─────────────────────────────────┐
│  각 서비스별 레거시 로직          │ ← 규칙 미설정 시 폴백
│  QuoteNumberService, OrderService│
└─────────────────────────────────┘
```

---

## 2. 채번규칙 시스템 (NumberingService)

> **상세**: `rules/numbering-rules.md`
> **MNG 관리**: `admin.codebridge-x.com/numbering-rules`

### 2.1 데이터 모델

| 테이블 | 용도 | 핵심 |
|--------|------|------|
| `numbering_rules` | 규칙 정의 | tenant_id + document_type (UNIQUE) |
| `numbering_sequences` | 시퀀스 카운터 | Atomic UPSERT로 동시성 안전 |

### 2.2 지원 문서유형

| document_type | 한글명 | 사용 서비스 |
|---------------|--------|------------|
| `quote` | 견적 | QuoteNumberService |
| `order` | 수주 | OrderService |
| `sale` | 매출 | SaleService |
| `work_order` | 작업지시 | WorkOrderService |
| `material_receipt` | 원자재수입검사 | ReceivingService |
| `stock_production` | 재고생산 | BendingCodeService |

### 2.3 패턴 세그먼트 유형 (6가지)

| 유형 | 설명 | 예시 |
|------|------|------|
| `static` | 고정 문자열 | `"KD"`, `"PR"` |
| `separator` | 구분자 | `"-"`, `"/"` |
| `date` | 날짜 포맷 | `ymd`→260322, `Ymd`→20260322 |
| `param` | 외부 파라미터 | `pair_code`→SS |
| `mapping` | 값→코드 변환 | SCREEN→SC, BLIND→BL |
| `sequence` | 자동 순번 | 01, 02, ... (padding 적용) |

### 2.4 리셋 주기

| 주기 | period_key | 동작 |
|------|-----------|------|
| `daily` | YYMMDD | 매일 01부터 |
| `monthly` | YYYYMM | 매월 01부터 |
| `yearly` | YYYY | 매년 01부터 |
| `never` | all | 리셋 없음 |

---

## 3. 문서 번호 체계

### 3.1 채번규칙 미사용 시 (레거시 기본 형식)

| 문서 | 접두사 | 형식 | 리셋 | 서비스 파일 |
|------|:------:|------|:----:|-----------|
| 견적 | QT | `QT{YYYYMMDD}{NNNN}` | 일 | `Services/Quote/QuoteNumberService.php` |
| 수주 | ORD | `ORD{YYYYMMDD}{NNNN}` | 일 | `Services/OrderService.php` |
| 재고생산 | STK | `STK{YYYYMMDD}{NNNN}` | 일 | `Services/OrderService.php` |
| 작업지시 | WO | `WO{YYYYMMDD}{NNNN}` | 일 | `Services/WorkOrderService.php` |
| 매출 | SL | `SL{YYYYMMDD}{NNNN}` | 일 | `Services/SaleService.php` |
| 매입 | PU | `PU{YYYYMMDD}{NNNN}` | 일 | `Services/PurchaseService.php` |
| 입고 | RV | `RV{YYYYMMDD}{NNNN}` | 일 | `Services/ReceivingService.php` |
| 출고 | SHP | `SHP-{YYYYMMDD}-{NNNN}` | 일 | `Models/Tenants/Shipment.php` |
| 결재 | AP | `AP-{YYYYMMDD}-{NNNN}` | 일 | `Services/ApprovalService.php` |
| 부적합 | NC | `NC-{YYYYMMDD}-{NNN}` | 일 | `Services/NonconformingReportService.php` |
| 청구 | — | `{YYYYMM}{NNNN}` | 월 | `Services/BillService.php` |
| 품질검사 | KD-QD | `KD-QD-{YYYYMM}-{NNN}` | 월 | `Models/Qualitys/QualityDocument.php` |
| 견적(추정) | EST | `EST{YYYYMMDD}{NNN}` | 일 | `Models/Estimate/Estimate.php` |
| 계약 | CTR | `CTR-{YYYY}-{NNN}` | 연 | `Services/Construction/ContractService.php` |
| 입찰 | BID | `BID-{YYYY}-{NNN}` | 연 | `Services/Bidding/BiddingService.php` |
| 판매명세 | ST | `ST{매출번호}` | — | `Services/SaleService.php` |

> 모든 서비스 파일 경로 기준: `api/app/`

### 3.2 채번규칙 적용 시 (예시: tenant_id 287)

| 규칙명 | document_type | 결과 예시 |
|--------|---------------|----------|
| 5130 견적번호 | `quote` | `KD-PR-260322-01` |
| 5130 수주 로트번호 | `order` | `KD-SS-260322-01` |
| 원자재 로트번호 | `material_receipt` | `260322-01` |
| 5130 재공품 로트번호 | `stock_production` | `RM6318-30` |

> **scope_key 분리**: param/mapping 값별로 독립 시퀀스 유지. 예) pair_code=SS와 pair_code=TE는 각각 01부터 시작.

---

## 4. 품목코드 체계

### 4.1 품목 유형 코드

| 코드 | 한글 | 영문 | source_table |
|:----:|------|------|:------------:|
| `FG` | 완제품 | Finished Goods | products |
| `PT` | 부품 | Parts | products |
| `SM` | 부자재 | Sub-Materials | materials |
| `RM` | 원자재 | Raw Materials | materials |
| `CS` | 소모품 | Consumables | materials |

> **상세**: `rules/item-policy.md`

### 4.2 절곡 품목코드

> **상세**: `standards/bending-item-code-policy.md`

**2계층 구조**:

| 구분 | 구분자 | 형식 | 의미 | 예시 |
|------|:------:|------|------|------|
| 기초자료 (표준) | 없음 | `BD-{분류}` | 표준 절곡 형상 | `BD-CL` |
| 기초자료 (변형) | 점(`.`) | `BD-{분류}.{NNN}` | 주문 수정 형상 | `BD-CL.001` |
| 재공품 | 하이픈(`-`) | `BD-{분류}-{길이}` | 형상+길이 고유 품목 | `BD-CL-30` |

**분류코드** (33종): RS, RM, RC, RD, RE, RT, RH, RN, CP, CF, CB, CL, CX, BS, BE, BH, TS, TE, XE, LE, ZP, ZF, ZB 등

**서비스**: `api/app/Services/BendingItemService.php`

---

## 5. LOT 번호 체계

### 5.1 절곡 재공품 LOT

> **상세**: `rules/bending-lot-numbering-policy.md`
> **서비스**: `api/app/Services/BendingCodeService.php`

**형식**: `{제품코드}{종류코드}{날짜코드}-{길이코드}`

| 세그먼트 | 규칙 | 예시 |
|---------|------|------|
| 제품코드 | 7종: R, S, G, B, T, L, C | `G` (연기차단재) |
| 종류코드 | 제품별 상이 (R: M/T/C/D/S/W/F, G: I/H 등) | `I` (화이바원단) |
| 날짜코드 | `{년1}{월1}{일2}` (월 10~12→A~C) | `6322` (2026-03-22) |
| 길이코드 | mm÷100 2자리 | `30` (3000mm) |

**결과 예시**: `GI6322-30` = 연기차단재 + 화이바원단 + 2026-03-22 + 3000mm

> **핵심**: 일련번호 불필요 — 같은 날 같은 조합은 동일 LOT 번호

### 5.2 일반 재고 LOT

**모델**: `api/app/Models/Tenants/StockLot.php`

| 필드 | 설명 |
|------|------|
| `lot_no` | 수급처 LOT 번호 (입고 시 입력) |
| `supplier_lot` | 공급자 LOT 번호 |
| `receipt_date` | 입고일 |
| `fifo_order` | FIFO 순서 |

---

## 6. 시스템 코드

### 6.1 테넌트 코드

**헬퍼**: `api/app/Helpers/TenantCodeGenerator.php`

| 항목 | 규칙 |
|------|------|
| 형식 | `{초성영문3자}{36진수4자리}` |
| 예시 | `TKP0001` (테크컴퍼니) |
| 범위 | 36^4 = 1,679,616 (원형 순환) |
| 생성 시점 | 테넌트 생성 시 자동 |

---

## 7. 관리 포인트

### 7.1 코드 추가/변경 시 체크리스트

- [ ] `numbering_rules`에 document_type 추가 여부 확인
- [ ] 레거시 폴백 로직 구현 (채번규칙 미설정 시)
- [ ] NumberingService의 `generate()` 메서드 연동
- [ ] MNG 채번규칙 관리 UI에서 새 문서유형 선택 가능 확인
- [ ] 이 문서(code-system-master.md) 업데이트

### 7.2 코드 위치 맵

| 구분 | 핵심 파일 |
|------|----------|
| 채번 통합 서비스 | `api/app/Services/NumberingService.php` |
| 채번 규칙 모델 | `api/app/Models/NumberingRule.php` |
| 채번 시퀀스 모델 | `api/app/Models/NumberingSequence.php` |
| MNG 채번 관리 | `mng/app/Services/NumberingRuleService.php` |
| MNG 채번 컨트롤러 | `mng/app/Http/Controllers/Api/Admin/NumberingRuleController.php` |
| 절곡 코드 서비스 | `api/app/Services/BendingCodeService.php` |
| 절곡 품목 서비스 | `api/app/Services/BendingItemService.php` |
| 테넌트 코드 생성 | `api/app/Helpers/TenantCodeGenerator.php` |
| DB 마이그레이션 | `api/database/migrations/2026_02_07_20000*` |

---

## 관련 문서

| 문서 | 설명 |
|------|------|
| [rules/numbering-rules.md](../rules/numbering-rules.md) | 채번규칙 상세 (세그먼트, DB 구조, API) |
| [rules/bending-lot-numbering-policy.md](../rules/bending-lot-numbering-policy.md) | 절곡품 LOT 번호 정책 |
| [standards/bending-item-code-policy.md](../standards/bending-item-code-policy.md) | 절곡 품목코드 체계 |
| [rules/item-policy.md](../rules/item-policy.md) | 품목 유형 정책 |
| [features/bending/README.md](../features/bending/README.md) | 절곡 바라시 기초자료 |

---

**최종 업데이트**: 2026-03-22