@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/abap/rap-business-events.md

@@ -0,0 +1,216 @@
+# RAP Business Events — event-driven architecture, async processing
+
+## Define Event in BDEF
+
+```abap
+managed implementation in class ZBP_I_ORDER unique;
+strict ( 2 );
+
+define behavior for ZI_Order alias Order
+persistent table ztab_order
+lock master
+{
+  create; update; delete;
+
+  " Event raised when order is created
+  event OrderCreated parameter ZA_OrderEventData;
+
+  " Event raised on status change
+  event OrderStatusChanged parameter ZA_OrderStatusEvent;
+
+  " Event without parameter (just notification)
+  event OrderDeleted;
+}
+```
+
+## Define Event Parameter (Abstract Entity)
+
+```abap
+@EndUserText.label: 'Order Event Data'
+define abstract entity ZA_OrderEventData
+{
+  OrderID      : abap.numc(10);
+  CustomerID   : kunnr;
+  TotalAmount  : abap.curr(17,2);
+  CurrencyCode : abap.cuky(5);
+}
+
+@EndUserText.label: 'Order Status Change Event'
+define abstract entity ZA_OrderStatusEvent
+{
+  OrderID   : abap.numc(10);
+  OldStatus : abap.char(1);
+  NewStatus : abap.char(1);
+}
+```
+
+## Raise Event in Handler
+
+```abap
+METHOD create FOR MODIFY IMPORTING entities FOR CREATE Order.
+  " ... create logic ...
+
+  " Raise event after creation
+  LOOP AT entities ASSIGNING FIELD-SYMBOL(<entity>).
+    RAISE ENTITY EVENT ZI_Order~OrderCreated
+      FROM VALUE #( (
+        %key       = VALUE #( OrderID = <entity>-OrderID )
+        %param     = VALUE ZA_OrderEventData(
+          OrderID      = <entity>-OrderID
+          CustomerID   = <entity>-CustomerID
+          TotalAmount  = <entity>-TotalAmount
+          CurrencyCode = <entity>-CurrencyCode ) ) ).
+  ENDLOOP.
+ENDMETHOD.
+
+METHOD acceptOrder FOR MODIFY IMPORTING keys FOR ACTION Order~acceptOrder RESULT result.
+  " ... update status to 'A' ...
+
+  " Raise status change event
+  LOOP AT keys ASSIGNING FIELD-SYMBOL(<key>).
+    RAISE ENTITY EVENT ZI_Order~OrderStatusChanged
+      FROM VALUE #( (
+        %key   = VALUE #( OrderID = <key>-OrderID )
+        %param = VALUE ZA_OrderStatusEvent(
+          OrderID   = <key>-OrderID
+          OldStatus = 'O'
+          NewStatus = 'A' ) ) ).
+  ENDLOOP.
+ENDMETHOD.
+```
+
+## Consume Event — Local Handler
+
+```abap
+" In another behavior pool or same pool
+CLASS lhc_event_handler DEFINITION INHERITING FROM cl_abap_behavior_handler.
+  PRIVATE SECTION.
+    METHODS on_order_created FOR ENTITY EVENT
+      OrderCreated FOR Order.
+ENDCLASS.
+
+CLASS lhc_event_handler IMPLEMENTATION.
+  METHOD on_order_created.
+    LOOP AT created ASSIGNING FIELD-SYMBOL(<event>).
+      " Process event
+      DATA(ls_data) = <event>-%param.
+      " Example: create follow-up document, send notification
+    ENDLOOP.
+  ENDMETHOD.
+ENDCLASS.
+```
+
+## Consume Event — Event Consumption Model (Cross-BO)
+
+```abap
+" Separate BDEF for event consumption
+abstract;
+
+define behavior for ZA_OrderEventData alias OrderEvent
+{
+  " Defines a consumer for the OrderCreated event
+}
+```
+
+## Event Binding to SAP Event Mesh
+
+```json
+// Communication arrangement for Event Mesh
+// In the event binding (ADT), map RAP events to Event Mesh topics:
+// ZI_Order.OrderCreated → sap/s4/beh/order/v1/Order/Created/v1
+// ZI_Order.OrderStatusChanged → sap/s4/beh/order/v1/Order/StatusChanged/v1
+```
+
+### Event Mesh Topic Naming Convention
+
+```
+<namespace>/<bo>/<version>/<entity>/<event>/<event-version>
+sap/s4/beh/order/v1/Order/Created/v1
+```
+
+## CloudEvents Format (Event Mesh Payload)
+
+```json
+{
+  "specversion": "1.0",
+  "type": "sap.s4.beh.order.v1.Order.Created.v1",
+  "source": "/default/sap.s4.beh/S4H",
+  "id": "abc-123-def-456",
+  "time": "2026-03-15T14:30:00Z",
+  "datacontenttype": "application/json",
+  "data": {
+    "OrderID": "0000001234",
+    "CustomerID": "0000100000",
+    "TotalAmount": 5000.00,
+    "CurrencyCode": "EUR"
+  }
+}
+```
+
+## Consume from External (CAP / Node.js)
+
+```js
+// CAP consuming SAP Event Mesh events
+const messaging = await cds.connect.to('messaging');
+
+messaging.on('sap/s4/beh/order/v1/Order/Created/v1', async (msg) => {
+  const { OrderID, CustomerID, TotalAmount } = msg.data;
+  console.log(`Order ${OrderID} created for customer ${CustomerID}`);
+  // Process event
+});
+```
+
+```json
+// package.json — Event Mesh config
+{
+  "cds": {
+    "requires": {
+      "messaging": {
+        "kind": "enterprise-messaging",
+        "format": "cloudevents"
+      }
+    }
+  }
+}
+```
+
+## Additional Save with Event Raising
+
+```abap
+" For managed BOs: raise events in additional save
+managed implementation in class ZBP_I_ORDER unique;
+with additional save;
+
+" In saver class:
+METHOD save_modified.
+  " Access created/updated/deleted records
+  LOOP AT create-order INTO DATA(ls_created).
+    RAISE ENTITY EVENT ZI_Order~OrderCreated
+      FROM VALUE #( (
+        %key   = VALUE #( OrderID = ls_created-OrderID )
+        %param = VALUE ZA_OrderEventData(
+          OrderID = ls_created-OrderID
+          CustomerID = ls_created-CustomerID ) ) ).
+  ENDLOOP.
+ENDMETHOD.
+```
+
+## Rules
+- Events declared in BDEF with `event <name> parameter <abstract_entity>`
+- Event parameter is an abstract entity (no persistence)
+- `RAISE ENTITY EVENT` in handler or saver methods
+- Events are transactional — raised only if save succeeds (COMMIT)
+- Event Mesh: configure via communication arrangement + event binding in ADT
+- CloudEvents format is the standard for Event Mesh payloads
+- Event consumers can be: local handler, other RAP BO, CAP app, external system
+- Events without parameter: just `event OrderDeleted;` (notification only)
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| Raising event before save completes | Events are transactional — only raised on COMMIT |
+| Direct HTTP call instead of event | Use events for async, decoupled communication |
+| Large payload in event parameter | Keep events lightweight — consumer reads details via API |
+| Event without abstract entity when data needed | Define abstract entity with relevant fields |
+| Hardcoded Event Mesh topic in code | Configure via event binding in ADT |
+| Synchronous processing of events | Events are async by nature — design consumers accordingly |

