wace_rps/docs/migration/sales/03-sale.md

03. 판매관리 이식 상세

원본: /contractMgmt/salesMgmtList.do (위임) → /salesNcollectMgmt/sales.do 또는 /salesMgmt/salesMgmt JSP: salesmgmt/salesMgmt/salesMgmtList.jsp (34KB) Controller: SalesNcollectMgmtController (line 763~) 대상: app/(main)/COMPANY_16/sales/sale/page.tsx (신규)

1. 화면 구조 (wace_plm 원본)

수주된 항목을 출하지시 → 판매등록 → 거래명세서 발행까지 처리.

1.1 검색 폼

필드	name	타입	비고
주문유형	orderType	select2 (공통코드)
발주번호	poNo	text
고객사	customer_objid	select2
품번	search_partNo	select2-part	hidden search_partObjId
품명	search_partName	select2-part
시리얼	serialNo	text
출하상태	shippingStatus	select2
발주일 from~to	orderDateFrom / orderDateTo	date_icon
출하일 from~to	shippingDateFrom / shippingDateTo	date_icon
판매상태	salesStatus	select2 multiple	다중 선택

1.2 버튼

버튼	id	동작
조회	btnSearch	/salesMgmt/salesMgmtGridList.do
출하지시/판매등록	btnBulkRegister	(녹색) → /salesMgmt/salesRegForm.do 새창
거래명세서 생성	(주석)	매출관리에서 사용
분할출하	(주석)	/salesMgmt/splitShipmentForm.do

1.3 그리드 컬럼

데이터 소스: POST /salesMgmt/salesMgmtGridList.do

#	컬럼	field	정렬
1	프로젝트번호	PROJECT_NO	center, frozen
2	주문유형	ORDER_TYPE	center
3	발주일	ORDER_DATE	center
4	발주번호	PO_NO	center
5	요청납기	REQUEST_DATE	center
6	출하일	SHIPPING_DATE_WITH_COUNT	center
7	고객사	CUSTOMER	left
8	품명	PRODUCT_NAME	left
9	수주수량	ORDER_QUANTITY	right
10	판매수량	SALES_QUANTITY	right
11	잔량	REMAINING_QUANTITY	right
12	판매단가	SALES_UNIT_PRICE	right
13	판매공급가액	SALES_SUPPLY_PRICE	right
14	부가세	SALES_VAT	right
15	판매총액	SALES_TOTAL_AMOUNT	right
16	판매원화총액	SALES_TOTAL_AMOUNT_KRW	right
17	잔량원화총액	REMAINING_AMOUNT_KRW	right
18	수주상태	ORDER_STATUS	center
19	판매상태	SALES_STATUS	center
20	생산상태	PRODUCTION_STATUS	center
21	출하지시상태	SHIPPING_ORDER_STATUS	center
22	유/무상	PAYMENT_TYPE	center
23	환종	SALES_CURRENCY_NAME	center
24	환율	SALES_EXCHANGE_RATE	right
25	S/N	SERIAL_NO	left
26	분할S/N	SPLIT_SERIAL_NO	left
27	품번	PRODUCT_NO	left
28	제품구분	PRODUCT_TYPE	center
29	국내/해외	NATION	center
30	접수일	RECEIPT_DATE	center
31	고객사요청사항	CUSTOMER_REQUEST	left
32	주문서첨부	CU01_CNT	center
33	출하방법	SHIPPING_METHOD	center
34	담당자	MANAGER	center
35	인도조건	INCOTERMS	center
36	거래명세서	TRANSACTION_STATEMENT	center

2. 백엔드 endpoint 매핑

wace_plm endpoint	메서드	용도	vexplor_rps 신규 endpoint
/contractMgmt/salesMgmtList.do	GET	(위임) → /salesmgmt/salesMgmt/salesMgmtList 렌더	(Next.js page)
/salesNcollectMgmt/sales.do	GET	판매 화면 직접 진입	(Next.js page)
/salesMgmt/salesMgmtGridList.do	POST	그리드 데이터	GET /api/sales/sale/list?...
/salesMgmt/salesRegForm.do	GET	출하지시/판매등록 폼	app/(pop)/sales/sale/register/page.tsx (43KB JSP)
/salesMgmt/saveSales.do	POST	판매 저장	POST /api/sales/sale
/salesMgmt/splitShipmentForm.do	GET	분할출하 폼	app/(pop)/sales/sale/split/page.tsx (23KB JSP)
/salesMgmt/saveSplitShipment.do	POST	분할출하 저장	POST /api/sales/sale/split
/salesMgmt/shippingDetailPopup.do	GET	출하 상세 팝업	(Next.js Dialog)
/salesMgmt/transactionStatementForm.do	GET	거래명세서 폼	app/(pop)/sales/sale/transaction/page.tsx (31KB JSP)
/salesMgmt/getTransactionStatementData.do	POST	거래명세서 데이터	GET /api/sales/sale/transaction-statement?...
/salesMgmt/saveTransactionStatement.do	POST	거래명세서 저장	POST /api/sales/sale/transaction-statement
/salesMgmt/getSavedTransactionStatement.do	POST	저장된 거래명세서 조회	GET /api/sales/sale/transaction-statement/:id
/salesMgmt/getAllSerialNumbers.do	POST	시리얼 번호 일괄 조회	(주문과 공유 가능)
/salesNcollectMgmt/contractList.do	GET	(대시보드 화면)	TBD
/salesNcollectMgmt/salesMgmtFormPopup.do	GET	판매 폼 팝업 (구버전)	(사용 안할 듯)
/salesNcollectMgmt/saveSalesMgmt.do	POST	판매 저장 (구버전)	위와 통합
/salesNcollectMgmt/deleteSalesMgmt.do	POST	판매 삭제	DELETE /api/sales/sale/:id
/salesNcollectMgmt/salesDeadlineConfirm.do	POST	매출 마감 확인	(매출관리에서 호출)

