@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/abap/object-orientation.md

@@ -0,0 +1,298 @@
+# Object Orientation — classes, interfaces, inheritance, events
+
+## Class Definition
+
+```abap
+CLASS zcl_order_processor DEFINITION
+  PUBLIC FINAL CREATE PUBLIC.
+
+  PUBLIC SECTION.
+    TYPES: ty_order_id TYPE char10.
+    CONSTANTS: c_max_items TYPE i VALUE 999.
+
+    METHODS:
+      constructor IMPORTING iv_order_id TYPE ty_order_id,
+      process IMPORTING iv_input  TYPE string
+              RETURNING VALUE(rv_result) TYPE string
+              RAISING   zcx_order_error,
+      get_id RETURNING VALUE(rv_id) TYPE ty_order_id.
+
+    CLASS-METHODS:
+      factory IMPORTING iv_id TYPE ty_order_id
+              RETURNING VALUE(ro_inst) TYPE REF TO zcl_order_processor.
+
+  PROTECTED SECTION.
+    DATA mv_status TYPE char1.
+    METHODS validate.
+
+  PRIVATE SECTION.
+    DATA mv_order_id TYPE ty_order_id.
+    METHODS helper.
+
+ENDCLASS.
+
+CLASS zcl_order_processor IMPLEMENTATION.
+
+  METHOD constructor.
+    mv_order_id = iv_order_id.
+  ENDMETHOD.
+
+  METHOD process.
+    rv_result = |Processed: { iv_input }|.
+  ENDMETHOD.
+
+  METHOD get_id.
+    rv_id = mv_order_id.
+  ENDMETHOD.
+
+  METHOD factory.
+    ro_inst = NEW #( iv_id ).
+  ENDMETHOD.
+
+  METHOD validate.
+  ENDMETHOD.
+
+  METHOD helper.
+  ENDMETHOD.
+
+ENDCLASS.
+```
+
+## Visibility
+
+| Modifier | Class | Subclass | External |
+|---|---|---|---|
+| PUBLIC | Yes | Yes | Yes |
+| PROTECTED | Yes | Yes | No |
+| PRIVATE | Yes | No | No |
+
+## Instantiation Control
+
+```abap
+CREATE PUBLIC     " Anyone can instantiate
+CREATE PROTECTED  " Only class + subclasses
+CREATE PRIVATE    " Only within the class (use factory)
+```
+
+## Object Creation
+
+```abap
+" NEW operator — preferred
+DATA(zo_proc) = NEW zcl_order_processor( iv_order_id = '1000' ).
+
+" Inline chain
+DATA(lv_result) = NEW zcl_order_processor( '1000' )->process( `data` ).
+
+" Factory method
+DATA(zo_inst) = zcl_order_processor=>factory( '1000' ).
+
+" Static method call
+zcl_utility=>execute( ).
+```
+
+## Method Signatures
+
+```abap
+METHODS process
+  IMPORTING iv_required TYPE string
+            iv_optional TYPE string OPTIONAL
+            iv_default  TYPE i DEFAULT 10
+  EXPORTING ev_output   TYPE string
+  CHANGING  cv_data     TYPE string
+  RETURNING VALUE(rv_result) TYPE string
+  RAISING   zcx_my_exception.
+```
+
+## Interfaces
+
+```abap
+INTERFACE zif_processable PUBLIC.
+  TYPES ty_result TYPE string.
+  METHODS:
+    process IMPORTING iv_input TYPE string
+            RETURNING VALUE(rv_result) TYPE ty_result,
+    get_status RETURNING VALUE(rv_status) TYPE char1.
+ENDINTERFACE.
+
+CLASS zcl_impl DEFINITION PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES zif_processable.
+    ALIASES process FOR zif_processable~process.
+    ALIASES get_status FOR zif_processable~get_status.
+ENDCLASS.
+
+CLASS zcl_impl IMPLEMENTATION.
+  METHOD zif_processable~process.
+    rv_result = |Done: { iv_input }|.
+  ENDMETHOD.
+  METHOD zif_processable~get_status.
+    rv_status = 'A'.
+  ENDMETHOD.
+ENDCLASS.
+```
+
+## Interface Usage + Polymorphism
+
+```abap
+" Program to interface, not implementation
+DATA zo_proc TYPE REF TO zif_processable.
+zo_proc = NEW zcl_impl_a( ).
+zo_proc->process( `input` ).  " Calls zcl_impl_a
+
+zo_proc = NEW zcl_impl_b( ).
+zo_proc->process( `input` ).  " Calls zcl_impl_b
+```
+
+## Interface Inheritance
+
+```abap
+INTERFACE zif_extended PUBLIC.
+  INTERFACES zif_processable.
+  METHODS extended_method.
+ENDINTERFACE.
+```
+
+## Inheritance
+
+```abap
+CLASS zcl_child DEFINITION
+  INHERITING FROM zcl_parent
+  PUBLIC FINAL CREATE PUBLIC.
+
+  PUBLIC SECTION.
+    METHODS constructor IMPORTING iv_name TYPE string.
+    METHODS process REDEFINITION.
+ENDCLASS.
+
+CLASS zcl_child IMPLEMENTATION.
+  METHOD constructor.
+    super->constructor( iv_name ).
+  ENDMETHOD.
+  METHOD process.
+    super->process( ).
+    " Child-specific logic
+  ENDMETHOD.
+ENDCLASS.
+```
+
+## Abstract Classes
+
+```abap
+CLASS zcl_base DEFINITION ABSTRACT PUBLIC.
+  PUBLIC SECTION.
+    METHODS concrete_method.
+    METHODS abstract_method ABSTRACT.
+ENDCLASS.
+
+CLASS zcl_concrete DEFINITION
+  INHERITING FROM zcl_base FINAL PUBLIC.
+  PUBLIC SECTION.
+    METHODS abstract_method REDEFINITION.
+ENDCLASS.
+```
+
+## Type Checking and Casting
+
+```abap
+" Instance check
+IF zo_ref IS INSTANCE OF zif_processable.
+  DATA(zo_intf) = CAST zif_processable( zo_ref ).
+ENDIF.
+
+" Safe casting
+TRY.
+    DATA(zo_specific) = CAST zcl_specific( zo_general ).
+  CATCH cx_sy_move_cast_error.
+ENDTRY.
+
+" RTTI
+DATA(zo_descr) = CAST cl_abap_classdescr(
+  cl_abap_typedescr=>describe_by_object_ref( zo_ref ) ).
+```
+
+## Events
+
+```abap
+" Publisher
+CLASS zcl_publisher DEFINITION PUBLIC.
+  PUBLIC SECTION.
+    EVENTS data_changed
+      EXPORTING VALUE(ev_old) TYPE string
+                VALUE(ev_new) TYPE string.
+    METHODS set_data IMPORTING iv_data TYPE string.
+  PRIVATE SECTION.
+    DATA mv_data TYPE string.
+ENDCLASS.
+
+CLASS zcl_publisher IMPLEMENTATION.
+  METHOD set_data.
+    DATA(lv_old) = mv_data.
+    mv_data = iv_data.
+    RAISE EVENT data_changed
+      EXPORTING ev_old = lv_old ev_new = iv_data.
+  ENDMETHOD.
+ENDCLASS.
+
+" Subscriber
+CLASS zcl_subscriber DEFINITION PUBLIC.
+  PUBLIC SECTION.
+    METHODS on_changed FOR EVENT data_changed OF zcl_publisher
+      IMPORTING ev_old ev_new sender.
+ENDCLASS.
+
+" Registration
+SET HANDLER zo_subscriber->on_changed FOR zo_publisher.
+```
+
+## Exception Classes
+
+```abap
+CLASS zcx_order_error DEFINITION
+  INHERITING FROM cx_static_check
+  PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES if_t100_message.
+    METHODS constructor
+      IMPORTING textid   LIKE if_t100_message=>t100key OPTIONAL
+                previous LIKE previous OPTIONAL.
+ENDCLASS.
+```
+
+## Friendship
+
+```abap
+CLASS zcl_private DEFINITION FRIENDS zcl_tester.
+  PRIVATE SECTION.
+    DATA mv_secret TYPE string.
+ENDCLASS.
+" zcl_tester can access mv_secret
+```
+
+---
+
+## Rules
+
+- Prefer FINAL unless inheritance is explicitly needed
+- Program to interfaces, not implementations
+- Use CREATE PRIVATE + factory method for controlled instantiation
+- Use ALIASES to simplify interface method access
+- Keep classes focused — Single Responsibility Principle
+- Prefer composition over inheritance
+- Use cx_static_check for expected errors, cx_no_check for programming errors
+- RETURNING parameters enable functional chaining — prefer over EXPORTING when single output
+- Use ABSTRACT for template method pattern
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| `CREATE OBJECT oref TYPE zcl_class` | `NEW zcl_class( )` |
+| Giant class with 50+ methods | Split into focused classes + interface |
+| Public attributes modified externally | Use getter/setter methods |
+| Deep inheritance hierarchy (3+ levels) | Composition + interfaces |
+| Catching `cx_root` everywhere | Catch specific exception classes |
+| Empty CATCH blocks | At minimum log the error |
+| PROTECTED SECTION with many attributes | Keep PROTECTED minimal, prefer PRIVATE |
+| Static methods accessing instance data | Use instance methods or pass data as parameters |
+| Missing FINAL on leaf classes | Always add FINAL unless subclassing is intended |
+| Using FRIENDS for production code | FRIENDS only for unit test access |