package/dist/knowledge/abap/rap-draft.md

@@ -0,0 +1,191 @@
+# RAP Draft — enable, edit, activate, discard, etag, lock
+
+## Ciclo de vida
+
+```
+[Active] --Edit--> [Draft] --Activate--> [Active]
+                      |
+                   Discard --> [Deleted]
+                      |
+                   Resume  --> [Draft restored]
+```
+
+Fiori Elements V4 exige draft para operacoes de escrita.
+
+## BDEF Interface — habilitar draft
+
+```abap
+managed implementation in class ZBP_I_ROOT unique;
+strict ( 2 );
+with draft;
+
+define behavior for ZI_Root alias Root
+persistent table zroot
+draft table zroot_d
+etag master LocalLastChangedAt
+lock master total etag LastChangedAt
+authorization master ( global )
+{
+  create; update; delete;
+
+  draft action Edit;
+  draft action Activate optimized;
+  draft action Discard;
+  draft action Resume;
+  draft determine action Prepare { validation val1; validation val2; }
+
+  association _Child { create; with draft; }
+}
+
+define behavior for ZI_Child alias Child
+persistent table zchild
+draft table zchild_d
+etag master LocalLastChangedAt
+lock dependent by _Root
+authorization dependent by _Root
+{
+  update; delete;
+  association _Root { with draft; }
+}
+```
+
+## BDEF Projection — expor draft
+
+```abap
+projection;
+strict ( 2 );
+use draft;
+
+define behavior for ZC_Root alias Root
+use etag
+{
+  use create; use update; use delete;
+  use action Edit; use action Activate; use action Discard;
+  use action Resume; use action Prepare;
+  use association _Child { create; with draft; }
+}
+
+define behavior for ZC_Child alias Child
+use etag
+{
+  use update; use delete;
+  use association _Root { with draft; }
+}
+```
+
+## Draft tables
+
+Geradas automaticamente ao ativar o BDEF. Convencao: `<tabela>_d`.
+Contem todos os campos da tabela ativa + `%is_draft`, `%draft_uuid`, `%draft_owner`.
+
+## ETag
+
+```abap
+" Root — controle de concorrencia + total etag para draft
+etag master LocalLastChangedAt
+lock master total etag LastChangedAt
+
+" Child — herda do root
+etag master LocalLastChangedAt
+lock dependent by _Root
+```
+
+- `etag master` → campo `@Semantics.systemDateTime.lastChangedAt` — concorrencia otimista por registro
+- `total etag` → campo `@Semantics.systemDateTime.localInstanceLastChangedAt` — detecta se ativo mudou desde criacao do draft
+
+## Draft actions
+
+| Action | Trigger | Efeito |
+|--------|---------|--------|
+| `Edit` | Usuario clica Edit | Copia ativo → draft table. Adquire lock |
+| `Activate optimized` | Usuario clica Save | Valida + move draft → tabela ativa. So campos modificados |
+| `Discard` | Usuario clica Cancel | Apaga draft. Libera lock |
+| `Resume` | Usuario reabre draft | Restaura draft para edicao |
+| `Prepare` | Antes do Activate | Executa validacoes listadas. Tambem trigado por side effects |
+
+## Prepare — validacao pre-activate
+
+```abap
+draft determine action Prepare
+{
+  validation validateDates;
+  validation validateCustomer;
+  determination calculateTotal;
+}
+```
+
+Validacoes listadas em Prepare rodam quando:
+1. Usuario clica Save (antes do Activate)
+2. Side effect com `determine action Prepare executed on field X`
+
+## EML com draft
+
+```abap
+" Criar draft a partir do ativo
+MODIFY ENTITIES OF ZI_Travel ENTITY Travel
+  EXECUTE Edit FROM VALUE #( ( TravelID = '00000001' ) )
+  MAPPED DATA(mapped).
+
+" Modificar draft
+MODIFY ENTITIES OF ZI_Travel ENTITY Travel
+  UPDATE FIELDS ( Description )
+  WITH VALUE #( ( %is_draft = if_abap_behv=>mk-on
+                  TravelID  = '00000001'
+                  Description = 'Updated' ) ).
+
+" Prepare (validar)
+MODIFY ENTITIES OF ZI_Travel ENTITY Travel
+  EXECUTE Prepare FROM VALUE #( ( %is_draft = if_abap_behv=>mk-on  TravelID = '00000001' ) )
+  REPORTED DATA(reported).
+
+" Activate (salvar)
+MODIFY ENTITIES OF ZI_Travel ENTITY Travel
+  EXECUTE Activate FROM VALUE #( ( %is_draft = if_abap_behv=>mk-on  TravelID = '00000001' ) )
+  FAILED DATA(failed) REPORTED reported.
+COMMIT ENTITIES.
+
+" Ler draft
+READ ENTITIES OF ZI_Travel ENTITY Travel ALL FIELDS
+  WITH VALUE #( ( %is_draft = if_abap_behv=>mk-on  TravelID = '00000001' ) )
+  RESULT DATA(drafts).
+```
+
+## Campos administrativos obrigatorios
+
+```abap
+@Semantics.user.createdBy: true
+created_by            as CreatedBy,               " abp_creation_user
+@Semantics.systemDateTime.createdAt: true
+created_at            as CreatedAt,               " abp_creation_tstmpl
+@Semantics.user.localInstanceLastChangedBy: true
+last_changed_by       as LastChangedBy,           " abp_locinst_lastchange_user
+@Semantics.systemDateTime.localInstanceLastChangedAt: true
+last_changed_at       as LastChangedAt,           " abp_locinst_lastchange_tstmpl → total etag
+@Semantics.systemDateTime.lastChangedAt: true
+local_last_changed_at as LocalLastChangedAt,      " abp_lastchange_tstmpl → etag master
+```
+
+## Draft lock
+
+- Um draft por instancia por vez
+- Outros usuarios veem "Locked by user X"
+- Drafts orfaos: cleanup automatico (default 28 dias)
+
+## Regras
+- `with draft` no topo do BDEF interface
+- `draft table` para cada entidade (root + filhos)
+- Todas as 5 draft actions obrigatorias: Edit, Activate, Discard, Resume, Prepare
+- `association _Child { create; with draft; }` — propaga draft para filhos
+- `use draft` na projection BDEF
+- Todas as draft actions expostas na projection BDEF
+- `Activate optimized` — grava so campos modificados (melhor performance)
+
+## Anti-patterns
+| Errado | Correto |
+|--------|---------|
+| `with draft` sem `draft table` | Ambos obrigatorios |
+| Esquecer `with draft` na association | `association _Child { create; with draft; }` |
+| Esquecer `use draft` na projection | Draft nao funciona sem isso |
+| Nao listar validacoes no Prepare | Validacoes nao rodam antes do Activate |
+| `lock master` no child | `lock dependent by _Root` |
+| `Activate` sem `optimized` | Funciona mas grava todos os campos (pior performance) |