3. DB 테이블

2026-05-07 운영 DB 직접 확인 결과: transaction_statement_* 테이블은 존재하지 않음. 거래명세서는 별도 테이블 없이 화면 폼에서 출력만 하거나, attach_file_info에 PDF로 저장하는 방식으로 보임 (정확한 위치는 getSavedTransactionStatement.do SQL 분석 필요).

테이블	역할	DDL
sales_registration	판매 등록 헤더 (프로젝트당 1건, UNIQUE project_no) — 메인	ddl-extracted/101_create_sales_registration.sql
shipment_log	분할출하 이력 라인 (FK parent_sale_no → sales_registration)	위
contract_mgmt	수주 헤더 (조인 필수, target_objid로 연결)	db/dbexport.pgsql:2488
contract_item	수주 라인 (조인 필수)	database/contract_item_tables.sql
contract_item_serial	시리얼 (분할출하 시 분리)	위
production_result	생산 결과 (조인 — PRODUCTION_STATUS)	(참고만)

핵심 관계

contract_mgmt (수주 헤더)
  └─ contract_item (수주 라인)
       └─ contract_item_serial (라인별 S/N)

contract_mgmt.objid = sales_registration.project_no?  (정확한 매칭 키 확인 필요)
                   = shipment_log.target_objid

sales_registration (판매 헤더, 프로젝트당 1건)
  ↑ parent_sale_no
  └─ shipment_log (분할출하 + 매출마감 이력 N건)

⚠️ sales_registration.project_no와 contract_mgmt.objid(또는 contract_no)의 매칭 키는 운영 SQL에서 재확인 필요. 칼럼명은 project_no이지만 실제로는 contract_mgmt를 가리킬 가능성이 큼.

4. 구현 순서

1. 운영 DB DDL 추출 (sales_registration, shipment_log, transaction_statement)
2. 마이그레이션 SQL: db/migrations/102_create_sale_tables.sql
3. 백엔드:
   • backend-node/src/routes/saleRoutes.ts
   • backend-node/src/services/saleService.ts (그리드 SQL은 contract_mgmt + contract_item + sales_registration JOIN, 잔량 계산 = ORDER_QUANTITY - SUM(SALES_QUANTITY))
   • 분할출하 트랜잭션 (라인 분리 + 시리얼 재할당)
4. 프론트엔드:
   • frontend/app/(main)/COMPANY_16/sales/sale/page.tsx (목록)
   • app/(pop)/sales/sale/register/page.tsx (출하지시/판매등록 폼)
   • app/(pop)/sales/sale/split/page.tsx (분할출하)
   • app/(pop)/sales/sale/transaction/page.tsx (거래명세서)

5. 주의사항

• 잔량(REMAINING_QUANTITY) 계산: ORDER_QUANTITY - SUM(sales_registration.SALES_QUANTITY where contract_item_objid = ?). 그리드는 라인 단위 또는 헤더 단위 표시 모드가 있을 수 있음 — 원본 SQL 확인 필요.
• 분할출하: 한 라인의 시리얼을 여러 출하건으로 나누는 시나리오. UI 복잡도 높음.
• 거래명세서: 여러 판매건을 묶어 1장으로 발행. projectNos 파라미터로 다건 처리.
• 상태 컬럼들: ORDER_STATUS / SALES_STATUS / PRODUCTION_STATUS / SHIPPING_ORDER_STATUS 4개를 동시 표시 — 각 상태 머신 정의 필요.
• 환율 컬럼 분리: 수주(exchange_rate)와 판매(sales_exchange_rate)를 별도 보유 — 시점 환율을 잠그는 정책.
• 거래명세서 PDF: 한국어 양식, 워터마크/도장 처리 필요할 수 있음.