@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/fiori/fiori-elements.md

@@ -0,0 +1,332 @@
+# Fiori Elements — Annotation-Driven UI Templates
+
+## List Report — Table + Filter Bar
+
+```xml
+<Annotations Target="Service.Products">
+    <!-- Filter bar fields -->
+    <Annotation Term="UI.SelectionFields">
+        <Collection>
+            <PropertyPath>Category</PropertyPath>
+            <PropertyPath>Price</PropertyPath>
+            <PropertyPath>Status</PropertyPath>
+        </Collection>
+    </Annotation>
+
+    <!-- Table columns -->
+    <Annotation Term="UI.LineItem">
+        <Collection>
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" PropertyPath="ProductID"/>
+            </Record>
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" PropertyPath="Name"/>
+                <PropertyValue Property="Label" String="Product Name"/>
+            </Record>
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" PropertyPath="Price"/>
+            </Record>
+            <Record Type="UI.DataFieldForAnnotation">
+                <PropertyValue Property="Target" AnnotationPath="@UI.DataPoint#Rating"/>
+                <PropertyValue Property="Label" String="Rating"/>
+            </Record>
+            <!-- Action button in table -->
+            <Record Type="UI.DataFieldForAction">
+                <PropertyValue Property="Label" String="Approve"/>
+                <PropertyValue Property="Action" String="Service.ApproveOrder"/>
+                <PropertyValue Property="InvocationGrouping"
+                    EnumMember="UI.OperationGroupingType/Isolated"/>
+            </Record>
+        </Collection>
+    </Annotation>
+</Annotations>
+```
+
+```json
+// manifest.json — List Report target
+{
+    "sap.ui5": {
+        "routing": {
+            "targets": {
+                "ProductsList": {
+                    "type": "Component",
+                    "id": "ProductsList",
+                    "name": "sap.fe.templates.ListReport",
+                    "options": {
+                        "settings": {
+                            "contextPath": "/Products",
+                            "variantManagement": "Page",
+                            "initialLoad": true,
+                            "navigation": {
+                                "Products": {
+                                    "detail": { "route": "ProductDetail" }
+                                }
+                            },
+                            "tableSettings": {
+                                "type": "ResponsiveTable",
+                                "selectAll": true,
+                                "selectionMode": "Multi"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Object Page — Header + Sections + Facets
+
+```xml
+<Annotations Target="Service.Product">
+    <Annotation Term="UI.HeaderInfo">
+        <Record>
+            <PropertyValue Property="TypeName" String="Product"/>
+            <PropertyValue Property="TypeNamePlural" String="Products"/>
+            <PropertyValue Property="Title">
+                <Record Type="UI.DataField">
+                    <PropertyValue Property="Value" PropertyPath="Name"/>
+                </Record>
+            </PropertyValue>
+            <PropertyValue Property="Description">
+                <Record Type="UI.DataField">
+                    <PropertyValue Property="Value" PropertyPath="Description"/>
+                </Record>
+            </PropertyValue>
+        </Record>
+    </Annotation>
+
+    <Annotation Term="UI.HeaderFacets">
+        <Collection>
+            <Record Type="UI.ReferenceFacet">
+                <PropertyValue Property="Target" AnnotationPath="@UI.DataPoint#Price"/>
+            </Record>
+            <Record Type="UI.ReferenceFacet">
+                <PropertyValue Property="Target" AnnotationPath="@UI.DataPoint#Stock"/>
+            </Record>
+        </Collection>
+    </Annotation>
+
+    <Annotation Term="UI.Facets">
+        <Collection>
+            <Record Type="UI.CollectionFacet">
+                <PropertyValue Property="Label" String="General Information"/>
+                <PropertyValue Property="ID" String="GeneralInfo"/>
+                <PropertyValue Property="Facets">
+                    <Collection>
+                        <Record Type="UI.ReferenceFacet">
+                            <PropertyValue Property="Target"
+                                AnnotationPath="@UI.FieldGroup#General"/>
+                        </Record>
+                    </Collection>
+                </PropertyValue>
+            </Record>
+            <Record Type="UI.ReferenceFacet">
+                <PropertyValue Property="Label" String="Sales Orders"/>
+                <PropertyValue Property="Target"
+                    AnnotationPath="SalesOrders/@UI.LineItem"/>
+            </Record>
+        </Collection>
+    </Annotation>
+
+    <Annotation Term="UI.FieldGroup" Qualifier="General">
+        <Record>
+            <PropertyValue Property="Data">
+                <Collection>
+                    <Record Type="UI.DataField">
+                        <PropertyValue Property="Value" PropertyPath="ProductID"/>
+                    </Record>
+                    <Record Type="UI.DataField">
+                        <PropertyValue Property="Value" PropertyPath="Category"/>
+                    </Record>
+                    <Record Type="UI.DataField">
+                        <PropertyValue Property="Value" PropertyPath="Price"/>
+                    </Record>
+                </Collection>
+            </PropertyValue>
+        </Record>
+    </Annotation>
+</Annotations>
+```
+
+```json
+// manifest.json — Object Page target
+{
+    "ProductDetail": {
+        "type": "Component",
+        "id": "ProductDetail",
+        "name": "sap.fe.templates.ObjectPage",
+        "options": {
+            "settings": {
+                "contextPath": "/Products",
+                "editableHeaderContent": true,
+                "showRelatedApps": true
+            }
+        }
+    }
+}
+```
+
+## Analytical List Page — Charts + Visual Filters
+
+```xml
+<Annotations Target="Service.SalesData">
+    <Annotation Term="UI.Chart">
+        <Record>
+            <PropertyValue Property="Title" String="Sales by Region"/>
+            <PropertyValue Property="ChartType" EnumMember="UI.ChartType/Column"/>
+            <PropertyValue Property="Dimensions">
+                <Collection><PropertyPath>Region</PropertyPath></Collection>
+            </PropertyValue>
+            <PropertyValue Property="Measures">
+                <Collection><PropertyPath>Sales</PropertyPath></Collection>
+            </PropertyValue>
+        </Record>
+    </Annotation>
+
+    <Annotation Term="UI.PresentationVariant">
+        <Record>
+            <PropertyValue Property="Visualizations">
+                <Collection>
+                    <AnnotationPath>@UI.Chart</AnnotationPath>
+                    <AnnotationPath>@UI.LineItem</AnnotationPath>
+                </Collection>
+            </PropertyValue>
+            <PropertyValue Property="SortOrder">
+                <Collection>
+                    <Record Type="Common.SortOrderType">
+                        <PropertyValue Property="Property" PropertyPath="Sales"/>
+                        <PropertyValue Property="Descending" Bool="true"/>
+                    </Record>
+                </Collection>
+            </PropertyValue>
+        </Record>
+    </Annotation>
+</Annotations>
+```
+
+## Draft Handling
+
+```xml
+<Annotations Target="Service.SalesOrder">
+    <Annotation Term="Common.DraftRoot">
+        <Record>
+            <PropertyValue Property="ActivationAction" String="Service.draftActivate"/>
+            <PropertyValue Property="EditAction" String="Service.draftEdit"/>
+            <PropertyValue Property="PreparationAction" String="Service.draftPrepare"/>
+        </Record>
+    </Annotation>
+</Annotations>
+```
+
+Required entity properties: `IsActiveEntity`, `HasActiveEntity`, `HasDraftEntity` (all `Edm.Boolean`).
+
+## Determining Actions — Object Page Footer
+
+```xml
+<Annotation Term="UI.Identification">
+    <Collection>
+        <Record Type="UI.DataFieldForAction">
+            <PropertyValue Property="Label" String="Approve"/>
+            <PropertyValue Property="Action" String="Service.ApproveOrder"/>
+            <PropertyValue Property="Determining" Bool="true"/>
+        </Record>
+    </Collection>
+</Annotation>
+```
+
+## Flexible Column Layout
+
+```json
+{
+    "sap.ui5": {
+        "routing": {
+            "config": {
+                "routerClass": "sap.f.routing.Router",
+                "flexibleColumnLayout": {
+                    "defaultTwoColumnLayoutType": "TwoColumnsMidExpanded",
+                    "defaultThreeColumnLayoutType": "ThreeColumnsMidExpanded"
+                }
+            },
+            "routes": [
+                { "pattern": ":?query:", "name": "List", "target": ["List"] },
+                { "pattern": "Items({key}):?query:", "name": "Detail",
+                  "target": ["List", "Detail"] },
+                { "pattern": "Items({key})/Sub({subKey}):?query:", "name": "SubDetail",
+                  "target": ["List", "Detail", "SubDetail"] }
+            ]
+        }
+    }
+}
+```
+
+## Building Blocks — Reusable Macros
+
+```xml
+<macros:Table id="tbl" contextPath="/Products"
+    metaPath="@com.sap.vocabularies.UI.v1.LineItem" readOnly="true"/>
+
+<macros:FilterBar id="fb" contextPath="/Products"
+    metaPath="@com.sap.vocabularies.UI.v1.SelectionFields"/>
+
+<macros:Form id="frm" contextPath="/Products"
+    metaPath="@com.sap.vocabularies.UI.v1.FieldGroup#General"/>
+```
+
+Available: `Table`, `Chart`, `FilterBar`, `Form`, `Field`, `MicroChart`, `ValueHelp`.
+
+## CDS Annotation Syntax (CAP)
+
+```cds
+annotate CatalogService.Products with @(
+    UI: {
+        HeaderInfo: {
+            TypeName: 'Product',
+            TypeNamePlural: 'Products',
+            Title: { Value: name }
+        },
+        SelectionFields: [ category, price, status ],
+        LineItem: [
+            { Value: ID },
+            { Value: name },
+            { Value: price }
+        ],
+        Facets: [
+            { $Type: 'UI.ReferenceFacet', Target: '@UI.FieldGroup#General', Label: 'General' }
+        ],
+        FieldGroup#General: {
+            Data: [
+                { Value: ID },
+                { Value: category },
+                { Value: price }
+            ]
+        }
+    }
+);
+```
+
+## Rules
+
+- Always define `UI.HeaderInfo` with `TypeName` + `TypeNamePlural` on Object Page entities
+- Use `UI.CollectionFacet` to group multiple `ReferenceFacet` under one section
+- Set `variantManagement: "Page"` for List Report variant persistence
+- Use `contextPath` (not `entitySet`) in manifest.json for V4-based Fiori Elements
+- Add `:?query:` to route patterns to preserve filter/variant state in URL
+- Set `initialLoad: true` only when data should load without user pressing Go
+- Use `UI.DataFieldForAction` inside `UI.LineItem` for table-row actions
+- Use `UI.DataFieldForAction` with `Determining: true` inside `UI.Identification` for footer actions
+- Navigation associations in `UI.Facets` use path syntax: `NavProperty/@UI.LineItem`
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Writing custom JS controllers for standard CRUD | Use annotations + draft handling |
+| Hardcoding column labels in XML annotations | Use `@Common.Label` on entity properties or i18n |
+| Using `entitySet` in manifest instead of `contextPath` | Use `contextPath` for OData V4 |
+| Mixing freestyle UI5 views with Fiori Elements | Use extension points or building blocks |
+| Omitting `TypeNamePlural` in `HeaderInfo` | Always set both `TypeName` and `TypeNamePlural` |
+| Defining sections without `ID` property | Always set `ID` on `CollectionFacet` for stable anchors |
+| Using `OneColumn` layout for master-detail | Use `TwoColumnsMidExpanded` |
+| Skipping `PresentationVariant` on Analytical List Page | Required for chart+table visualization binding |

package/dist/knowledge/fiori/fiori-side-effects.md

@@ -0,0 +1,107 @@
+# Fiori Side Effects — refresh automatico de campos e validacao inline
+
+Declarar no BDEF da interface (ZI_*), NAO na projection.
+
+## Sintaxe
+
+```abap
+define behavior for ZI_Order alias Order
+{
+  side effects
+  {
+    " campo afeta campo
+    field Quantity affects field TotalPrice;
+
+    " campo afeta multiplos campos
+    field Discount affects field TotalPrice, field NetPrice;
+
+    " multiplos campos trigam mesmo efeito
+    field Quantity, field UnitPrice affects field TotalPrice;
+
+    " campo afeta entity inteira (recarrega tudo)
+    field CurrencyCode affects entity Order;
+
+    " campo afeta filhos (recarrega association)
+    field OrderType affects entity _Item;
+
+    " validacao inline ao sair do campo
+    determine action Prepare executed on field CustomerID, field BeginDate;
+
+    " acao afeta entity
+    action acceptOrder affects entity Order;
+
+    " campo afeta feature control de acoes
+    field Status affects action acceptOrder, action rejectOrder;
+  }
+}
+```
+
+## Patterns
+
+### Campo calculado
+```abap
+" BDEF:
+determination calculateTotal on modify { field Quantity, UnitPrice; }
+side effects { field Quantity, field UnitPrice affects field TotalPrice; }
+```
+Side effect recarrega o campo. Determination faz o calculo. Ambos necessarios.
+
+### Validacao em tempo real
+```abap
+" BDEF:
+draft determine action Prepare { validation validateDates; validation validateCustomer; }
+side effects { determine action Prepare executed on field BeginDate, field EndDate, field CustomerID; }
+```
+Ao sair do campo, Fiori chama Prepare → backend roda validacoes → mostra erro inline.
+
+### Filho afeta pai
+```abap
+" No BDEF do filho (ZI_OrderItem):
+side effects { field Quantity, field ItemPrice affects entity _Order; }
+```
+Mudanca no item recarrega entidade pai (ex: recalcula total do pedido).
+
+### Pai afeta filhos
+```abap
+" No BDEF do pai (ZI_Order):
+side effects { field CurrencyCode affects entity _Item; }
+```
+
+### Feature control dinamico
+```abap
+side effects {
+  field OverallStatus affects action acceptTravel, action rejectTravel;
+}
+```
+Apos mudar Status, Fiori recalcula `get_instance_features` → habilita/desabilita botoes.
+
+## Tipos de efeito
+
+| Sintaxe | Recarrega |
+|---------|-----------|
+| `affects field X` | So o campo X (melhor performance) |
+| `affects field X, field Y` | Campos X e Y |
+| `affects entity Order` | Todos os campos da entidade |
+| `affects entity _Item` | Todos os filhos da association |
+| `affects action X` | Feature control da acao X |
+| `determine action Prepare executed on field X` | Executa validacoes do Prepare ao sair do campo |
+
+## Performance
+
+- Preferir `affects field` sobre `affects entity`
+- `determine action Prepare executed on field` gera roundtrip por campo — usar com moderacao
+- Agrupar: `field A, field B, field C affects field Total`
+
+## Regras
+- Declarar no BDEF da interface (ZI_*), nunca na projection
+- Side effect sem determination correspondente nao faz nada (recarrega dados inalterados)
+- `determine action Prepare` requer que Prepare liste as validacoes
+- `use action Prepare` obrigatorio na projection BDEF
+
+## Anti-patterns
+| Errado | Correto |
+|--------|---------|
+| Side effects na projection BDEF | Na interface BDEF |
+| `affects entity` para tudo | `affects field` quando possivel |
+| Prepare em todos os campos | So nos que precisam de validacao inline |
+| Side effect sem determination | Recarrega dado inalterado — sem efeito visivel |

package/dist/knowledge/fiori/fiori-valuelist.md

@@ -0,0 +1,144 @@
+# Fiori Value Help — @Consumption.valueHelpDefinition
+
+## Basico
+
+```abap
+@Consumption.valueHelpDefinition: [{
+  entity: { name: '/DMO/I_Agency', element: 'AgencyID' }
+}]
+AgencyID;
+```
+
+A entidade DEVE estar exposta no Service Definition.
+
+## Com filtros dependentes (additionalBinding)
+
+```abap
+@Consumption.valueHelpDefinition: [{
+  entity: { name: '/DMO/I_Connection', element: 'ConnectionID' },
+  additionalBinding: [
+    { localElement: 'CarrierID', element: 'AirlineID', usage: #FILTER_AND_RESULT }
+  ]
+}]
+ConnectionID;
+```
+
+| usage | Comportamento |
+|-------|---------------|
+| `#FILTER` | Filtra opcoes mas NAO preenche campo |
+| `#RESULT` | Preenche campo mas NAO filtra |
+| `#FILTER_AND_RESULT` | Filtra + preenche. O mais usado |
+
+## Cascata de value helps
+
+```abap
+" 1. Carrier — sem dependencia
+@Consumption.valueHelpDefinition: [{
+  entity: { name: '/DMO/I_Carrier', element: 'AirlineID' }
+}]
+CarrierID;
+
+" 2. Connection — depende do carrier
+@Consumption.valueHelpDefinition: [{
+  entity: { name: '/DMO/I_Connection', element: 'ConnectionID' },
+  additionalBinding: [
+    { localElement: 'CarrierID', element: 'AirlineID', usage: #FILTER_AND_RESULT }
+  ]
+}]
+ConnectionID;
+
+" 3. Flight — depende do carrier + connection
+@Consumption.valueHelpDefinition: [{
+  entity: { name: '/DMO/I_Flight', element: 'FlightDate' },
+  additionalBinding: [
+    { localElement: 'CarrierID',    element: 'AirlineID',    usage: #FILTER_AND_RESULT },
+    { localElement: 'ConnectionID', element: 'ConnectionID', usage: #FILTER_AND_RESULT }
+  ]
+}]
+FlightDate;
+```
+
+## Com texto (descricao)
+
+```abap
+@ObjectModel.text.element: ['AgencyName']
+@Consumption.valueHelpDefinition: [{
+  entity: { name: '/DMO/I_Agency', element: 'AgencyID' }
+}]
+AgencyID;
+
+@UI.textArrangement: #TEXT_FIRST
+_Agency.Name as AgencyName;
+```
+
+| textArrangement | Exibicao |
+|-----------------|----------|
+| `#TEXT_FIRST` | "ACME Travel (001)" |
+| `#TEXT_LAST` | "001 (ACME Travel)" |
+| `#TEXT_ONLY` | "ACME Travel" |
+| `#TEXT_SEPARATE` | Colunas separadas |
+
+Alternativa via association:
+```abap
+@ObjectModel.text.association: '_AgencyText'
+AgencyID;
+```
+
+## Com validacao frontend
+
+```abap
+@Consumption.valueHelpDefinition: [{
+  entity: { name: '/DMO/I_Customer', element: 'CustomerID' },
+  useForValidation: true
+}]
+CustomerID;
+```
+
+Valida no frontend se valor existe (evita roundtrip).
+
+## Multiplos value helps (qualifier)
+
+```abap
+@Consumption.valueHelpDefinition: [
+  { entity: { name: 'ZI_CustomerByID',   element: 'CustomerID' },
+    qualifier: 'ByID',   label: 'By ID' },
+  { entity: { name: 'ZI_CustomerByName', element: 'CustomerID' },
+    qualifier: 'ByName', label: 'By Name',
+    additionalBinding: [
+      { localElement: 'CustomerName', element: 'Name', usage: #RESULT }
+    ] }
+]
+CustomerID;
+```
+
+Aparece dropdown com opcoes "By ID" e "By Name" no Fiori.
+
+## Service Definition — expor entidades
+
+```abap
+define service ZUI_ORDER {
+  expose ZC_Order        as Order;
+  expose ZC_OrderItem    as OrderItem;
+  expose /DMO/I_Agency   as Agency;      " OBRIGATORIO para value help funcionar
+  expose /DMO/I_Customer as Customer;
+  expose /DMO/I_Carrier  as Carrier;
+  expose /DMO/I_Connection as Connection;
+  expose /DMO/I_Flight   as Flight;
+  expose I_Currency      as Currency;
+}
+```
+
+## Regras
+- `@Consumption.valueHelpDefinition` na projection CDS (ZC_*), nao na interface (ZI_*)
+- Entidade de value help DEVE estar no Service Definition
+- `#FILTER_AND_RESULT` e o usage padrao para filtros dependentes
+- `@ObjectModel.text.element` para exibir descricao junto com codigo
+- `useForValidation: true` para validacao frontend
+
+## Anti-patterns
+| Errado | Correto |
+|--------|---------|
+| Value help na interface (ZI_*) | Na projection (ZC_*) |
+| Entidade nao exposta no Service Definition | Value help nao aparece (sem erro) |
+| `#FILTER` quando quer preencher | `#FILTER_AND_RESULT` |
+| Sem `@ObjectModel.text.element` | Campo mostra so codigo sem descricao |