From de4c6593f0cc91c6e0c1a4e2bf9581f11f4f5c98 Mon Sep 17 00:00:00 2001
From: joonhoekim <26rote@gmail.com>
Date: Sun, 2 Nov 2025 14:03:34 +0900
Subject: (김준회) SWP 리스트 관리 파트 오류 수정 및 요구사항 반영, 동적 상태
 리스트 필터링 변경, null은 동기화 전(전송 전)으로 간주, 선택된 것만 보내도록
 변경
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/swp/document-service.ts | 76 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

(limited to 'lib/swp/document-service.ts')

diff --git a/lib/swp/document-service.ts b/lib/swp/document-service.ts
index 49e4da4c..f83488d9 100644
--- a/lib/swp/document-service.ts
+++ b/lib/swp/document-service.ts
@@ -1,5 +1,81 @@
 "use server";
 
+/**
+ * SWP Document Service
+ * 
+ * ## 목적
+ * SWP API 응답을 가공하여 프론트엔드에 최적화된 데이터 구조를 제공합니다.
+ * 
+ * ## 역할
+ * 1. **데이터 변환**: API 응답을 UI 친화적 구조로 변환
+ * 2. **데이터 집계**: 여러 API 호출 결과를 조합 (예: 문서 + 파일 개수)
+ * 3. **비즈니스 로직**: 파일 다운로드, 취소 가능 여부 판단 등
+ * 4. **에러 처리**: API 실패 시 사용자 친화적 에러 메시지 반환
+ * 
+ * ## 주요 함수
+ * 
+ * ### 조회
+ * - `getDocumentList(projNo, vndrCd)`: 문서 목록 + 파일 개수 집계
+ * - `getDocumentDetail(projNo, docNo)`: Rev → Activity → File 3단계 트리 구조
+ * 
+ * ### 액션
+ * - `cancelStandbyFile(boxSeq, actvSeq, userId)`: Standby 파일 취소 (SCW01만)
+ * - `downloadDocumentFile(projNo, ownDocNo, fileName)`: NFS에서 파일 다운로드
+ * 
+ * ## 데이터 구조
+ * 
+ * ### DocumentListItem (문서 목록)
+ * ```typescript
+ * {
+ *   DOC_NO: string,
+ *   DOC_TITLE: string,
+ *   LTST_REV_NO: string,
+ *   STAGE: string,
+ *   fileCount: number,        // 전체 파일 개수
+ *   standbyFileCount: number, // 업로드 대기 중 (SCW01)
+ *   ...
+ * }
+ * ```
+ * 
+ * ### DocumentDetail (문서 상세)
+ * ```typescript
+ * {
+ *   docNo: string,
+ *   revisions: [
+ *     {
+ *       revNo: "04",
+ *       stage: "IFC",
+ *       activities: [
+ *         {
+ *           actvNo: "ACTV123",
+ *           type: "External Outbox",
+ *           files: [
+ *             {
+ *               fileNm: "drawing.pdf",
+ *               stat: "COM01",
+ *               canDownload: true,
+ *               canCancel: false,
+ *               ...
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ * 
+ * ## 설계 원칙
+ * 1. **API 호출 최소화**: 필요한 데이터를 한 번에 조회 후 가공
+ * 2. **타입 안전성**: 모든 반환 타입을 명확히 정의
+ * 3. **UI 친화적**: 프론트엔드가 바로 사용 가능한 구조
+ * 4. **에러 복원력**: API 실패 시에도 부분 데이터 제공 시도
+ * 
+ * @see lib/swp/api-client.ts - 저수준 API 호출
+ * @see lib/swp/vendor-actions.ts - 서버 액션 (권한 체크 추가)
+ * @see lib/swp/README.md - 전체 시스템 문서
+ */
+
 import {
   fetchGetVDRDocumentList,
   fetchGetExternalInboxList,
-- 
cgit v1.2.3