docs: [system] SAM 코드 체계 종합 관리 문서 작성

- 문서번호 15종 (견적/수주/매출/매입/입고/출고 등) 레거시+채번규칙 형식 정리 - 품목코드 체계 (FG/PT/SM/RM/CS + 절곡 BD-XX 2계층) - LOT 번호 체계 (절곡 재공품 + 일반 재고) - 시스템 코드 (테넌트 코드) - 코드 위치 맵 및 관리 포인트 체크리스트
2026-03-22 19:54:07 +09:00
parent 50f498c87d
commit dfb406d304
2 changed files with 244 additions and 0 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -19,6 +19,7 @@
 | 이메일 정책 | `dev/standards/email-policy.md` | 멀티테넌시 이메일 발송 아키텍처 |
 | Blade+React | `dev/standards/blade-react-policy.md` | Blade JSX 이중 중괄호 충돌 방지 |
 | 이메일 연동 | `dev/guides/tenant-email-integration-guide.md` | 테넌트 메일 연동, SMTP 프리셋, MNG 관리 |
+| 코드 체계 | `system/code-system-master.md` | 문서번호·품목코드·LOT번호·채번규칙 총괄 |
 | 품목관리 | `rules/item-policy.md` | 품목 정책 |
 | BOM V2 설계 | `plans/bom-v2-universal-architecture-plan.md` | 범용 멀티테넌트 BOM V2 아키텍처 |
 | 단가관리 | `rules/pricing-policy.md` | 6 Depth 단가 체계, 흐름도, 계산공식, 버전관리 개선방향 |
@@ -126,6 +127,7 @@ docs/
 | [erp-analysis/](system/erp-analysis/) | ERP 스토리보드 분석 |
 | [api-analysis-report.md](system/api-analysis-report.md) | API 구조 분석 및 개선 로드맵 (기술 부채 8건, P1~P3) |
 | [api-code-quality-audit.md](system/api-code-quality-audit.md) | API 코드 품질 감사 — 정석 패턴 6가지 + 보안 감사 + 개발 체크리스트 |
+| [code-system-master.md](system/code-system-master.md) | 코드 체계 종합 관리 — 문서번호·품목코드·LOT번호·채번규칙 총괄 |

 DB 도메인별:

--- a/system/code-system-master.md
+++ b/system/code-system-master.md
@@ -0,0 +1,242 @@
+# 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