@linkup-ai/abap-ai 2.0.0

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

@@ -0,0 +1,280 @@
+# RAP Numbering — early, late, unmanaged numbering
+
+## Early Numbering (Default for Managed)
+
+Key assigned at CREATE time, before save. Simplest approach.
+
+### 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
+{
+  field ( readonly ) OrderID;
+
+  create;
+  update;
+  delete;
+
+  determination setOrderID on modify { create; }
+}
+```
+
+### Handler — MAX + 1 Pattern
+
+```abap
+METHOD setOrderID.
+  READ ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order FIELDS ( OrderID ) WITH CORRESPONDING #( keys )
+    RESULT DATA(orders).
+
+  SELECT SINGLE FROM ztab_order FIELDS MAX( order_id ) INTO @DATA(lv_max).
+
+  MODIFY ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order UPDATE FIELDS ( OrderID )
+    WITH VALUE #( FOR order IN orders WHERE ( OrderID IS INITIAL )
+      LET lv_next = lv_max + 1 IN
+      ( %tky = order-%tky  OrderID = lv_next ) ).
+ENDMETHOD.
+```
+
+### Handler — UUID Pattern
+
+```abap
+METHOD setOrderID.
+  READ ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order FIELDS ( OrderID ) WITH CORRESPONDING #( keys )
+    RESULT DATA(orders).
+
+  MODIFY ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order UPDATE FIELDS ( OrderID )
+    WITH VALUE #( FOR order IN orders WHERE ( OrderID IS INITIAL )
+      ( %tky    = order-%tky
+        OrderID = cl_system_uuid=>create_uuid_x16_static( ) ) ).
+ENDMETHOD.
+```
+
+### Handler — Number Range Pattern
+
+```abap
+METHOD setOrderID.
+  READ ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order FIELDS ( OrderID ) WITH CORRESPONDING #( keys )
+    RESULT DATA(orders).
+
+  DATA(lt_no_id) = FILTER #( orders WHERE OrderID IS INITIAL ).
+  IF lt_no_id IS INITIAL. RETURN. ENDIF.
+
+  TRY.
+      cl_numberrange_runtime=>number_get(
+        EXPORTING nr_range_nr = '01'
+                  object      = 'ZORDER_NR'
+                  quantity    = CONV #( lines( lt_no_id ) )
+        IMPORTING number      = DATA(lv_number) ).
+    CATCH cx_number_ranges.
+      RETURN.
+  ENDTRY.
+
+  DATA(lv_next) = CONV numc10( lv_number ).
+  MODIFY ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order UPDATE FIELDS ( OrderID )
+    WITH VALUE #( FOR order IN lt_no_id
+      ( %tky = order-%tky  OrderID = lv_next )  ).
+ENDMETHOD.
+```
+
+## Late Numbering
+
+Key assigned during SAVE phase (adjust_numbers). Used when key comes from external system or number range that should only be consumed on commit.
+
+### BDEF
+
+```abap
+managed implementation in class ZBP_I_ORDER unique;
+strict ( 2 );
+with draft;
+
+define behavior for ZI_Order alias Order
+persistent table ztab_order
+draft table ztab_order_d
+lock master total etag LastChangedAt
+etag master LocalLastChangedAt
+late numbering
+{
+  field ( readonly ) OrderID;
+
+  create;
+  update;
+  delete;
+
+  draft action Edit;
+  draft action Activate optimized;
+  draft action Discard;
+  draft action Resume;
+  draft determine action Prepare;
+}
+```
+
+### Saver Class — adjust_numbers
+
+```abap
+CLASS lsc_order DEFINITION INHERITING FROM cl_abap_behavior_saver.
+  PROTECTED SECTION.
+    METHODS adjust_numbers REDEFINITION.
+ENDCLASS.
+
+CLASS lsc_order IMPLEMENTATION.
+  METHOD adjust_numbers.
+    DATA(lt_orders) = mapped-order.
+
+    LOOP AT lt_orders ASSIGNING FIELD-SYMBOL(<order>).
+      " Only assign to records without key
+      IF <order>-OrderID IS INITIAL.
+        TRY.
+            cl_numberrange_runtime=>number_get(
+              EXPORTING nr_range_nr = '01'
+                        object      = 'ZORDER_NR'
+              IMPORTING number      = DATA(lv_number) ).
+          CATCH cx_number_ranges.
+            CONTINUE.
+        ENDTRY.
+        <order>-OrderID = lv_number.
+      ENDIF.
+    ENDLOOP.
+  ENDMETHOD.
+ENDCLASS.
+```
+
+### Late Numbering — EML with %tmp and %pid
+
+```abap
+" During draft / before save, records use temporary keys
+" %tmp — temporary key (system-generated during create)
+" %pid — persistent identifier (maps temp to final key)
+
+" The framework automatically maps %tmp to the final key after adjust_numbers
+```
+
+## Early Numbering vs Late Numbering
+
+| Aspect | Early | Late |
+|--------|-------|------|
+| When key assigned | On CREATE (before save) | During SAVE (adjust_numbers) |
+| BDEF keyword | (none — default) | `late numbering` |
+| Draft support | Key available in draft | Temp key until activate |
+| Implementation | Determination on modify | Saver class adjust_numbers |
+| Number consumption | May waste numbers on discard | Only consumed on commit |
+| Complexity | Simple | More complex |
+| Typical use | UUID keys, simple sequences | Number ranges, external IDs |
+
+## Unmanaged Numbering
+
+For unmanaged BOs where the application fully controls key assignment.
+
+### BDEF
+
+```abap
+unmanaged implementation in class ZBP_I_ORDER unique;
+strict ( 2 );
+
+define behavior for ZI_Order alias Order
+lock master
+{
+  create;
+  update;
+  delete;
+}
+```
+
+### Handler — CREATE with Key Assignment
+
+```abap
+METHOD create.
+  LOOP AT entities ASSIGNING FIELD-SYMBOL(<entity>).
+    " Application assigns key
+    DATA(lv_id) = get_next_order_id( ).
+
+    INSERT VALUE #(
+      order_id    = lv_id
+      customer_id = <entity>-CustomerID
+      amount      = <entity>-Amount
+    ) INTO TABLE buffer_orders.
+
+    INSERT VALUE #(
+      %cid     = <entity>-%cid
+      order_id = lv_id
+    ) INTO TABLE mapped-order.
+  ENDLOOP.
+ENDMETHOD.
+```
+
+## Child Numbering
+
+```abap
+" BDEF — child with determination for numbering
+define behavior for ZI_OrderItem alias Item
+persistent table ztab_order_item
+lock dependent by _Order
+{
+  field ( readonly ) OrderID, ItemID;
+
+  update;
+  delete;
+
+  determination setItemID on modify { create; }
+}
+
+" Handler
+METHOD setItemID.
+  READ ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Item FIELDS ( OrderID ItemID ) WITH CORRESPONDING #( keys )
+    RESULT DATA(items).
+
+  " Get max item ID per order
+  TYPES: BEGIN OF ty_max,
+           order_id TYPE numc10,
+           max_item TYPE numc6,
+         END OF ty_max.
+  DATA lt_max TYPE SORTED TABLE OF ty_max WITH UNIQUE KEY order_id.
+
+  LOOP AT items INTO DATA(item) WHERE ItemID IS INITIAL.
+    IF NOT line_exists( lt_max[ order_id = item-OrderID ] ).
+      SELECT SINGLE FROM ztab_order_item
+        FIELDS MAX( item_id )
+        WHERE order_id = @item-OrderID
+        INTO @DATA(lv_max_item).
+      INSERT VALUE #( order_id = item-OrderID max_item = lv_max_item ) INTO TABLE lt_max.
+    ENDIF.
+
+    DATA(lv_next) = lt_max[ order_id = item-OrderID ]-max_item + 10.
+    lt_max[ order_id = item-OrderID ]-max_item = lv_next.
+
+    MODIFY ENTITIES OF ZI_Order IN LOCAL MODE
+      ENTITY Item UPDATE FIELDS ( ItemID )
+      WITH VALUE #( ( %tky = item-%tky  ItemID = lv_next ) ).
+  ENDLOOP.
+ENDMETHOD.
+```
+
+## Rules
+- Early numbering: simplest, key available immediately — use for UUID or simple sequences
+- Late numbering: key assigned at save — use for number ranges or external IDs
+- `late numbering` keyword in BDEF activates late numbering
+- Late numbering uses saver class `adjust_numbers` method
+- Child numbering: typically MAX+10 pattern (increment by 10 for insertion gaps)
+- Always filter `WHERE KeyField IS INITIAL` before assigning — skip records that already have keys
+- UUID keys: `cl_system_uuid=>create_uuid_x16_static( )` for RAP-safe UUID generation
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| Number range in early numbering determination | Wastes numbers on draft discard — use late numbering |
+| `MAX + 1` without lock in concurrent system | Use number range object or UUID |
+| Late numbering without `late numbering` in BDEF | Framework doesn't call adjust_numbers |
+| Assigning key to records that already have one | Filter `WHERE KeyField IS INITIAL` |
+| Item numbering by +1 | Use +10 for insertion gaps (SAP convention) |
+| Hardcoded key in test data | Use dynamic generation or %cid |

package/dist/knowledge/abap/rap-service-exposure.md

@@ -0,0 +1,163 @@
+# RAP Service Exposure — Projection CDS, Projection BDEF, Service Definition, Service Binding
+
+## Camadas
+
+```
+Service Binding (OData V4 UI)  ← endpoint
+Service Definition             ← quais entidades expor
+Projection BDEF                ← quais operacoes expor
+Projection CDS                 ← consumption layer
+Interface BDEF                 ← business logic
+Interface CDS                  ← data model
+Database Tables                ← persistencia
+```
+
+## Projection CDS — Root
+
+```abap
+@AccessControl.authorizationCheck: #CHECK
+@Metadata.allowExtensions: true
+@Search.searchable: true
+define root view entity ZC_Order
+  provider contract transactional_query
+  as projection on ZI_Order
+{
+  key OrderID,
+      @Search.defaultSearchElement: true
+      CustomerID,
+      OrderDate,
+      @Semantics.amount.currencyCode: 'CurrencyCode'
+      TotalAmount,
+      CurrencyCode,
+      Status,
+      CreatedBy, CreatedAt, LastChangedBy, LastChangedAt, LocalLastChangedAt,
+      _Item     : redirected to composition child ZC_OrderItem,
+      _Customer,
+      _Currency
+}
+```
+
+- `provider contract transactional_query` — obrigatorio para Fiori Elements com CRUD
+- `redirected to composition child ZC_OrderItem` — redireciona association para projection
+
+## Projection CDS — Child
+
+```abap
+@AccessControl.authorizationCheck: #CHECK
+@Metadata.allowExtensions: true
+define view entity ZC_OrderItem
+  as projection on ZI_OrderItem
+{
+  key OrderID,
+  key ItemID,
+      ProductID, Quantity,
+      @Semantics.amount.currencyCode: 'CurrencyCode'
+      ItemPrice,
+      CurrencyCode, LocalLastChangedAt,
+      _Order   : redirected to parent ZC_Order,
+      _Product
+}
+```
+
+- `redirected to parent ZC_Order` — filho aponta para projection do pai
+- Sem `provider contract` no filho (so root precisa)
+
+## provider contract
+
+| Contract | Uso |
+|----------|-----|
+| `transactional_query` | Fiori Elements com CRUD |
+| `transactional_interface` | Consumo programatico (API) |
+
+## Projection BDEF
+
+```abap
+projection;
+strict ( 2 );
+use draft;
+
+define behavior for ZC_Order alias Order
+use etag
+{
+  use create; use update; use delete;
+  use action Edit; use action Activate; use action Discard;
+  use action Resume; use action Prepare;
+  use action acceptOrder;
+  use association _Item { create; with draft; }
+}
+
+define behavior for ZC_OrderItem alias Item
+use etag
+{
+  use update; use delete;
+  use association _Order { with draft; }
+}
+```
+
+- `projection;` na primeira linha (nao `managed`)
+- `use draft;` obrigatorio se interface usa `with draft`
+- `use action` expoe operacoes da interface — deve expor TODAS as draft actions
+- Pode ter multiplas projections para o mesmo BO (admin vs viewer)
+
+## Service Definition
+
+```abap
+@EndUserText.label: 'Order Service'
+define service ZUI_ORDER {
+  expose ZC_Order       as Order;
+  expose ZC_OrderItem   as OrderItem;
+  expose /DMO/I_Customer as Customer;    " value help
+  expose /DMO/I_Product  as Product;     " value help
+  expose I_Currency      as Currency;    " value help
+}
+```
+
+- Expor **projections** (ZC_*), nunca interfaces (ZI_*)
+- Expor toda entidade referenciada em `@Consumption.valueHelpDefinition`
+- Aliases definem nome no OData $metadata
+
+## Service Binding
+
+Criado no ADT como objeto SRVB:
+- Tipo: `OData V4 - UI` (Fiori Elements)
+- Service Definition: `ZUI_ORDER`
+- Convencao: `ZUI_ORDER_O4` (V4) ou `ZUI_ORDER_O2` (V2)
+- Apos criar: **Publish** para ativar endpoint OData
+
+| Tipo | Uso | Draft UI |
+|------|-----|:--------:|
+| OData V4 - UI | Fiori Elements (recomendado) | SIM |
+| OData V4 - Web API | APIs programaticas | NAO |
+| OData V2 - UI | Apps Fiori legados | SIM |
+
+URL apos publish:
+```
+V4: /sap/opu/odata4/sap/zui_order_o4/0001/
+V2: /sap/opu/odata/sap/ZUI_ORDER_O2/
+```
+
+Multiplos bindings para o mesmo service definition:
+```
+ZUI_ORDER (Service Definition)
+├── ZUI_ORDER_O4  (OData V4 - UI)     → Fiori Elements
+├── ZUI_ORDER_O2  (OData V2 - UI)     → Apps legados
+└── ZAPI_ORDER    (OData V4 - Web API) → APIs externas
+```
+
+## Regras
+- Projection CDS root: sempre `provider contract transactional_query`
+- Associations: `redirected to composition child` / `redirected to parent`
+- Projection BDEF: expor TODAS as 5 draft actions
+- Service Definition: expor projections + entidades de value help
+- Service Binding: sempre publicar apos criar
+- OData V4 UI para apps novos, V2 so para legado
+
+## Anti-patterns
+| Errado | Correto |
+|--------|---------|
+| Expor ZI_* no Service Definition | Expor ZC_* |
+| Esquecer `provider contract transactional_query` | Fiori Elements nao funciona sem isso |
+| Nao redirecionar associations na projection | `redirected to composition child` obrigatorio |
+| Service Binding sem Publish | Endpoint nao fica acessivel |
+| OData V2 para app novo | OData V4 UI |
+| Nao expor entidade de value help | Value help nao aparece no Fiori |