# RPS PLM 시스템 사용자 매뉴얼

영업·개발·구매·생산·품질·CS·ECR 전 업무 + Amaranth(ERP) 결재 연계

버전: v1.0 대상: 일반 사용자 / 관리자 최종 갱신: 2026-05-15

## 1. 시스템 개요

RPS PLM 은 영업(견적·수주)부터 개발(E-BOM), 구매(발주·입고), 생산(M-BOM·실적), 품질(수입·공정·반제품·CS·ECR), 매출까지 전사 업무를 단일 시스템으로 처리합니다. 회계·결재·인사 등 ERP 영역은 Wehago/Amaranth 와 REST API 로 연계됩니다.

11
주요 모듈
40+
화면 메뉴
7
Amaranth 커넥션
3
모니터링 보드

### 시스템 구성

레이어 | 기술 | 역할
--- | --- | ---
프론트엔드 | Next.js 15 + React + Tailwind | 탭 기반 SPA, DataGrid, 그리드 차트/엑셀
백엔드 | Node.js + Express + TypeScript | REST API, JWT 인증, 외부 ERP 프록시
데이터베이스 | PostgreSQL 15 | 업무 데이터 + 메뉴/권한 메타
외부 ERP | Wehago / Amaranth | 전자결재, 인사, 거래처, 계정과목 마스터
인증 | JWT + Refresh Token | 로그인 세션, 401 자동 갱신

## 2. 전체 메뉴 구조

#### 📋 영업관리

- 견적관리 — 견적 작성·승인·메일발송
- 주문서관리 — 수주 등록·확정
- 판매관리 — 출하 처리
- 매출관리 — 세금계산서 발행

#### 📁 프로젝트관리

- 제품구분_WBS관리 — 제품별 WBS 템플릿
- 진행관리 — 프로젝트 단계별 진척률

#### 🛠 개발관리

- PART 등록·조회
- E-BOM 등록·조회
- 설계변경 리스트

#### 🛒 구매관리

- M-BOM 관리
- 구매리스트 / 견적요청서 / 품의서 / 발주서
- 입고관리 (3가지 뷰)
- 프로젝트별 발주/입고 현황

#### 📦 자재관리

- 자재리스트
- 불출의뢰서

#### 🏭 생산관리

- M-BOM 관리
- 생산계획&실적 (일반/장비)
- 반제품·원자재 소요량

#### 🔬 품질관리

- 수입검사 요청·관리
- 공정검사 관리
- 반제품검사 관리

#### 💬 고객CS관리

- 고객CS관리 — 민원 접수·조치

#### 📝 ECR관리

- ECR관리 — 설계변경요청서

#### 📊 모니터링

- 품질 모니터링
- 생산 모니터링
- 설비 모니터링

## 3. 업무 프로세스 흐름

각 모듈의 작업 결과는 다음 모듈의 입력이 되어 자동으로 흘러갑니다. 한 화면에서 다른 화면으로 물려 있는 점이 RPS PLM의 핵심입니다.

견적 작성
→
결재상신 (Amaranth)
→
수주 확정
→
M-BOM 생성
→
발주서
→
입고·수입검사
→
생산실적
→
공정·반제품 검사
→
출하
→
매출·세금계산서 (Amaranth)

### 3.1 영업·수주

#### 핵심 시나리오

1. 견적요청 등록 — 영업관리 > 견적관리 [+ 견적요청등록]. 주문유형/고객사/유무상/접수일/품목 입력.
2. 견적작성 — 행 선택 후 [견적작성]. 일반/장비 템플릿 중 선택 → 신규 차수 생성.
3. 결재상신 — 견적서가 작성된 행에서 [결재상신] → Amaranth 팝업 → 결재완료까지 대기.
4. 수주 확정 — 결재완료 시 자동으로 contract_result 가 변경되어 주문서관리에 노출됨.

⚠ 가드 조건 ① 견적서 미작성 → 결재상신 불가 ② 결재중·결재완료 건은 재상신 차단 ③ 수주확정(0000964/0000968) 행은 품목 추가/삭제 불가

### 3.2 개발·설계

제품 양산 전 단계의 부품(PART)과 설계 BOM(E-BOM)을 관리합니다. 설계변경(ECR)이 발생하면 E-BOM 의 차수가 올라가고, 변경 이력은 [설계변경 리스트]에서 추적됩니다.

PART 등록
→
E-BOM 트리 구성
→
ECR 발의
→
E-BOM 차수 업데이트

### 3.3 구매·입고

수주 → M-BOM 분해 → 구매리스트 → 견적요청서 → 품의서(승인) → 발주서 → 입고 → 수입검사 순서로 진행됩니다. Amaranth 와는 거래처/계정과목 마스터를 실시간 동기화합니다.