package/dist/knowledge/abap/performance.md

@@ -0,0 +1,216 @@
+# ABAP Performance — SELECT, internal tables, buffering, code optimization
+
+## SELECT Optimization
+
+```abap
+" ONLY needed fields (never SELECT *)
+SELECT order_id, customer_id, status
+  FROM ztab_order
+  INTO TABLE @DATA(lt_orders).
+
+" Use INTO TABLE (not ENDSELECT loop)
+" BAD:
+SELECT * FROM ztab_order INTO @DATA(ls_order).
+  " process row by row — very slow
+ENDSELECT.
+
+" GOOD:
+SELECT * FROM ztab_order INTO TABLE @DATA(lt_orders).
+LOOP AT lt_orders INTO DATA(ls_order).
+  " process in memory — much faster
+ENDLOOP.
+
+" Use JOIN instead of nested SELECT
+" BAD:
+SELECT * FROM ztab_order INTO TABLE @DATA(lt_orders).
+LOOP AT lt_orders INTO DATA(ls_ord).
+  SELECT SINGLE name FROM ztab_customer
+    WHERE customer_id = @ls_ord-customer_id INTO @DATA(lv_name).
+ENDLOOP.
+
+" GOOD:
+SELECT o~order_id, o~customer_id, c~name
+  FROM ztab_order AS o
+  INNER JOIN ztab_customer AS c ON o~customer_id = c~customer_id
+  INTO TABLE @DATA(lt_joined).
+
+" Use FOR ALL ENTRIES (with empty check)
+IF lt_keys IS NOT INITIAL.
+  SELECT * FROM ztab_detail
+    FOR ALL ENTRIES IN @lt_keys
+    WHERE order_id = @lt_keys-order_id
+    INTO TABLE @DATA(lt_details).
+ENDIF.
+
+" Use aggregation in SQL
+" BAD:
+SELECT * FROM ztab_order INTO TABLE @DATA(lt_all).
+DATA(lv_sum) = REDUCE decfloat34( INIT s = 0
+  FOR wa IN lt_all NEXT s = s + wa-amount ).
+
+" GOOD:
+SELECT SINGLE SUM( amount ) FROM ztab_order INTO @DATA(lv_sum).
+
+" PACKAGE SIZE for millions of rows
+SELECT * FROM ztab_big INTO TABLE @DATA(lt_chunk) PACKAGE SIZE 10000.
+  " process chunk
+  CLEAR lt_chunk.
+ENDSELECT.
+
+" Existence check (not SELECT COUNT)
+" BAD:
+SELECT COUNT(*) FROM ztab_order WHERE order_id = @lv_id INTO @DATA(lv_cnt).
+IF lv_cnt > 0.
+
+" GOOD:
+SELECT SINGLE @abap_true FROM ztab_order
+  WHERE order_id = @lv_id INTO @DATA(lv_exists).
+IF lv_exists = abap_true.
+```
+
+## Internal Table Optimization
+
+```abap
+" Use correct table type for access pattern
+" Sequential processing → STANDARD TABLE
+" Frequent key lookup → SORTED TABLE (binary search O(log n))
+" Hash lookup → HASHED TABLE (O(1))
+
+" BAD: READ TABLE on STANDARD TABLE (linear scan O(n))
+DATA lt_std TYPE STANDARD TABLE OF zs_item WITH EMPTY KEY.
+READ TABLE lt_std WITH KEY order_id = lv_id INTO DATA(ls_found).
+
+" GOOD: SORTED TABLE (binary search)
+DATA lt_sorted TYPE SORTED TABLE OF zs_item WITH UNIQUE KEY order_id.
+DATA(ls_found2) = lt_sorted[ order_id = lv_id ].
+
+" GOOD: HASHED TABLE for large datasets
+DATA lt_hashed TYPE HASHED TABLE OF zs_item WITH UNIQUE KEY order_id.
+DATA(ls_found3) = lt_hashed[ order_id = lv_id ].
+
+" Use FIELD-SYMBOL in LOOP (no copy)
+" BAD:
+LOOP AT lt_items INTO DATA(ls_item).
+  ls_item-amount = ls_item-amount * 1.1.
+  MODIFY lt_items FROM ls_item.
+ENDLOOP.
+
+" GOOD:
+LOOP AT lt_items ASSIGNING FIELD-SYMBOL(<item>).
+  <item>-amount = <item>-amount * 1.1.
+ENDLOOP.
+
+" Use secondary keys for multiple access patterns
+DATA lt_multi TYPE TABLE OF zs_item
+  WITH EMPTY KEY
+  WITH NON-UNIQUE SORTED KEY by_customer COMPONENTS customer_id
+  WITH UNIQUE HASHED KEY by_id COMPONENTS order_id.
+
+DATA(ls_by_id) = lt_multi[ KEY by_id order_id = '1000' ].
+LOOP AT lt_multi USING KEY by_customer ASSIGNING FIELD-SYMBOL(<fs>)
+  WHERE customer_id = 'CUST100'.
+ENDLOOP.
+
+" Use FILTER (requires sorted/hashed key)
+DATA(lt_active) = FILTER #( lt_multi USING KEY by_customer
+  WHERE customer_id = 'CUST100' ).
+
+" DELETE ADJACENT DUPLICATES — SORT first
+SORT lt_items BY order_id.
+DELETE ADJACENT DUPLICATES FROM lt_items COMPARING order_id.
+```
+
+## Avoid Nested Loops
+
+```abap
+" BAD: O(n*m) — nested LOOP
+LOOP AT lt_orders INTO DATA(ls_order).
+  LOOP AT lt_items INTO DATA(ls_item) WHERE order_id = ls_order-order_id.
+    " process
+  ENDLOOP.
+ENDLOOP.
+
+" GOOD: O(n+m) — GROUP BY
+LOOP AT lt_items INTO DATA(ls_rep)
+  GROUP BY ( order_id = ls_rep-order_id )
+  ASSIGNING FIELD-SYMBOL(<group>).
+  LOOP AT GROUP <group> ASSIGNING FIELD-SYMBOL(<member>).
+    " process
+  ENDLOOP.
+ENDLOOP.
+
+" GOOD: O(n*log m) — SORTED TABLE inner
+DATA lt_items_sorted TYPE SORTED TABLE OF zs_item WITH NON-UNIQUE KEY order_id.
+lt_items_sorted = lt_items.
+LOOP AT lt_orders INTO ls_order.
+  LOOP AT lt_items_sorted INTO ls_item
+    WHERE order_id = ls_order-order_id.
+    " binary search on first access
+  ENDLOOP.
+ENDLOOP.
+```
+
+## String Optimization
+
+```abap
+" Use string templates (not CONCATENATE for multiple joins)
+DATA(lv_msg) = |Order { lv_id } for { lv_customer }|.
+
+" For large string building, use string_table + CONCATENATE LINES OF
+DATA lt_lines TYPE string_table.
+LOOP AT lt_data INTO DATA(ls_data).
+  APPEND |{ ls_data-field1 },{ ls_data-field2 }| TO lt_lines.
+ENDLOOP.
+CONCATENATE LINES OF lt_lines INTO DATA(lv_csv) SEPARATED BY cl_abap_char_utilities=>newline.
+```
+
+## Buffering Hints
+
+```abap
+" CDS View — enable buffering
+@AbapCatalog.buffering.status: #ACTIVE
+@AbapCatalog.buffering.type: #FULL           " Entire table cached
+@AbapCatalog.buffering.type: #SINGLE         " By primary key
+@AbapCatalog.buffering.type: #GENERIC        " By n key fields
+@AbapCatalog.buffering.numberOfKeyFields: 2  " For GENERIC
+
+" ABAP — bypass buffer when needed
+SELECT SINGLE * FROM ztab BYPASSING BUFFER WHERE id = @lv_id INTO @DATA(ls).
+```
+
+## Parallel Processing
+
+```abap
+" AMDP / CDS for DB-level parallel processing
+" Background jobs for long-running tasks
+
+" NEW with async RFC (only when truly needed)
+CALL FUNCTION 'ZFUNC' STARTING NEW TASK 'TASK1'
+  PERFORMING callback ON END OF TASK
+  EXPORTING iv_param = lv_value.
+```
+
+## Rules
+- SELECT only needed fields — `SELECT *` reads unnecessary data
+- INTO TABLE, not ENDSELECT — avoid row-by-row processing
+- JOIN instead of SELECT in LOOP — single DB roundtrip
+- FOR ALL ENTRIES: always check IS NOT INITIAL before
+- Aggregation in SQL, not in ABAP — let the DB do the math
+- SORTED/HASHED tables for frequent key lookups
+- FIELD-SYMBOL in LOOP for modification — no copy overhead
+- PACKAGE SIZE for millions of rows — avoid memory overflow
+- Existence check: `SELECT SINGLE @abap_true` instead of `COUNT(*)`
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| `SELECT *` in production | Select only needed fields |
+| `SELECT ... ENDSELECT` (row by row) | `SELECT ... INTO TABLE` |
+| SELECT inside LOOP | JOIN or FOR ALL ENTRIES |
+| FOR ALL ENTRIES without empty check | `IF itab IS NOT INITIAL` |
+| `LOOP INTO DATA(wa)` for modification | `LOOP ASSIGNING FIELD-SYMBOL(<fs>)` |
+| Nested LOOP for lookup O(n*m) | HASHED/SORTED table or GROUP BY |
+| `SELECT COUNT(*)` for existence | `SELECT SINGLE @abap_true` |
+| Aggregation in ABAP LOOP | `SELECT SUM/AVG/COUNT` in SQL |
+| STANDARD TABLE + READ TABLE (linear) | SORTED TABLE (binary) or HASHED (hash) |
+| `CONCATENATE` in LOOP for large strings | Collect in string_table, join once |

