sam-docs/system/code-system-master.md

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} (월 1012→AC)	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	채번규칙 상세 (세그먼트, DB 구조, API)
rules/bending-lot-numbering-policy.md	절곡품 LOT 번호 정책
standards/bending-item-code-policy.md	절곡 품목코드 체계
rules/item-policy.md	품목 유형 정책
features/bending/README.md	절곡 바라시 기초자료

---

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