단계 | 메뉴 | 핵심 동작
--- | --- | ---
1. 구매대상 추출 | 구매리스트관리 | 수주 M-BOM 에서 외주/구매 품목만 필터링
2. 견적요청 | 견적요청서관리 | 거래처별 RFQ 발송 (Amaranth 거래처 조회 연동)
3. 품의 → 결재 | 품의서관리 | 구매 품의서 작성 후 Amaranth 결재 (formId=품의서)
4. 발주 | 발주서관리 | 결재완료된 품의서를 발주로 전환
5. 입고 | 입고관리 (3가지 뷰) | 전체/품목별/입고일별 입고 확정
6. 수입검사 | 품질관리 > 수입검사 | 입고된 자재의 검사 진행 + 합/불 판정

### 3.4 생산

M-BOM 으로 생산계획을 수립하고 작업지시번호 단위로 실적을 입력합니다. 장비 생산은 별도 메뉴(생산계획&실적관리(장비))에서 처리합니다.

- M-BOM 관리 — 구조 트리 + 본 편집(품목 추가/삭제) + 변경이력
- 반제품/원자재 소요량 — 계획 대비 필요 자재 자동 계산
- 생산실적 — 작업지시 단위 양품/불량 등록 (반제품검사와 inspection_group_id 로 연계)

### 3.5 품질

품질관리는 4단계로 흐릅니다:

수입검사 요청 (발주서 단위)
→
수입검사 진행 (검사자 판정)
→
공정검사 (작업 중 SPC)
→
반제품검사 (양품/불량 분류)

불량 발생 → 책임부서로 통보 → 수정완료 시 재생수량 가산 → 최종양품수량 자동 산정. 자세한 내용은 6. 품질관리 메뉴 가이드.

### 3.6 매출·CS

출하 완료 → 매출 인식 → Amaranth 로 세금계산서 발행. 고객 클레임은 CS 메뉴로 접수되어 분석/조치 후 종결됩니다.

판매관리 (출하)
→
매출관리
→
세금계산서 발행 (Amaranth)
→
CS 접수 (필요 시)
→
ECR (설계 반영 필요 시)

## 4. Amaranth(ERP) 연계

RPS PLM 은 결재·인사·거래처 등 ERP 영역을 Wehago/Amaranth 시스템과 REST API 로 통합합니다. 모든 외부 호출 정보는 [관리자 > 자동화 관리 > 외부 커넥션 관리] 에 등록되어 있고, 자격 증명(accessToken/hashKey)은 AES-256-GCM 으로 암호화 저장됩니다.

### 4.1 외부 커넥션 관리 — 한눈에 보기

위치: `관리자 > 자동화 관리 > 외부 커넥션 관리`

외부 시스템(ERP / 마스터 / 공공 API) 과의 모든 연결을 한 곳에서 관리합니다. 두 종류의 탭이 있습니다:

    ┌────────────────────────────────────────────────────────────────────────────┐
    │  외부 커넥션 관리   외부 데이터베이스 및 REST API 연결 정보를 관리합니다.   │
    ├────────────────────────────────────────────────────────────────────────────┤
    │  [🗄 데이터베이스 연결]  [🌐 REST API 연결]  ← 탭 전환                       │
    │                                                                            │
    │  🔍 [연결명 또는 URL로 검색...]  [전체 ▾]  [전체 ▾]   총 7건   [+ 새 연결] │
    ├──────────────────────┬─────────────┬──────────────────────┬────────────────┤
    │ 연결명               │ 회사         │ 기본 URL              │ 상태   테스트  │
    ├──────────────────────┼─────────────┼──────────────────────┼────────────────┤
    │ Amaranth - 계정과목   │ COMPANY_16  │ https://erp.rps...    │ 활성   [테스트] │
    │ Amaranth - 부서       │ COMPANY_16  │ https://erp.rps...    │ 활성   [테스트] │
    │ Amaranth - 거래처     │ COMPANY_16  │ https://erp.rps...    │ 활성   [테스트] │
    │ Amaranth - 결재       │ COMPANY_16  │ https://erp.rps...    │ 활성   [테스트] │
    └──────────────────────┴─────────────┴──────────────────────┴────────────────┘

각 행의 [테스트] 버튼을 누르면 실제 호출이 발생하고 성공 / 실패 로 즉시 결과가 표시됩니다.

#### 등록된 Amaranth 커넥션 (운영 기준 7종)

연결명 | 엔드포인트 path | 용도
--- | --- | ---
Amaranth - 결재 | `(SSO/결재 호출 시 path 지정)` | 전자결재 SSO URL 발급, 결재함 조회
Amaranth - Wehago 사용자 | `/apiproxy/api99u01A11` | 사용자 인증 토큰 발급
Amaranth - 거래처 | `/apiproxy/api16S11` | 거래처 마스터 동기화
Amaranth - 부서 | `/apiproxy/api16S10` | 부서 마스터 동기화
Amaranth - 사원 | `/apiproxy/api16S05` | 사원 마스터 동기화
Amaranth - 창고 | `/apiproxy/api20A00S00801` | 창고 마스터 동기화
Amaranth - 계정과목 | `/apiproxy/api11A02` | 계정과목 마스터 동기화