package/dist/knowledge/abap/rap-abstract-entities.md

@@ -0,0 +1,206 @@
+# RAP Abstract Entities — action parameters and function returns
+
+## What They Are
+
+Abstract entities define structured types without DB persistence. Used for:
+- Action input parameters
+- Action/function return types
+- Complex result structures
+
+## Defining Abstract Entity
+
+```abap
+@EndUserText.label: 'Action Parameter: Reject Reason'
+define abstract entity ZA_RejectParams
+{
+  reason     : abap.char(256);
+  note       : abap.string;
+  reject_date : abap.dats;
+}
+```
+
+```abap
+@EndUserText.label: 'Action Result: Confirmation'
+define abstract entity ZA_ConfirmResult
+{
+  order_id    : abap.numc(10);
+  status      : abap.char(1);
+  message     : abap.char(256);
+  changed_at  : abp_lastchange_tstmpl;
+}
+```
+
+## Using in BDEF — Action with Parameters
+
+```abap
+define behavior for ZI_Order alias Order
+{
+  " Action with input parameter
+  action rejectOrder parameter ZA_RejectParams result [1] $self;
+
+  " Action with result type (not $self)
+  action confirmOrder result [1] ZA_ConfirmResult;
+
+  " Action with parameter AND custom result
+  action processOrder parameter ZA_ProcessParams result [1] ZA_ProcessResult;
+
+  " Action without parameter, with result
+  action acceptOrder result [1] $self;
+
+  " Action without parameter, without result
+  action cancelOrder;
+
+  " Static action with parameter
+  static action bulkProcess parameter ZA_BulkParams result [0..*] ZA_BulkResult;
+}
+```
+
+## Handler — Action with Parameter
+
+```abap
+METHOD rejectOrder.
+  " req.data contains the parameter fields
+  " keys contains the entity keys
+
+  MODIFY ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order
+    UPDATE FIELDS ( Status RejectReason RejectDate )
+    WITH VALUE #( FOR key IN keys
+      ( %tky        = key-%tky
+        Status      = 'X'
+        RejectReason = key-%param-reason
+        RejectDate   = key-%param-reject_date ) )
+    FAILED failed
+    REPORTED reported.
+
+  " Return updated instance
+  READ ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order ALL FIELDS
+    WITH CORRESPONDING #( keys )
+    RESULT DATA(orders).
+
+  result = VALUE #( FOR order IN orders
+    ( %tky = order-%tky  %param = order ) ).
+ENDMETHOD.
+```
+
+## Handler — Action with Custom Result
+
+```abap
+METHOD confirmOrder.
+  MODIFY ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order
+    UPDATE FIELDS ( Status )
+    WITH VALUE #( FOR key IN keys
+      ( %tky = key-%tky  Status = 'A' ) )
+    FAILED failed
+    REPORTED reported.
+
+  READ ENTITIES OF ZI_Order IN LOCAL MODE
+    ENTITY Order FIELDS ( OrderID Status LastChangedAt )
+    WITH CORRESPONDING #( keys )
+    RESULT DATA(orders).
+
+  result = VALUE #( FOR order IN orders
+    ( %tky = order-%tky
+      %param = VALUE ZA_ConfirmResult(
+        order_id   = order-OrderID
+        status     = order-Status
+        message    = |Order { order-OrderID } confirmed|
+        changed_at = order-LastChangedAt ) ) ).
+ENDMETHOD.
+```
+
+## Handler — Static Action with Parameter
+
+```abap
+METHOD bulkProcess.
+  " Static action — no entity keys, only parameter data
+  DATA(lv_params) = keys[ 1 ]-%param.
+
+  " Process based on parameter
+  SELECT * FROM ztab_order
+    WHERE status = @lv_params-filter_status
+    INTO TABLE @DATA(lt_orders).
+
+  " ... process orders ...
+
+  result = VALUE #( FOR order IN lt_orders
+    ( %param = VALUE ZA_BulkResult(
+        order_id = order-order_id
+        processed = abap_true ) ) ).
+ENDMETHOD.
+```
+
+## Abstract Entity with Associations (for complex results)
+
+```abap
+@EndUserText.label: 'Order Summary Result'
+define abstract entity ZA_OrderSummary
+{
+  order_id     : abap.numc(10);
+  customer_id  : kunnr;
+  total_amount : abap.curr(17,2);
+  currency_code : abap.cuky(5);
+  item_count   : abap.int4;
+  status_text  : abap.char(20);
+}
+```
+
+## Projection BDEF — Exposing Actions with Parameters
+
+```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 rejectOrder;     " Parameter inherited from interface
+  use action confirmOrder;    " Result type inherited from interface
+  use action acceptOrder;
+  use action bulkProcess;
+}
+```
+
+## Fiori UI — Action Dialog for Parameters
+
+When an action has a parameter, Fiori Elements automatically generates a dialog with input fields for the abstract entity's fields.
+
+```abap
+" Metadata Extension — customize action parameter dialog
+@Metadata.layer: #CORE
+annotate entity ZA_RejectParams with
+{
+  @UI.defaultValue: 'Rejected by user'
+  reason;
+
+  @UI.hidden: true
+  reject_date;
+}
+```
+
+## Rules
+- Abstract entities: `define abstract entity` — no DB table, no persistence
+- Use for action parameters when more than 1-2 simple fields needed
+- `$self` returns the entity itself; custom abstract entity returns different structure
+- `result [1]` = exactly one result; `result [0..*]` = multiple results
+- `%param` in handler: `key-%param-fieldname` for parameter fields
+- Static actions: no entity key, parameter accessed via `keys[ 1 ]-%param`
+- Abstract entities can use data elements for labels and search helps
+- Fiori auto-generates dialog for action parameters based on abstract entity fields
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| Using STRING for action params that need structure | Define abstract entity |
+| `result [1] $self` when return differs from entity | Use custom abstract entity as result |
+| Accessing `keys-%param` without checking keys is not empty | Guard with `IF keys IS NOT INITIAL` |
+| Abstract entity with too many fields (>10) | Keep focused — split into multiple if complex |
+| Missing labels on abstract entity fields | Use data elements or `@EndUserText.label` |
+| Forgetting to `use action` in projection BDEF | Action not available in Fiori |