SamProject/sam-docs

Fork 0

Files

김보곤 93c0e2815c docs: [features] 기초자료 복사 기능 + 2차 가공물 부품 코드 표시 문서화

2026-03-21 11:56:47 +09:00

11 KiB

Raw Blame History

절곡 바라시 기초자료

작성일: 2026-03-21 상태: 운영 중

1. 개요

1.1 목적

절곡 바라시 기초자료는 원자재(SUS, EGI 등)를 절곡(바라시) 가공하여 만드는 1차 가공물(부품)의 형상을 정의하는 마스터 데이터이다.

1.2 2계층 생산 구조

원자재 (SUS 1.2T, EGI 1.55T 등)
    ↓ 절곡 가공 (바라시)
1차 가공물: bending_items (기초자료) — 절곡 형상 정의
    ↓ 조립
2차 가공물: bending_models (가이드레일/케이스/하단마감재) — 부품을 조합한 완성품

기초자료 = 1차 가공물 = 절곡 형상 (길이 무관)
가이드레일/케이스 = 2차 가공물 = 1차 가공물을 조립한 형상

1.3 재공품(WIP)과의 관계

재공품은 유휴 시간을 활용하여 가장 많이 나가는 정형화된 부품을 미리 생산하는 것이다.

모든 절곡 형상을 재공품으로 관리하는 것이 아님
수요가 높은 표준 형상만 재공품 코드로 관리
기초자료는 표준 형상 + 주문에 따른 변형 형상도 관리

2. 품목코드 체계

2.1 기초자료 코드 (형상 정의, 길이 무관)

BD-{분류코드}.{변형번호}

세그먼트	설명	예시
`BD`	Bending 접두사 (고정)	`BD`
분류코드	부품 종류 + 재질 계열 (2자리)	`CL`, `RS`, `CP`
`.nnn`	변형 번호 (점 구분자, 3자리)	`.001`, `.027`

규칙:

.001 = 대표(표준) 형상 — 재공품의 기준이 되는 절곡도
.002~ = 표준 대비 변형 — 주문에 따라 수정된 절곡도
최대 .999 (999종 변형 수용)

예시:

BD-CL.001   케이스 린텔 — 대표(표준) 형상
BD-CL.002   케이스 린텔 — 변형 1
BD-RS.001   가이드레일 SUS 마감재 — 대표(표준)
BD-RS.025   가이드레일 SUS 마감재 — 변형 25

2.2 재공품 코드 (형상 + 길이, 고유 품목)

BD-{분류코드}-{길이코드}

세그먼트	설명	예시
`BD`	Bending 접두사 (기초자료와 공통)	`BD`
분류코드	기초자료와 동일 (2자리)	`CL`, `RS`
`-길이코드`	원자재 길이 (하이픈 구분자)	`-30` (3000mm)

예시:

BD-CL-30    케이스 린텔 3000mm (고유 품목코드)
BD-RS-24    가이드레일 SUS 마감재 2438mm

2.3 기초자료 vs 재공품 코드 구분

구분	형식	구분자	의미
기초자료 (표준)	`BD-CL.001`	점 (`.`)	절곡 형상만 (길이 무관)
기초자료 (변형)	`BD-CL.002`	점 (`.`)	주문 수정 형상
재공품	`BD-CL-30`	하이픈 (`-`)	표준 형상 + 길이 (고유 품목)

BD-CL까지 공통, 그 뒤 구분자(. vs -)로 구분. 기초자료는 길이 정보를 담지 않는다.

2.4 LOT 번호

{제품}{종류}{날짜코드}-{길이코드}

예시	의미
`CL6318-30`	케이스 린텔, 2026-03-18 생산, 3000mm

LOT 번호는 생산 이력 추적용이며, 품목코드/기초자료 코드와는 별개 체계이다.

3. 분류코드 접두사 정의

3.1 가이드레일 부품 (R 계열)

코드	부품명	주재질
`RS`	SUS 마감재	SUS 1.2T
`RM`	본체/보강	EGI 1.55T
`RC`	C형	EGI 1.55T
`RD`	D형	EGI 1.55T
`RE`	측면 마감재	EGI/SUS
`RT`	절단판	—
`RH`	뒷보강	—
`RN`	비인정	—

3.2 케이스 부품 (C 계열)

코드	부품명	주재질
`CP`	밑면판/점검구	EGI 1.55T
`CF`	전면판	EGI 1.55T
`CB`	후면 코너/후면부	EGI 1.55T
`CL`	린텔	EGI 1.55T
`CX`	상부 덮개	EGI 1.55T

3.3 하단마감재 부품 (B/T 계열)

코드	부품명	주재질
`BS`	하장바 SUS	SUS 1.5T
`BE`	하장바 EGI	EGI 1.55T
`BH`	보강평철	EGI 1.15T
`TS`	철재 하장바 SUS	SUS
`TE`	철재 하장바 EGI	EGI

3.4 기타

코드	부품명
`XE`	마구리
`LE`	L-BAR
`ZP`	특수 밑면/점검구
`ZF`	특수 전면판
`ZB`	특수 후면

4. 데이터 모델

4.1 테이블

테이블	역할	프로젝트
`bending_items`	1차 가공물 (부품 형상)	API
`bending_models`	2차 가공물 (조립품)	API

4.2 bending_items 주요 필드

필드	설명
`code`	품목코드 (고유, `BD-XX.nnn`)
`item_name`	부품명
`item_sep`	대분류 (스크린/철재)
`item_bending`	분류 (가이드레일/케이스/하단마감재/마구리)
`material`	원자재 (SUS 1.2T, EGI 1.55T 등)
`bending_data`	전개도 JSON `[{input, rate, sum, color, aAngle}]`
`legacy_code`	이전 코드 (마이그레이션 이력 보존)

