nololsabias-spec/sap-cpi-architect

SAP CPI 아키텍트: iFlow 생성기, 복제기 및 역공학 문서화 도구

세 가지 특화 모드로 작동합니다:

• 모드 1 · iFlow + 스크립트 컬렉션 (.zip) 생성: 3단계(계획 -> BPMN2 .iflw XML -> Groovy 스크립트)로 엔터프라이즈급 iFlow를 설계하고, 모든 아티팩트를 검증하여 SAP Integration Suite로 가져올 수 있는 실제 OSGi .zip 번들을 생성합니다.
• 모드 2 · 기존 iFlow 문서화: 기존 .zip 번들을 추출하여 정적 휴리스틱을 실행하고 8개 섹션의 기술 및 아키텍처 문서를 생성합니다.
• 모드 3 · 새 명세서에 따른 참조 번들 (.zip) 복제 및 적응: 기존의 작동하는 iFlow + 스크립트 컬렉션 .zip 템플릿을 복제하고, 스크립트, XPath 분할기 및 OSGi 디스크립터를 새로운 기능/API 명세서에 맞게 적응시키며, 개인 .prop 파일은 그대로 유지합니다.

---

모드 1: iFlow + 스크립트 컬렉션 생성 (3단계 파이프라인)

단계 0: 대화형 명확화 프로토콜 (가정 전에 질문하기)

아키텍처 계획이나 .zip 패키지를 생성하기 전에, 사용자 프롬프트가 통합 흐름의 모든 중요한 매개변수를 정의하는지 분석합니다. 핵심 정보가 누락된 경우, 필요한 컨텍스트를 얻기 위해 권장 값을 제안하는 간결하고 체계적인 질문을 수행합니다:

1. 소스 및 대상 시스템 (발신자/수신자): 어떤 어댑터(HTTPS, OData v2/v4, SFTP, SOAP, IDoc, JMS, ProcessDirect)를 사용하며, 통신이 동기(Request-Reply)인지 비동기인지?
2. 데이터 계약 및 변환: 입력 및 출력 형식(JSON, XML, IDoc, CSV)은 무엇이며, 어떤 비즈니스 규칙이나 강화(Content Modifier, Router, Groovy Script)가 적용되어야 하는가?
3. 보안 및 외부화된 매개변수: 각 엔드포인트에 필요한 인증 방법(OAuth2 클라이언트 자격 증명, 기본 인증/사용자 자격 증명 별칭, 클라이언트 인증서)과 예상 타임아웃은 무엇인가?
4. 오류 처리 및 알림: 오류 발생 시 Exception Subprocess가 어떻게 작동해야 하는가(이메일 알림 전송, JMS 대기열에 저장, 사용자 정의 HTTP 오류 구조 반환)?

고속 처리 규칙: 사용자가 이미 완전한 명세서를 제공했거나 SAP 모범 사례 기본값을 가정하도록 명시적으로 요청한 경우, 가정된 내용을 문서화한 후 직접 1단계로 진행합니다.

단계 1: 아키텍처 계획 (plan.json)

다음을 포함하는 JSON 계획을 설계합니다:

• iflowName (PascalCase(밑줄 포함), 예: Order_Sync_S4HANA)
• scriptCollectionName (SC_<iflowName>)
• businessDescription 및 technicalSummary
• parameters (모든 외부 URL, 자격 증명 별칭 또는 타임아웃을 KEY: defaultValue로 외부화)
• components[] (순서화된 단계: StartEvent, ContentModifier, RequestReply, Router, ScriptTask, ExceptionSubprocess, EndEvent)
• groovyScriptsPlan[] ({ fileName, purpose })

단계 2: BPMN 2.0 XML (<iflowName>.iflw)

SAP 공식 통합 흐름 설계 지침에 따라 계획의 모든 단계를 구현하는 완전한 BPMN 2.0 XML을 생성합니다:

• bpmn2, bpmndi, ifl, dc, di 네임스페이스와 함께 <bpmn2:definitions>를 포함해야 합니다.
• <bpmn2:collaboration> (발신자, 수신자, 통합 프로세스) 및 <bpmn2:process>를 포함해야 합니다.
• <bpmn2:subProcess triggeredByEvent="true" ifl:type="ExceptionSubProcess"> (또는 ErrorEventSubProcessTemplate)를 포함해야 합니다:
  • 탄력적인 오류 및 트랜잭션 아키텍처: 일시적 오류(자동 재시도/백오프가 있는 JMS 대기열 사용)와 영구/독성 오류(예외 하위 프로세스의 데이터 저장소 또는 데드 레터 대기열로 라우팅하고, 선택적으로 중앙 오류 로깅 iFlow로 ProcessDirect를 통해 알림 전달)를 구분합니다. 트랜잭션 단계를 로컬 통합 프로세스 내부로 격리하여 트랜잭션 경계를 짧게 유지합니다.
