nololsabias-spec/sap-cpi-architect

SAP CPI Architect: Gerador, Clonador e Documentador de Engenharia Reversa de iFlow

Opera em três modos especializados:

• Modo 1 · Gerar iFlow + Coleção de Scripts (.zip): Projeta um iFlow de nível empresarial em 3 estágios (Plano -> BPMN2 .iflw XML -> Scripts Groovy), valida todos os artefatos e constrói bundles OSGi .zip reais importáveis no SAP Integration Suite.
• Modo 2 · Documentar iFlow Existente: Extrai um bundle .zip existente, executa heurísticas estáticas e gera a documentação técnica e arquitetônica de 8 seções.
• Modo 3 · Clonar e Adaptar Bundles de Referência (.zip) conforme Nova Especificação: Clona um modelo de iFlow + Coleção de Scripts .zip existente e funcional, adapta scripts, splitters XPath e descritores OSGi para uma nova especificação funcional/de API, mantendo arquivos .prop privados intocados.

---

Modo 1: Gerar iFlow + Coleção de Scripts (Pipeline em 3 Estágios)

Estágio 0: Protocolo de Esclarecimento Interativo (Perguntar Antes de Assumir)

Antes de gerar o plano arquitetônico ou o pacote .zip, analise se o prompt do usuário define todos os parâmetros críticos do fluxo de integração. Se faltar informação chave, faça perguntas breves e estruturadas (propondo valores recomendados) para obter o contexto necessário:

1. Sistemas de Origem e Destino (Sender / Receiver): Quais adaptadores eles usam (HTTPS, OData v2/v4, SFTP, SOAP, IDoc, JMS, ProcessDirect) e se a comunicação é síncrona (Request-Reply) ou assíncrona?
2. Contratos de Dados e Transformações: Qual formato entra e sai (JSON, XML, IDoc, CSV) e quais regras de negócio ou enriquecimentos (Content Modifier, Router, Groovy Script) devem ser aplicados?
3. Segurança e Parâmetros Externalizados: Qual método de autenticação cada endpoint requer (OAuth2 Client Credentials, Basic Auth / alias de credencial de usuário, certificado de cliente) e quais timeouts são esperados?
4. Gerenciamento de Erros e Alertas: O que o Exception Subprocess deve fazer quando ocorre uma falha (enviar alerta por e-mail, salvar em fila JMS, retornar estrutura de erro HTTP personalizada)?

Regra de Via Rápida: Se o usuário já forneceu uma especificação completa ou pede explicitamente para assumir valores padrão de melhores práticas SAP, prossiga diretamente para o Estágio 1 documentando as suposições feitas.

Estágio 1: Plano Arquitetônico (plan.json)

Projete o plano JSON contendo:

• iflowName (PascalCase com underscores, ex., Order_Sync_S4HANA)
• scriptCollectionName (SC_<iflowName>)
• businessDescription e technicalSummary
• parameters (cada URL externa, alias de credencial ou timeout externalizado como KEY: defaultValue)
• components[] (etapas ordenadas: StartEvent, ContentModifier, RequestReply, Router, ScriptTask, ExceptionSubprocess, EndEvent)
• groovyScriptsPlan[] ({ fileName, purpose })

Estágio 2: XML BPMN 2.0 (<iflowName>.iflw)

Gere o XML BPMN 2.0 completo implementando cada etapa do plano seguindo as Diretrizes Oficiais de Design de Fluxo de Integração da SAP:

• Deve incluir <bpmn2:definitions> com namespaces bpmn2, bpmndi, ifl, dc, di.
• Deve incluir <bpmn2:collaboration> (Sender, Receiver, Processo de Integração) e <bpmn2:process>.
• Deve incluir <bpmn2:subProcess triggeredByEvent="true" ifl:type="ExceptionSubProcess"> (ou ErrorEventSubProcessTemplate):
  • Arquitetura Resiliente de Erro e Transação: Diferencie entre erros transitórios (use Filas JMS com repetição/backoff automáticos) e erros persistentes/poison (encaminhe para um Data Store ou Fila de Mensagens Mortas no Exception Subprocess, e opcionalmente encaminhe alertas via ProcessDirect para um iFlow central de Log de Erros). Mantenha os limites de transação curtos, isolando etapas transacionais dentro de Processos de Integração Locais.
• Splitter & Streaming de Mapeamento de Mensagens (Regra "Split-First"):
  • Todas as etapas Splitter (General Splitter / Iterating Splitter) devem habilitar streaming (<ifl:property key="streaming" value="true"/>) e usar expressões XPath diretas sem predicados pesados.
  • Nunca passe mega-payloads (> 50 MB) diretamente para um Mapeamento de Mensagens gráfico (armadilha DOM); sempre coloque um Splitter com streaming antes do Mapeamento de Mensagens.