4.3 2차 가공물 매핑

bending_models.components JSON 배열에서 sam_item_id로 bending_items.id를 참조한다.

가이드레일 KSS01 (GR-3)
├── BD-RS.001 (SUS 마감재, 수량2)
├── BD-RM.001 (본체)
├── BD-RC.001 (C형)
└── BD-RD.001 (D형)

5. MNG 화면 기능

5.1 메뉴 구조

절곡품 관리
├── 기초관리          ← 이 문서의 대상
├── 가이드레일
├── 케이스
└── 하단마감재

5.2 기초관리 CRUD

기능	설명
목록	대분류/분류/재질/인정여부 필터, 검색, 페이지네이션
등록	분류코드 드롭다운 선택 → 순번(`.nnn`) 자동 채번
조회	코드/기본정보/전개도/이미지 표시
수정	코드 편집 가능 (저장 시 중복 검사)
복사	현재 항목을 복제 — 코드 자동 채번 + 이미지 복사
삭제	Soft delete

5.3 코드 관련 동작

등록 시

분류코드 드롭다운에서 BD-XX 선택
저장 시 API가 해당 분류의 마지막 번호 +1 자동 채번
결과: BD-CL.028 (CL 분류에 .027까지 있었다면)

수정 시

코드 필드 편집 가능
저장 시 API가 변경된 코드의 중복 검사 수행
중복이면 422 에러 + "코드 'BD-XX.nnn'는 이미 사용 중입니다" 메시지
중복 아니면 정상 저장

코드 변경 불가 케이스

같은 코드 유지 → 중복 검사 건너뜀
자기 자신은 중복에서 제외

복사 시

수정/조회 화면에서 복사 버튼 클릭
확인 다이얼로그 후 API 호출 (POST /api/v1/bending-items/{id}/duplicate)
같은 분류코드의 다음 번호 자동 채번 (예: .027까지 있으면 → .028)
R2 이미지 파일도 함께 복사 (R2 내 파일 복사 + 새 File 레코드 생성)
복사 완료 후 새 항목의 수정 화면으로 자동 이동
"복사 완료 — 새 코드: BD-CL.028" 성공 메시지 표시

복사되는 항목:

기본정보 (품명, 대분류, 분류, 재질, 규격 등)
전개도 데이터 (bending_data JSON)
options (검색어, 메모 등)
전개도 이미지 (R2 파일 복사)

5.4 2차 가공물 부품 코드 표시

가이드레일/케이스/하단마감재 상세 화면의 '절곡 부품 조합' 섹션에 각 부품의 기초자료 품목코드가 표시된다.

순서:1  BD-RS.011  1번(마감제)      재질: SUS 1.2T  수량: 2
순서:2  BD-RM.009  2번(본체)        재질: EGI 1.55T
순서:3  BD-RC.005  3번(벽면형-C)    재질: EGI 1.55T
순서:4  BD-RD.004  4번(벽면형-D)    재질: EGI 1.55T

components[].sam_item_id → bending_items.id → bending_items.code 매핑
API Resource에서 item_code 필드로 자동 주입
조회/수정 모드 모두 회색 배지로 표시

6. API 엔드포인트

Method	Path	설명	화이트리스트
GET	`/api/v1/bending-items`	목록 (페이지네이션)	필수
GET	`/api/v1/bending-items/filters`	필터 옵션	필수
GET	`/api/v1/bending-items/prefixes`	분류코드 접두사 목록	필수
POST	`/api/v1/bending-items`	등록 (자동 채번)	필수
GET	`/api/v1/bending-items/{id}`	상세 조회	필수
PUT	`/api/v1/bending-items/{id}`	수정 (코드 중복 검사)	필수
POST	`/api/v1/bending-items/{id}/duplicate`	복사 (자동 채번 + 이미지 복사)	필수
DELETE	`/api/v1/bending-items/{id}`	삭제	필수

화이트리스트: ApiKeyMiddleware의 allowWithoutAuth에 등록 필요 (Bearer 토큰 없이 API Key + X-TENANT-ID로 접근)

7. MNG→API 통신 규칙

7.1 Docker 환경 (로컬)

$baseUrl = config('services.api.internal_url'); // https://nginx
$headers['Host'] = 'api.sam.kr';                // nginx 서버 블록 라우팅

7.2 서버 환경 (개발/운영)

$baseUrl = config('services.api.base_url');     // https://api.dev.codebridge-x.com
// Host 헤더 불필요

7.3 이미지 표시

용도	라우트	방식
일반 `<img>` 표시	`/files/{id}/view`	R2 presigned URL로 redirect
Canvas 편집기	`/files/{id}/proxy`	MNG 서버가 R2에서 다운로드 후 스트리밍 (CORS 우회)

8. 마이그레이션 이력

날짜	작업
2026-03-21 (1차)	기존 코드(날짜 포함 LOT 형식) → `BD-XX-nn` 변환 (265건)
2026-03-21 (2차)	`BD-XX-nn` → `BD-XX.nn` 변환 (재공품과 구분자 분리)
2026-03-21 (3차)	`BD-XX.nn` → `BD-XX.nnn` 3자리 변형번호 (999종 수용)
2026-03-21 (4차)	순번 없는 항목 → `.001` 통일 (대표 번호)

❌ CX250722-06   (날짜 포함) — LOT 번호와 혼동
❌ BD-CX-06      (하이픈) — 재공품 BD-CX-30과 혼동
❌ BD-CX.06      (2자리) — 변형 수용량 99종 한계
✅ BD-CX.006     (점 + 3자리) — 변형 999종, 재공품과 구분 명확

기존 코드는 legacy_code 필드에 보존되어 있다.

11 KiB Raw Blame History