• 분할기 및 메시지 매핑 스트리밍("분할 우선" 규칙):
  • 모든 분할기 단계(일반 분할기 / 반복 분할기)는 스트리밍을 활성화(<ifl:property key="streaming" value="true"/>)하고 무거운 조건자 없이 직접 XPath 표현식을 사용해야 합니다.
  • 메가 페이로드(> 50MB)를 그래픽 메시지 매핑(DOM 트랩)에 직접 전달하지 말고, 항상 메시지 매핑 전에 스트리밍 분할기를 배치합니다.
• 라우터 최적화:
  • 라우터 전에 Content Modifier에서 XML 값을 java.lang.String, java.lang.Long과 같은 유형화된 교환 속성으로 추출하고, 여러 라우터 분기에서 반복 XPath를 평가하는 대신 ${property.Field} (Camel Simple)를 평가합니다.
  • 라우터 분기를 가장 빈번한 순서에서 가장 적은 순서로 정렬하고, 항상 <bpmn2:exclusiveGateway>에 기본 경로를 정의합니다.
• 모든 외부 엔드포인트는 https:// 및 외부화된 매개변수 {{PARAM_NAME}}를 사용해야 합니다.
• 모든 동기 ExternalCall 작업은 명시적 timeout 속성(예: 60000)을 선언해야 합니다.
• 모든 스크립트 작업은 <ifl:property key="scriptFunction" value="processData"/> 및 <ifl:property key="script" value="<fileName>"/>를 참조해야 합니다.
• SAP CPI 웹 UI 편집기가 다이어그램을 깔끔하게 렌더링할 수 있도록 <bpmndi:BPMNDiagram> 좌표를 포함해야 합니다.
• 재사용 가능한 교차 처리자를 위한 선택적 패턴:
  • 중앙 집중식 오류 및 관찰 가능성 처리자 (ProcessDirect -> 병렬 멀티캐스트):
    • 다른 iFlow의 Exception Subprocess로부터 ProcessDirect ({{PD_address}})를 통해 오류 XML 봉투를 수신하며, 모든 필드가 minOccurs="0" nillable="true" ( Environment, InterfaceName, InterfaceDescription, ObjectID, ExceptionMessage, OriginalMessageProcessingLogID, SAP_MessageProcessingLogID, SAP_MplCorrelationId 및 SendBody와 같은 플래그 포함)인 관대한 XSD로 뒷받침됩니다.
    • 병렬 멀티캐스트를 사용하여 흐름을 두 분기로 나눕니다: (1) Content Modifier에서 HTML 테이블을 포맷하는 이메일 알림 분기(Mail SMTP with starttls_mandatory), (2) SAP Cloud Logging / OpenSearch로의 관찰 가능성 분기로, 라우터에서 ${property.SendBody.toLowerCase()} = 'yes'를 평가하여 두 Message Mapping (WithBody.mmap vs NoBody.mmap) 중에서 선택하고, 출력을 XML to JSON Converter (xmlJsonSuppressRootElement=true)로 변환한 후 HTTP POST(클라이언트 인증서 {{CloudLoggingCertificate}} 사용)로 전송합니다.
    • CamelExceptionCaught를 검사하고 실패 시 세부 정보를 MPL 첨부 파일(addAttachmentAsString)로 저장하여 메일 또는 로그 서버 오류 시 무한 루프를 방지하는 자체 로컬 Exception Subprocess를 포함합니다.
  • 중앙 집중식 토큰 갱신 처리자 (StartTimerEvent -> LocalIntegrationProcess -> 글로벌 Data Store):
    • 매개변수화된 StartTimerEvent ({{TokenTimer}} 유형 custom:schedule in parameters.propdef)로 시작하고, ExternalCall 호출 및 토큰 추출을 LocalIntegrationProcess (processType="directCall")에 위임하며, Content Modifier에서 Delete 작업($name=Authorization, $name=SAP_MonitoringStateProperties, $name=Content-Length 등)을 통해 헤더와 내부 속성을 정리하고, 헤더/토큰을 암호화된 글로벌 데이터 저장소 (activityType="DBstorage", operation="put", visibility="global", encrypt="true", override="true", includeMessageHeaders="true")에 유지합니다.