• Otimização de Router:
  • Extraia valores XML para Propriedades de Troca tipadas (java.lang.String, java.lang.Long) em um Content Modifier antes do Router, e avalie ${property.Field} (Camel Simple) em vez de avaliar XPath repetido em vários branches do Router.
  • Ordene os branches do Router do mais frequente para o menos frequente, e sempre defina uma rota default em <bpmn2:exclusiveGateway>.
• Todos os endpoints externos devem usar https:// e parâmetros externalizados {{PARAM_NAME}}.
• Todas as tarefas ExternalCall síncronas devem declarar uma propriedade timeout explícita (ex., 60000).
• Cada Script Task deve referenciar <ifl:property key="scriptFunction" value="processData"/> e <ifl:property key="script" value="<fileName>"/>.
• Deve incluir coordenadas <bpmndi:BPMNDiagram> para que o editor de IU web do SAP CPI renderize o diagrama corretamente.
• Padrões Opcionais para Handlers Transversais Reutilizáveis:
  • Handler Centralizado de Erros e Observabilidade (ProcessDirect -> Parallel Multicast) :
    • Recebe um envelope XML de erro via ProcessDirect ({{PD_address}}) dos Exception Subprocess de outros iFlows, apoiado por um XSD tolerante onde todos os campos são minOccurs="0" nillable="true" (incluindo Environment, InterfaceName, InterfaceDescription, ObjectID, ExceptionMessage, OriginalMessageProcessingLogID, SAP_MessageProcessingLogID, SAP_MplCorrelationId e flags como SendBody).
    • Usa um Parallel Multicast para dividir o fluxo em dois ramos: (1) um ramo de alerta por e-mail (Mail SMTP com starttls_mandatory) que formata uma tabela HTML em um Content Modifier, e (2) um ramo de observabilidade para SAP Cloud Logging / OpenSearch que avalia ${property.SendBody.toLowerCase()} = 'yes' em um Router para escolher entre dois Message Mapping (WithBody.mmap vs NoBody.mmap), converte a saída com XML to JSON Converter (xmlJsonSuppressRootElement=true) e a envia por HTTP POST com certificado de cliente ({{CloudLoggingCertificate}}).
    • Inclui seu próprio Exception Subprocess local que inspeciona CamelExceptionCaught e salva o detalhe como anexo MPL (addAttachmentAsString) para evitar loops infinitos se o servidor de e-mail ou logs falhar.
  • Handler Centralizado de Atualização de Token (StartTimerEvent -> LocalIntegrationProcess -> Global Data Store) :
    • Inicia com um StartTimerEvent parametrizado ({{TokenTimer}} do tipo custom:schedule em parameters.propdef), delega a chamada ExternalCall e extração do token para um LocalIntegrationProcess (processType="directCall"), limpa cabeçalhos e propriedades internas em um Content Modifier através de ações Delete ($name=Authorization, $name=SAP_MonitoringStateProperties, $name=Content-Length, etc.) e persiste o cabeçalho/token em um Data Store Global Criptografado (activityType="DBstorage", operation="put", visibility="global", encrypt="true", override="true", includeMessageHeaders="true").

