From dfb406d304e3a21de1060cbd20c08974e973b920 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Sun, 22 Mar 2026 19:54:07 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[system]=20SAM=20=EC=BD=94=EB=93=9C=20?= =?UTF-8?q?=EC=B2=B4=EA=B3=84=20=EC=A2=85=ED=95=A9=20=EA=B4=80=EB=A6=AC=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=9E=91=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 문서번호 15종 (견적/수주/매출/매입/입고/출고 등) 레거시+채번규칙 형식 정리 - 품목코드 체계 (FG/PT/SM/RM/CS + 절곡 BD-XX 2계층) - LOT 번호 체계 (절곡 재공품 + 일반 재고) - 시스템 코드 (테넌트 코드) - 코드 위치 맵 및 관리 포인트 체크리스트 --- INDEX.md | 2 + system/code-system-master.md | 242 +++++++++++++++++++++++++++++++++++ 2 files changed, 244 insertions(+) create mode 100644 system/code-system-master.md diff --git a/INDEX.md b/INDEX.md index f991b9f..b3c6df3 100644 --- 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 도메인별: diff --git a/system/code-system-master.md b/system/code-system-master.md new file mode 100644 index 0000000..4be2840 --- /dev/null +++ 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