단계 3: Groovy 스크립트 (src/main/resources/script/*.groovy)

모든 SAP CPI 스크립팅 지침(def Message processData(Message message), Reader 스트리밍, JsonSlurperClassic, XmlSlurper with disallow-doctype-decl, ZoneId.of("UTC"), 조건부 MPL 첨부 파일, CPI-ERR: 예외 재발생)에 따라 groovyScriptsPlan[]에 계획된 각 Groovy 스크립트를 작성합니다.

단계 4: OSGi 번들 (.zip) 유효성 검사 및 빌드

iflowName, scriptCollectionName, businessDescription, parameters, iflwXml 및 groovyScripts를 포함하는 사양 JSON을 저장하고 build-cpi-package.mjs를 실행합니다:

node ./scripts/build-cpi-package.mjs <spec.json | --demo> --out-dir ./dist-packages

• OSGi 패키저 및 검증기 스크립트: build-cpi-package.mjs
• OSGi 번들 사양: osgi-bundle-spec.md
• 검증 게이트 및 OSGi 매니페스트 준수:
  • build-cpi-package.mjs는 <iflowName>.zip, <scriptCollectionName>.zip 및 Paquete_<iflowName>.zip을 생성하기 전에 .iflw BPMN2 XML과 모든 Groovy 스크립트를 검증합니다.
  • .project 및 META-INF/MANIFEST.MF를 최상위 래퍼 폴더 내에 중첩시키지 않고 .zip의 루트에 직접 배치하며, 모든 MANIFEST.MF 줄을 72바이트 UTF-8로 \r\n 연속으로 래핑하여 SAP CPI가 "프로젝트에 유효한 매니페스트 파일이 포함되어야 합니다" 오류를 발생시키지 않도록 합니다.
  • 항상 사용자에게 외부 Paquete_<iflowName>.zip 래퍼를 업로드하는 대신 <scriptCollectionName>.zip (추가 -> 스크립트 컬렉션) 및 <iflowName>.zip (추가 -> 통합 흐름)을 개별적으로 업로드하도록 알립니다.

---

모드 2: 기존 iFlow 문서화 (8개 섹션 역공학)

단계 0: 문서 범위 명확화

기술 문서를 작성하기 전에 다음을 확인합니다:

1. 사용자가 .zip 또는 .iflw 파일 경로를 제공했는지 여부. 제공하지 않은 경우 패키지 경로를 요청합니다.
2. 문서 대상(예: 운영/지원 팀, BTP 보안 감사 또는 프로덕션 이전)에 대해 특정 측면을 강조해야 하는지, 또는 .iflw 내에 없는 비즈니스 컨텍스트를 추가해야 하는지 확인합니다.

단계 1: .zip에서 컨텍스트 및 휴리스틱 추출

기존 .zip 번들에서 extract-for-docs.mjs를 실행합니다:

node ./scripts/extract-for-docs.mjs <existing-iflow.zip | --demo>

• 추출기 및 문서 검증기 스크립트: extract-for-docs.mjs
• 8개 섹션 템플릿: doc-template-8-sections.md

단계 2: 8개 필수 섹션 작성 및 검증

doc-template-8-sections.md의 정확한 8개 제목을 따라 Markdown 문서를 작성하고 생성된 .md 파일을 다음으로 검증합니다:

node ./scripts/extract-for-docs.mjs --validate-doc <generated-doc.md>

---

모드 3: 새 명세서에 따른 참조 번들 (.zip) 복제 및 적응

사용자가 기존 SAP CPI 패키지(하나 이상의 iFlow 및/또는 ScriptCollection을 포함하는 .zip)를 제공하고 API 명세서 문서(PDF, Markdown, OpenAPI)를 기반으로 새 통합을 생성하거나 기존 통합을 업데이트하도록 요청할 때 이 모드를 사용합니다.

단계 0: 차이 분석 및 개인 정보 보호 규칙

1. 개인 데이터 노출 없는 검사(개인 정보 보호 우선):
   • inspect-iflow-zip.mjs로 .zip 구조를 검사합니다(자동으로 .prop 값을 [REDACTED]로 수정).
   • 절대 parameters.prop의 민감한 값(자격 증명, 개인 엔드포인트, 내부 대기열)을 읽거나 인쇄하지 말고, 명시적인 지시 없이 고객 패키지를 Git 저장소에 업로드하지 마십시오.
2. 사양 대 구현 비교 및 명확화 질문:
   • 참조 번들과 사양 문서 간의 쿼리 필터, 요청된 필드, 참조 확인 테이블 및 JSON/XML 스키마를 비교합니다.
   • 문서에 열린 지점, 상위 엔터티에서 상속된 필드(점 표기법 대 null), 또는 필드 이름 불일치(예: 정식 필드 대 대체 필드)가 있는 경우, 코드를 작성하기 전에 사용자에게 질문하고 먼저 권장 옵션을 제안합니다.

단계 1: 스크립트 컬렉션에서 스크립트 적응 또는 생성

1. 원본 스크립트 컬렉션의 아키텍처 패턴을 유지하면서 새 .groovy 스크립트를 생성하고(사용자가 요청한 경우 기존 스크립트 업데이트)합니다.
2. 다음을 확인합니다:
   • Groovy 2.4 스크립트(com.sap.gateway.ip.core.customdev.util.Message)에서는 **groovy.util.XmlSlurper**를 가져옵니다(groovy.xml.XmlSlurper는 절대 사용하지 않음. unable to resolve class groovy.xml.XmlSlurper로 컴파일 실패).
   • Reader (BufferedReader / StringReader)에서 읽을 때, 절대 bodyReader.getText('UTF-8')를 문자셋 매개변수와 함께 호출하지 마십시오(MissingMethodException 발생). bodyReader.getText()를 인수 없이 사용하거나 bodyReader를 직접 .parse(bodyReader)에 전달합니다.
   • 스크립트 수준의 모든 상수 @Field는 final (@Field final)을 포함하고, XML 파싱은 disallow-doctype-decl을 비활성화하며, JSON 파싱은 JsonSlurperClassic을 사용합니다.
3. validate-groovy.mjs로 모든 스크립트를 일괄 검증합니다:

node ../sap-cpi-groovy-generator/scripts/validate-groovy.mjs <script-folder> --strict

단계 2: iFlow 복제 및 스크립트 컬렉션 패키징

clone-iflow-bundle.mjs를 실행하여 각 참조 iFlow를 복제하고(.project, META-INF/MANIFEST.MF, metainfo.prop, <NewName>.iflw, .groovy 스크립트 참조 및 분할기 XPath 표현식 업데이트) 새 스크립트를 스크립트 컬렉션 .zip에 주입합니다:

# 1. BPMN2 다이어그램 및 .prop을 그대로 유지하면서 iFlow .zip 복제 및 적응
node ./scripts/clone-iflow-bundle.mjs --source <Reference_iFlow.zip> --target-name <New_iFlow> --out <New_iFlow.zip> --replace <OldScript.groovy=NewScript.groovy> --xpath <//oldNode=//newNode> [--add-resource <Schema.xsd>] [--add-resource <Mapping.mmap>]

# 2. 기존 iFlow .zip에 개별 파일(.xsd, .mmap, .xsl, .wsdl, .groovy) 주입 또는 업데이트 (이름 변경 없음)
node ./scripts/clone-iflow-bundle.mjs --source <Existing_iFlow.zip> --add-resource <NewSchema.xsd> --add-resource <NewMapping.mmap> --out <Updated_iFlow.zip>

# 3. 검증된 새 스크립트로 스크립트 컬렉션 .zip 업데이트
node ./scripts/clone-iflow-bundle.mjs --update-sc <SC_Source.zip> --scripts-dir <script-folder> --out <Updated_SC.zip> --strict

• 복제기 및 SC 업데이터 스크립트: clone-iflow-bundle.mjs

단계 3: 최종 검증 적용

1. OSGi 매니페스트 준수: MANIFEST.MF 줄이 정확히 72바이트에 래핑되어 있는지 확인합니다.
2. BPMN2 XML 유효성 검사: SAP CPI XML 스키마(iflw.xsd)를 기준으로 .iflw 파일의 유효성을 검사합니다.
3. Groovy 구문 검증: validate-groovy.mjs --strict로 모든 스크립트의 구문을 확인합니다.
4. 매개변수 일관성: metainfo.prop가 새 iFlow 이름과 일치하는지, 모든 외부화된 매개변수 {{PARAM}}가 parameters.prop에 정의되어 있는지 확인합니다.

---

실행 개요: Python 기반 다중 모드 인터페이스

기본 인터페이스는 sap-cpi-architect.py를 통해 Python 기반 대화형을 실행하며, 인텐트 인식 및 각 모드에 대한 오케스트레이션 흐름을 제공합니다.

python sap-cpi-architect.py [modo] [argumentos...]

• 메인 Python 래퍼: sap-cpi-architect.py

---

참조 문서 인덱스

문서	위치
OSGi 번들 사양	references/osgi-bundle-spec.md
8개 섹션 문서 템플릿	references/doc-template-8-sections.md
CPI 패키지 빌드 스크립트	scripts/build-cpi-package.mjs
문서 추출 스크립트	scripts/extract-for-docs.mjs
iFlow 복제기 스크립트	scripts/clone-iflow-bundle.mjs
Groovy 검증기 스크립트	scripts/validate-groovy.mjs
iFlow 검사기 스크립트	scripts/inspect-iflow-zip.mjs