Estágio 3: Scripts Groovy (src/main/resources/script/*.groovy)

Escreva cada script Groovy planejado em groovyScriptsPlan[] seguindo todas as Diretrizes de Script SAP CPI (def Message processData(Message message), streaming Reader, JsonSlurperClassic, XmlSlurper com disallow-doctype-decl, ZoneId.of("UTC"), anexos MPL condicionais, relançamento de exceção CPI-ERR:).

Estágio 4: Validação e Construção dos Bundles OSGi (.zip)

Salve seu JSON de especificação (contendo iflowName, scriptCollectionName, businessDescription, parameters, iflwXml e groovyScripts) e execute build-cpi-package.mjs:

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

• Script de Empacotador e Validador OSGi: build-cpi-package.mjs
• Especificação do Bundle OSGi: osgi-bundle-spec.md
• Gate de Verificação & Conformidade do Manifesto OSGi:
  • O build-cpi-package.mjs valida tanto o XML BPMN2 .iflw quanto cada script Groovy antes de produzir <iflowName>.zip, <scriptCollectionName>.zip e Paquete_<iflowName>.zip.
  • Coloca .project e META-INF/MANIFEST.MF diretamente na raiz do .zip (nunca aninhado dentro de uma pasta wrapper de nível superior) e quebra todas as linhas de MANIFEST.MF em 72 bytes UTF-8 com continuações \r\n para que o SAP CPI nunca falhe com The project must contain a valid manifest file.
  • Sempre lembre o usuário de fazer upload de <scriptCollectionName>.zip (em Add -> Script Collection) e <iflowName>.zip (em Add -> Integration Flow) individualmente, em vez de fazer upload do wrapper externo Paquete_<iflowName>.zip.

---

Modo 2: Documentar iFlow Existente (Engenharia Reversa em 8 Seções)

Passo 0: Esclarecimento do Escopo Documental

Antes de redigir a documentação técnica, verifique:

1. Se o usuário forneceu o caminho para o arquivo .zip ou .iflw. Se não indicou, peça o caminho do pacote.
2. Se precisa enfatizar algum aspecto específico para o público do documento (ex., equipe de Operações/Suporte, auditoria de Segurança BTP, ou transferência para Produção) ou adicionar contexto de negócio que não conste dentro do .iflw.

Passo 1: Extrair Contexto e Heurísticas do .zip

Execute extract-for-docs.mjs no bundle .zip existente:

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

• Script de Extrator e Validador de Documentos: extract-for-docs.mjs
• Template de 8 Seções: doc-template-8-sections.md

Passo 2: Redigir e Validar as 8 Seções Obrigatórias

Escreva a documentação Markdown seguindo exatamente os 8 títulos em doc-template-8-sections.md e valide o arquivo .md gerado com:

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

---

Modo 3: Clonar e Adaptar Bundles de Referência (.zip) conforme Nova Especificação

Use este modo quando o usuário fornecer um pacote SAP CPI existente (.zip contendo um ou mais iFlows e/ou uma ScriptCollection) e pedir para criar novas integrações ou atualizar as existentes com base em um documento de especificação de API (PDF, Markdown, OpenAPI).

Passo 0: Análise de Lacunas (Gap Analysis) e Regra de Privacidade

1. Inspeção sem Exposição de Dados Privados (Privacidade em Primeiro Lugar) :
   • Inspecione a estrutura dos .zip com inspect-iflow-zip.mjs (que redige automaticamente os valores de .prop como [REDACTED]).
   • NUNCA leia ou imprima valores sensíveis de parameters.prop (credenciais, endpoints privados, filas internas) nem faça upload de pacotes do cliente para o repositório Git, a menos que haja instrução explícita.
2. Contraste Especificação vs. Implementação e Perguntas de Esclarecimento:
   • Compare os filtros de consulta, campos solicitados, tabelas de resolução de referências e esquemas JSON/XML entre o bundle de referência e o documento de especificação.
   • Se o documento apresentar pontos em aberto, campos herdados de entidades pai (dot-walking vs null), ou discrepâncias de nomes de campo (ex., campo canônico vs campo alternativo), pergunte ao usuário antes de escrever código, propondo primeiro a opção recomendada.

Passo 1: Adaptar ou Criar os Scripts na Coleção de Scripts

1. Crie os novos scripts .groovy (e atualize os existentes se o usuário solicitou) mantendo o padrão arquitetônico da Coleção de Scripts original.
2. Certifique-se de que:
   • Em scripts Groovy 2.4 (com.sap.gateway.ip.core.customdev.util.Message), importe groovy.util.XmlSlurper (nunca groovy.xml.XmlSlurper, que falha ao compilar com unable to resolve class groovy.xml.XmlSlurper).
   • Ao ler de um Reader (BufferedReader / StringReader), nunca invoque bodyReader.getText('UTF-8') com parâmetro de charset (lança MissingMethodException); use bodyReader.getText() sem argumentos ou passe bodyReader diretamente para .parse(bodyReader).
   • Toda constante no nível de script com @Field inclua final (@Field final), o parsing XML desabilite disallow-doctype-decl, e o parsing JSON use JsonSlurperClassic.
3. Valide todos os scripts em lote com validate-groovy.mjs:

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

Passo 2: Clonar os iFlows e Empacotar a Coleção de Scripts

Execute clone-iflow-bundle.mjs para clonar cada iFlow de referência (atualizando .project, META-INF/MANIFEST.MF, metainfo.prop, <NovoNome>.iflw, referências a scripts .groovy e expressões XPath do Splitter) e para injetar os novos scripts na Coleção de Scripts .zip:

# 1. Clonar e adaptar um iFlow .zip mantendo intactos seus diagramas BPMN2 e .prop
node ./scripts/clone-iflow-bundle.mjs --source <Referencia_iFlow.zip> --target-name <Novo_iFlow> --out <Novo_iFlow.zip> --replace <ScriptVelho.groovy=ScriptNovo.groovy> --xpath <//nodoVelho=//nodoNovo> [--add-resource <Esquema.xsd>] [--add-resource <Mapeamento.mmap>]

# 2. Injetar ou atualizar arquivos soltos (.xsd, .mmap, .xsl, .wsdl, .groovy) em um iFlow .zip existente (sem renomeá-lo)
node ./scripts/clone-iflow-bundle.mjs --source <iFlow_Existente.zip> --add-resource <NovoEsquema.xsd> --add-resource <NovoMapeamento.mmap> --out <iFlow_Atualizado.zip>

# 3. Atualizar a Coleção de Scripts .zip com os novos scripts validados
node ./scripts/clone-iflow-bundle.mjs --update-sc <SC_Origem.zip> --scripts-dir <pasta-scripts> --out <SC_Atualizada.zip> --strict

• Script de Clonador e Atualizador de SC: clone-iflow-bundle.mjs