### 4.2 REST API 신규 등록 가이드 (URL + 키만 입력하면 끝)

외부 시스템과 새로 연동할 때 코드 수정 없이 UI에서 URL/인증 키만 입력하면 RPS PLM 어디서든 호출할 수 있습니다. Amaranth 외에 ITS 교통정보, 기상특보, 환율, 자체 백오피스 API 등도 동일하게 등록 가능합니다.

#### STEP 1 · [+ 새 연결] 버튼 클릭 → 등록 모달 오픈

    ┌──────────────────────────────────────────────────────┐
    │  REST API 연결 등록                              [X] │
    ├──────────────────────────────────────────────────────┤
    │  ▶ 기본 정보                                          │
    │    연결명 *        [Amaranth - 사원_____________]     │
    │    설명           [api16S05 — 사원 마스터________]     │
    │    회사 코드       [COMPANY_16 ▾]                     │
    │                                                      │
    │  ▶ 엔드포인트                                         │
    │    기본 URL *      [https://erp.rps-korea.com___]     │
    │    엔드포인트 path  [/apiproxy/api16S05_________]     │
    │    HTTP 메서드     [POST ▾]   ⏱ Timeout [5000] ms    │
    │                                                      │
    │  ▶ 인증 정보                                          │
    │    인증 타입       [Wehago / Amaranth ▾]              │
    │    callerName     [API_gcmsAmaranth40578________]     │
    │    accessToken    [••••••••••••••••••••••••••••]🔒    │
    │    hashKey        [••••••••••••••••••••••••••••]🔒    │
    │    groupSeq       [gcmsAmaranth40578____________]     │
    │                                                      │
    │  ▶ 기본 헤더 / 기본 요청 본문 (JSON, 선택)             │
    │                                                      │
    │              [테스트]   [취소]   [저장]                │
    └──────────────────────────────────────────────────────┘

#### STEP 2 · 필드 작성 가이드

필드 | 설명 | 예시
--- | --- | ---
연결명 * | 유일 식별자. 백엔드가 이 이름으로 조회 (`amaranthApprovalClient`). | `Amaranth - 결재`
설명 | 운영자 참고용. 자유 입력. | "전자결재 통합 — 인증토큰/SSO/결재함"
기본 URL * | 스킴+호스트까지만. path는 별도. 끝의 / 는 자동 제거. | `https://erp.rps-korea.com`
엔드포인트 path | 고정 path. 호출 시 함수에서 override 가능. | `/apiproxy/api11A02`
HTTP 메서드 | GET / POST / PUT / DELETE. | `POST`
인증 타입 | API_KEY / BEARER / BASIC / OAUTH2 / WEHAGO_AMARANTH 중 선택. | `Wehago/Amaranth`
callerName | Wehago 발급 API 이름. 평문 저장. | `API_gcmsAmaranth40578`
accessToken | Wehago 발급 토큰. 저장 시 AES-256-GCM 자동 암호화. | `MN5Kz...` (저장 후 마스킹)
hashKey | HMAC 서명용 키. 자동 암호화. | `22519103...`
groupSeq | Wehago 그룹 시퀀스. 평문. | `gcmsAmaranth40578`

🔐 자동 암호화 `accessToken`·`hashKey`·`password`·`clientSecret` 같은 민감 필드는 저장 직전에 `iv:authTag:cipher` 3-part hex 형식으로 변환됩니다. 복호화 키는 환경변수 `DB_PASSWORD_SECRET` 이며, 코드(`amaranthApprovalClient.loadApprovalConnection`)에서 자동 복호화됩니다. 직접 평문 입력해도 자동 처리되므로 사용자가 별도로 암호화할 필요가 없습니다.

#### STEP 3 · [테스트] 버튼으로 즉시 검증

저장 전에 [테스트] 를 누르면 실제 외부 서버로 호출을 보내 응답을 표시합니다:

    ┌────────────────────────────────────────────────┐
    │  ✅ 연결 성공                                    │
    │  HTTP 200 · 응답시간 234ms                       │
    │  마지막 테스트: 2026-05-13 09:42                  │
    └────────────────────────────────────────────────┘

실패 시 응답 본문이 그대로 표시되어 토큰 오타 / IP 화이트리스트 / 시그니처 불일치를 즉시 디버그할 수 있습니다.

#### STEP 4 · 저장 후 백엔드 호출에서 활용

등록된 커넥션은 즉시 코드 어디서나 이름으로 조회 가능합니다:

    // backend-node/src/services/amaranthApprovalClient.ts
    const conn = await loadApprovalConnection();   // connection_name='Amaranth - 결재'
    // conn.baseUrl, conn.callerName, conn.accessToken(복호화됨), ...
    const url = conn.baseUrl + "/apiproxy/api99u02A01";

업무 화면이 호출하는 모든 ERP API는 이 헬퍼를 거치므로, 키가 만료되면 코드 수정 없이 외부 커넥션 관리에서 토큰만 갱신해주면 됩니다.

#### auth_config 저장 구조 (참고)

    {
      "callerName": "API_gcmsAmaranth40578",                    // 평문
      "groupSeq":   "gcmsAmaranth40578",                        // 평문
      "accessToken": "fa9c..:b3e8..:7d2a..",                    // iv:authTag:cipher
      "hashKey":     "3a91..:c2f4..:8e6b..",                    // iv:authTag:cipher
      "aesKey":      "8441e27489d402cd"                         // 결재 SSO empSeq AES-128-CBC 키
    }

### 4.3 결재상신 워크플로 (사용자 시점)

견적관리·주문서관리·품의서관리·ECR관리·CS관리 등 결재 대상 화면에서 동일한 흐름으로 작동합니다.

#### 사용자 화면 흐름

    ┌─ 견적관리 ──────────────────────────────────────────────────────────────┐
    │ [삭제] [+ 견적요청등록] [✎ 견적작성] [✈ 결재상신] [📧 메일발송] [초기화] │
    ├─────────────────────────────────────────────────────────────────────────┤
    │ ☑ 영업번호    주문유형  접수일      고객사         품명      견적현황    │
    │ ☑ 26C-0801   수리      2026-05-06  라온기술       10인치... 📁          │
    │ ☐ 26C-0800   수리      2026-04-28  에스에프에이.. 12인치... 📁          │
    └─────────────────────────────────────────────────────────────────────────┘
                  ↓ ① 견적행 1건 체크
                  ↓ ② [✈ 결재상신] 버튼 클릭
    ┌─ Sweet Alert 확인 ─────────────────────────────────────┐
    │  결재상신                                                │
    │  결재상신 하시겠습니까?                                  │
    │  * 결재완료 후 메일발송이 가능합니다.                     │
    │                                  [취소]    [결재상신 →]  │
    └────────────────────────────────────────────────────────┘
                  ↓ ③ 백엔드가 Amaranth SSO URL 발급
                  ↓ ④ 새 창 자동 오픈 (1200x900 popup)
    ┌─ Amaranth 결재 작성 화면 (외부 시스템) ────────────────┐
    │  견적서 결재 - 26C-0801                                 │
    │  ┌──────────────────────────────────────────────────┐  │
    │  │ 결재선: [부서장] → [임원] → [대표]                │  │
    │  │ 첨부:   견적서 PDF (자동 합본)                    │  │
    │  │ 본문:   기안자 코멘트 작성...                     │  │
    │  │                            [임시저장] [상신]      │  │
    │  └──────────────────────────────────────────────────┘  │
    └────────────────────────────────────────────────────────┘
                  ↓ ⑤ 사용자가 [상신] 클릭 시 Amaranth 가 PLM 으로 webhook
                  ↓ ⑥ PLM 의 amaranth_approval.status 가 inProcess 로 변경
                  ↓ ⑦ 결재완료 시 status=complete + 견적관리 그리드 "결재상태" 컬럼 갱신

#### 가드 조건 (버튼 비활성 / 토스트)

상황 | 처리
--- | ---
행 미선택 | "결재상신할 행을 선택해주십시오." 토스트
견적서 미작성 (est_objid 없음) | "견적서를 먼저 작성해주세요." 토스트 → [견적작성] 유도
이미 inProcess 상태 | "결재 진행중인 건은 상신할 수 없습니다." 토스트
complete 상태 | "결재 완료된 건은 상신할 수 없습니다." 토스트
approval_required='N' (결재불필요로 처리됨) | "결재불필요로 처리된 건입니다." 토스트
reject / delete / create | 재상신 허용 (새 approKey 발급)

#### 백엔드 내부 처리 11 단계

1. 프론트 → `POST /api/sales/estimate/:id/amaranth-approval`
2. JWT 에서 userId 추출 → `user_info.emp_seq` 조회 (없으면 401)
3. 최신 차수 `estimate_template.objid` 추출 → `target_objid`
4. `amaranth_approval` 기존 매핑 조회 (target_type + target_objid)
   - 없음 → 신규 `approKey` = `UB_` + UUID
   - status ∈ {reject, delete, create} → 재상신: 새 approKey 발급
   - 그 외 → 기존 approKey 재사용
5. [외부 커넥션 관리]에서 Amaranth - 결재 레코드 조회 + 자동 복호화
6. wehago-sign 헤더 생성 (HMAC-SHA256, transaction-id, timestamp)
7. empSeq AES-128-CBC 암호화 (KST yyyyMMddHHmmss▦empSeq)
8. SSO URL 발급 API 호출 → `fullUrl` 수신
9. `amaranth_approval` INSERT 또는 UPDATE
10. 프론트로 `{fullUrl, approKey, status}` 반환
11. 프론트가 `window.open(fullUrl, "amaranthApproval", "width=1200,height=900")`

✓ 주요 파라미터
targetType
  `CONTRACT_ESTIMATE` (견적) / `CONTRACT_ORDER` (수주) / 등
formId
  1162 (견적) / 1161 (수주) — Amaranth 양식 ID
compSeq
  1000
approvalTitle
  "견적서 결재 - 26C-0801" 같은 결재함 제목

#### 결재 상태 코드

코드 | 의미 | 가능 액션
--- | --- | ---
create | 임시 저장 (작성중) | 재상신 가능
inProcess | 결재 진행 중 | 상신 불가 (가드)
complete | 결재 완료 | 후속 처리 가능 (수주확정 등)
reject | 반려 | 수정 후 재상신
delete | 회수/삭제 | 재상신 가능
— | notRequired / N | 결재불필요 처리

### 4.3 문제 해결

Q. [결재상신] 클릭 시 "결재 시스템 연동 중 오류" 토스트가 표시됩니다.

1. [외부 커넥션 관리] 에서 Amaranth - 결재 의 [테스트] 버튼 실행
2. 실패 시 auth_config 의 accessToken/hashKey 가 만료됐을 가능성 → 운영팀 또는 Wehago 관리자에게 키 재발급 요청
3. 성공인데 결재상신이 안 되면 백엔드 로그 `docker logs rps_backend` 에서 `SSO API 응답` 확인

Q. "empSeq 정보가 없습니다" 오류가 납니다.

`user_info.emp_seq` 가 비어 있는 사용자입니다. 관리자 메뉴 [유저관리] 에서 해당 사용자의 emp_seq 를 Amaranth 사원 마스터의 값으로 채워야 합니다.

Q. 결재 후 PLM 상태가 자동 업데이트되지 않습니다.

Amaranth 측 webhook (콜백 URL) 설정이 RPS PLM 의 `/api/amaranth-approval/callback` 으로 등록돼 있어야 합니다. Wehago 관리 콘솔에서 확인 가능.

## 5. 대시보드 관리

### 5.1 사용자 대시보드

로그인 후 메인 화면(`/dashboard`)에서 보여지는 위젯형 대시보드입니다. 회사별로 위젯 구성이 다릅니다.

- 매출 추이 — 월별 매출 합계 라인 차트
- 수주 잔량 — 미출하 수주 막대 차트
- 리스크 / 알림 — 기상특보 / 교통사고 / 환율 (외부 API 자동 갱신, 10분 간격)
- To-Do — 결재 대기, 마감 임박 견적, 미입고 발주

### 5.2 모니터링 보드

보드 | 경로 | 주요 위젯
--- | --- | ---
품질 모니터링 | `/COMPANY_16/monitoring/quality` | 일별 불량률 추이, 검사자 별 처리 건, 불량 유형 Top 10
생산 모니터링 | `/COMPANY_16/monitoring/production` | 실시간 작업지시 현황, 라인별 가동률, 계획 대비 실적
설비 모니터링 | `/COMPANY_16/monitoring/equipment` | 설비별 상태(가동/정지/점검), 알람 이력

### 5.3 대시보드 관리자 기능

위치: `관리자 > 화면 관리 > 대시보드 리스트`

- 회사별 대시보드 신규 생성 / 위젯 배치 / 권한 설정
- 위젯 종류: 카드 / 라인 차트 / 막대 차트 / 파이 차트 / 그리드 / 외부 URL embed
- 저장된 대시보드는 `/dashboard/{dashboardId}` 경로로 접근

💡 그리드 → 차트 즉시 변환 모든 업무 그리드(견적관리, 매출관리, 품질관리 등)는 우상단 📊 토글로 Top-N 데이터를 막대/파이 차트로 즉시 시각화할 수 있습니다.

## 6. 화면 관리 — 사용자 정의 화면 만들기 (코딩 없이)

RPS PLM 의 가장 강력한 기능 중 하나는 관리자가 코드 수정 없이 새 업무 화면을 직접 만들 수 있다는 점입니다. 테이블 선택 → 컬럼 매핑 → 버튼 / 데이터 흐름 정의 → 저장만으로 즉시 메뉴에 노출됩니다.

### 6.1 화면 디자이너 개요

위치: `관리자 > 화면 관리 > 화면관리`

    ┌─────────────────────────────────────────────────────────────────────────┐
    │  ● 하이큐마그 영업 수주관리 화면                              #6456  [↻] │
    ├─────────────────────────────────────────────────────────────────────────┤
    │  sales_order_detail                                                      │
    │                                                                          │
    │  메인 테이블:  sales_order_detail                                        │
    │  컴포넌트:    버튼 4                                                     │
    ├──────────────────────────────────┬──────────────────────────────────────┤
    │  🗄 테이블                    1  │  ▼ 미리보기 영역                      │
    │  ┌────────────────────────────┐  │  ● 하이큐마그 영업 수주관리 화면      │
    │  │ sales_order_detail         │  │                                      │
    │  │ 메인 · 0 컬럼 사용중  [설정]│  │       ⌛ 화면 로딩 중...               │
    │  └────────────────────────────┘  │                                      │
    │                                  │                                      │
    │  🔘 버튼                      4  │                                      │
    │  [수주 등록 · MODAL · 플로우 1]  │                                      │
    │  [수정     · EDIT  · 플로우 1]  │                                      │
    │  [삭제     · DELETE          ]  │                                      │
    │  [출하계획 · OPENMODALWITHDATA] │                                      │
    │                                  │                                      │
    │  → 데이터 흐름                0  │                                      │
    │  데이터 흐름이 없어요             │                                      │
    │                                  │                                      │
    │           [↗ 화면 디자이너에서 편집]                                       │
    └──────────────────────────────────┴──────────────────────────────────────┘

화면 카드 한 장에 ① 메인 테이블 / ② 버튼 N 개 / ③ 데이터 흐름 N 개 / ④ 미리보기 가 통합되어 있어 설정 변경 즉시 결과가 우측에 표시됩니다.

### 6.2 신규 화면 만들기 — 4단계

#### STEP 1 · [+ 새 화면] 클릭 → 기본 정보 입력

    ┌──────────────────────────────────────────────────┐
    │  새 화면 만들기                              [X]  │
    ├──────────────────────────────────────────────────┤
    │  화면명 *      [영업 수주관리 화면_________]      │
    │  설명         [수주 마스터/디테일 관리_____]      │
    │  화면 코드     [SALES_ORDER_MGMT_______]          │
    │  그룹         [영업관리 ▾]                        │
    │  화면 종류     ○ 일반 화면  ● POP 화면            │
    │  메뉴 노출    ☑ 좌측 메뉴 / 권한 그룹 자동 매핑   │
    │                                                  │
    │                  [취소]  [생성]                   │
    └──────────────────────────────────────────────────┘

#### STEP 2 · 메인 테이블 매핑

[테이블] 섹션의 [설정] 버튼을 누르면 컬럼 매핑 모달이 열립니다:

    ┌─ 테이블 컬럼 매핑 ─────────────────────────────────────────┐
    │  메인 테이블: sales_order_detail                            │
    │                                                            │
    │  ☑ 사용  컬럼명          데이터타입    그리드 라벨    필터 │
    │  ──────────────────────────────────────────────────────── │
    │  ☑      objid           BIGINT       PK             —     │
    │  ☑      order_no        VARCHAR(50)  주문번호       text  │
    │  ☑      customer_objid  BIGINT       고객사         FK→client_mng │
    │  ☑      product_objid   BIGINT       제품           FK→part_mng   │
    │  ☑      quantity        NUMERIC      수량           number │
    │  ☐      writer          VARCHAR(50)  작성자(숨김)    —     │
    │  ☑      reg_date        TIMESTAMP    등록일         date  │
    │                                                            │
    │              [취소]  [저장]                                │
    └────────────────────────────────────────────────────────────┘

체크박스만 토글하면 즉시 미리보기 그리드에 컬럼이 추가/제거됩니다. FK 매핑이 잡힌 컬럼은 자동으로 select 드롭다운으로 렌더링됩니다.

#### STEP 3 · 버튼 추가 (등록 / 수정 / 삭제 / 모달 등)

버튼 타입 | 동작 | 예시
--- | --- | ---
MODAL | 등록/수정 폼 모달 오픈 | "+ 수주 등록"
EDIT | 선택 행 인라인 수정 모드 | "✎ 수정"
DELETE | 선택 행 삭제 (확인 다이얼로그) | "🗑 삭제"
OPENMODALWITHDATA | 현재 행 데이터를 다른 화면 모달에 전달 | "출하계획" → 출하 화면 자동 채움
FLOW | 데이터 흐름(워크플로) 실행 | 견적→수주 자동 전환
EXTERNAL | 외부 커넥션 호출 + 결과 매핑 | "거래처 동기화" → Amaranth API

#### STEP 4 · 저장 → 즉시 메뉴에 노출

화면 디자이너 우상단 [저장] 클릭 시:

1. `screen_definitions` 테이블에 화면 정의 INSERT
2. 좌측 [메뉴 관리]에서 자동으로 신규 메뉴 후보로 표시 → 활성화하면 즉시 사이드바 등장
3. 권한 그룹 자동 매핑 (관리자 그룹 전체 허용으로 기본 등록)
4. 다른 사용자는 새로고침(F5) 후 메뉴에서 클릭 → 새 화면 사용 시작

### 6.3 테이블 매핑 — 조인 / 다중 테이블

한 화면에 메인 1개 + 조인 테이블 N개를 함께 매핑할 수 있습니다.

    ┌─ 조인 추가 ────────────────────────────────────────────┐
    │  메인:   sales_order_detail                             │
    │           └── ON customer_objid = ?                     │
    │  조인 1: client_mng       (LEFT JOIN)                   │
    │           └── client.objid = sales.customer_objid       │
    │           └── 노출 컬럼: client_nm                       │
    │  조인 2: part_mng         (LEFT JOIN)                   │
    │           └── part.objid = sales.product_objid          │
    │           └── 노출 컬럼: part_no, part_name              │
    └─────────────────────────────────────────────────────────┘

조인된 컬럼은 자동으로 `partner_name` 같은 별칭으로 그리드에 합쳐 보입니다.

### 6.4 버튼·플로우 추가 — 클릭 시 동작 정의

버튼 카드 → [편집] → "플로우 연결" 화면에서 시각적 노드 편집기로 동작을 구성합니다:

    ┌─ 플로우 편집기 (DataFlowDesigner) ─────────────────────┐
    │                                                         │
    │   [버튼 클릭]                                            │
    │        │                                                │
    │        ▼                                                │
    │   ┌──────────────────┐                                  │
    │   │ 입력 검증         │  ← 필수 컬럼 null 체크 등         │
    │   └──────────────────┘                                  │
    │        │                                                │
    │        ▼                                                │
    │   ┌──────────────────┐                                  │
    │   │ SQL 실행          │  → INSERT INTO sales_order...   │
    │   └──────────────────┘                                  │
    │        │                                                │
    │        ▼                                                │
    │   ┌──────────────────┐                                  │
    │   │ 외부 커넥션 호출  │  → Amaranth 결재상신             │
    │   └──────────────────┘                                  │
    │        │                                                │
    │        ▼                                                │
    │   ┌──────────────────┐                                  │
    │   │ 토스트 + 새로고침 │                                  │
    │   └──────────────────┘                                  │
    └─────────────────────────────────────────────────────────┘

### 6.5 데이터 흐름 — 화면 간 자동 연계

한 화면에서 다른 화면으로 데이터를 전달할 때 사용합니다. 예시:

- 견적 → 수주 전환: 견적 행 [수주확정] 클릭 → 견적 데이터를 수주 등록 모달에 자동 채움
- 수주 → 출하계획: 수주 행 [출하계획] 버튼 → 출하 화면을 새 탭으로 열면서 contract_objid / part / qty 자동 전달
- 입고 → 수입검사 요청: 입고 확정 시 자동으로 incoming_inspection_detail INSERT

✓ 화면 디자이너의 장점
① 코드 수정 0 — 신규 메뉴 추가 시 Next.js / Node 빌드 불필요
② 즉시 반영 — 저장 즉시 모든 사용자에게 새로고침으로 노출
③ 일관된 UI — 자동으로 PageHeader + CompactFilterBar + DataGrid 패턴 적용
④ 버전 관리 — `#6456` 처럼 화면별 ID + 변경 이력 보관

## 7. 품질관리 메뉴 가이드

### 6.1 수입검사 요청

경로: `/COMPANY_16/quality/incoming-request`

발주서 단위로 입고/검사 요청 현황을 한 줄씩 보여줍니다. 검사 디테일이 아직 없으면 "미요청", 있으면 "요청중"/"요청완료".

#### 필터 (12종)

품의서 No · 발주서 No · 프로젝트번호 · 품번 · 품명 · 공급업체 · 입고결과 · 제품구분 · 검사여부 · 요청현황 · 요청자 · 요청일 범위

#### 그리드 컬럼 (12개)

품의서 No · 발주서 No · 프로젝트번호 · 제품구분 · 품번 · 품명 · 공급업체 · 입고결과 · 요청일 · 요청자 · 검사여부 · 요청현황

### 6.2 수입검사 진행

경로: `/COMPANY_16/quality/incoming-mgmt`

검사자가 실제 검사를 진행하여 합/불 판정과 불량률(검사수량 대비)을 입력하는 화면입니다.

#### 주요 컬럼 (19개)

검사일 · 검사자 · 품의서 · 발주서 · 프로젝트번호 · 제품구분 · 품명(모델명) · 부품품번 · 부품명 · 공급업체 · 입고일 · 입고수량 · 입고결과 · 검사수량 · 불량수량 · 불량률 · 검사현황 · 검사성적서(첨부파일)

불량률 = SUM(defect_qty 서브쿼리) / inspection_qty × 100, 소수점 2자리.

### 6.3 공정검사 관리

경로: `/COMPANY_16/quality/process-inspection`

작업 중 SPC 검사. 마스터 1건당 디테일 N건(검사항목)을 SUM 으로 집계하여 한 줄로 표시.

#### 필터 (10종, 2행)

- 1행: 프로젝트번호 · 제품구분 · 품번 · 품명 · 작업환경상태 · 측정기
- 2행: 검사일 범위 · 검사자 · 검사결과 · 진행공정

#### 그리드 컬럼 (9개)

검사일 · 검사자 · 프로젝트번호 · 제품구분 · 품번 · 품명 · 검사수량 합계 · 검사결과(OK/NG) · 첨부파일

### 6.4 반제품검사 관리

경로: `/COMPANY_16/quality/semi-product-inspection`

반제품 입고에 대한 양품/불량 판정. 단일 테이블(`pms_quality_semi_product_inspection`)에 양품 마스터(`DATA_TYPE='GOOD'`)와 불량 행(`'DEFECT'`)을 동일 `INSPECTION_GROUP_ID` 로 묶어 저장합니다.

#### 자동 산정 컬럼

컬럼 | 계산식
--- | ---
불량수량 합계 | 같은 group_id 의 DEFECT 행 defect_qty 합
불량률(%) | round(불량수량 / 입고수량 × 100, 2)
재생수량 합계 | DEFECT 행 중 disposition_type='수정완료' 의 defect_qty 합
최종양품수량 | good_qty + 재생수량

## 8. 공통 UI 사용법

### 7.1 데이터 그리드

모든 업무 화면의 표는 동일한 `DataGrid` 컴포넌트로 통일됩니다.

- 컬럼 드래그 — 헤더 ⋮⋮ 영역을 드래그해 컬럼 순서 변경
- 정렬 — 헤더 클릭 (asc/desc 토글)
- 필터 — 헤더 옆 깔때기 아이콘 → 고유값 체크박스 다중 선택
- 인라인 편집 — 셀 더블클릭 (편집 가능 컬럼만)
- 🔃 새로고침 / 📊 차트 / ⬇ 엑셀 다운로드 / ⚙ 컬럼 표시 설정 — 그리드 우상단 툴바
- 페이지 사이즈 — 우하단 드롭다운 (10/15/20/50/100)

### 7.2 필터바 (CompactFilterBar)

화면 상단의 검색 영역. 요청일·검사일 같은 날짜 범위는 캘린더 아이콘 클릭으로 달력 popover가 뜹니다(YYYY-MM-DD 직접 입력도 가능).

### 7.3 페이지 헤더

모든 화면 상단의 [검색] / [초기화] / 업무 액션(등록·삭제·결재상신 등)은 `PageHeader` 한 곳에 모입니다.

## 9. 자주 묻는 질문

Q. 로그인 후 좌측 메뉴가 안 보입니다.

해당 계정이 권한 그룹에 속해있지 않습니다. `관리자 > 권한 그룹 관리`에서 사용자에게 메뉴를 부여하세요.

Q. 그리드의 엑셀 다운로드가 "내보낼 데이터가 없습니다" 토스트만 나옵니다.

현재 필터로 조회된 결과가 0건이라 그렇습니다. 검색 조건을 변경한 후 다시 [⬇ 엑셀 다운로드] 를 누르세요.

Q. 결재상신 버튼이 비활성화 되어 있습니다.

- 행을 선택했는지 확인 (체크박스 클릭 또는 셀 클릭)
- 견적관리의 경우 [견적작성] 으로 견적서(템플릿)가 먼저 생성되어 있어야 함
- 이미 결재중/결재완료 인 건은 재상신 불가

Q. Amaranth 결재 팝업이 안 뜨고 에러만 납니다.

4.3 문제 해결 참조.

Q. 화면이 "Loading chunk app/layout failed" 로 깨집니다.

프론트엔드 dev 서버가 초기 컴파일 중이거나 OOM 으로 재시작 중입니다. 1~2분 기다린 후 하드 새로고침(Cmd+Shift+R / Ctrl+F5).

Q. 외부 REST API 의 [테스트] 가 "실패" 로 나옵니다.

1. 기본 URL 끝에 슬래시가 들어가 있는지 확인 (자동 제거되지만 path 와 중복은 회피)
2. accessToken/hashKey 가 만료됐는지 — Wehago 관리 콘솔에서 키 재발급
3. 외부 서버의 IP 화이트리스트에 RPS 서버 IP 가 등록돼 있는지
4. HTTP 메서드(GET/POST) 가 외부 API 명세와 일치하는지
5. 실패 메시지에 표시된 HTTP 상태 코드 / 응답 본문을 운영팀에 공유

Q. 화면 디자이너로 새 화면을 만들었는데 좌측 메뉴에 안 나옵니다.

1. [관리자 > 시스템 관리 > 메뉴 관리] 에서 신규 화면이 메뉴 트리에 등록됐는지 확인
2. 등록은 됐는데 안 보이면 → 권한 그룹 매핑 누락. [관리자 > 권한 그룹 관리] 에서 해당 그룹에 메뉴 권한 부여
3. 본인 계정으로 로그아웃 → 재로그인 (메뉴 캐시 갱신)

Q. 사용자 정의 화면에서 데이터를 등록했는데 저장이 안 됩니다.

1. 버튼 카드의 동작 타입이 `MODAL` / `EDIT` 인지 확인
2. 버튼의 데이터 흐름 (DataFlowDesigner) 에 "SQL 실행" 노드가 포함돼 있는지
3. SQL 노드의 대상 컬럼이 메인 테이블의 NOT NULL 컬럼을 모두 채우는지
4. 저장 후 미리보기 영역에서 즉시 새로고침되는지 (안 되면 콘솔 로그 확인)