SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
261277871cdbcb73473c66a289a5c264afb2d8a3
sam-docs/system/code-system-master.md
김보곤 dfb406d304 docs: [system] SAM 코드 체계 종합 관리 문서 작성 
- 문서번호 15종 (견적/수주/매출/매입/입고/출고 등) 레거시+채번규칙 형식 정리
- 품목코드 체계 (FG/PT/SM/RM/CS + 절곡 BD-XX 2계층)
- LOT 번호 체계 (절곡 재공품 + 일반 재고)
- 시스템 코드 (테넌트 코드)
- 코드 위치 맵 및 관리 포인트 체크리스트
2026-03-22 19:54:07 +09:00

243 lines
9.2 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink