@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/cap/fiori-integration.md

@@ -0,0 +1,303 @@
+# Fiori Integration — CAP UI Annotations and Drafts
+
+## Enable Drafts
+
+```cds
+// Enable on the SERVICE projection, not the base entity
+service AdminService {
+  entity Books as projection on my.Books;
+}
+annotate AdminService.Books with @odata.draft.enabled;
+```
+
+## HeaderInfo
+
+```cds
+annotate CatalogService.Books with @UI.HeaderInfo: {
+  TypeName       : 'Book',
+  TypeNamePlural : 'Books',
+  Title          : { Value: title },
+  Description    : { Value: author.name },
+  ImageUrl       : coverImageUrl,
+  TypeImageUrl   : 'sap-icon://education'
+};
+```
+
+## SelectionFields (Filter Bar)
+
+```cds
+annotate CatalogService.Books with @UI.SelectionFields: [
+  title,
+  author_ID,
+  genre_code,
+  price
+];
+```
+
+## LineItem (Table Columns)
+
+```cds
+annotate CatalogService.Books with @UI.LineItem: [
+  { Value: title, Label: 'Title' },
+  { Value: author.name, Label: 'Author' },
+  { Value: stock, Label: 'In Stock' },
+  { Value: price, Label: 'Price' },
+  {
+    $Type: 'UI.DataFieldForAction',
+    Action: 'CatalogService.order',
+    Label: 'Order',
+    Inline: true
+  },
+  {
+    $Type: 'UI.DataFieldForAnnotation',
+    Target: '@UI.DataPoint#rating',
+    Label: 'Rating'
+  }
+];
+```
+
+## DataPoint
+
+```cds
+annotate CatalogService.Books with @UI.DataPoint#rating: {
+  Value: rating,
+  Visualization: #Rating,
+  TargetValue: 5
+};
+
+annotate CatalogService.Books with @UI.DataPoint#stock: {
+  Value: stock,
+  Criticality: stockCriticality
+};
+```
+
+## Facets (Object Page Sections)
+
+```cds
+annotate CatalogService.Books with @UI.Facets: [
+  {
+    $Type  : 'UI.ReferenceFacet',
+    ID     : 'GeneralFacet',
+    Target : '@UI.FieldGroup#General',
+    Label  : 'General'
+  },
+  {
+    $Type  : 'UI.ReferenceFacet',
+    ID     : 'ReviewsFacet',
+    Target : 'reviews/@UI.LineItem',
+    Label  : 'Reviews'
+  },
+  {
+    $Type  : 'UI.CollectionFacet',
+    ID     : 'DetailsFacet',
+    Label  : 'Details',
+    Facets : [
+      { $Type: 'UI.ReferenceFacet', Target: '@UI.FieldGroup#Pricing' },
+      { $Type: 'UI.ReferenceFacet', Target: '@UI.FieldGroup#Availability' }
+    ]
+  }
+];
+```
+
+## FieldGroup
+
+```cds
+annotate CatalogService.Books with @UI.FieldGroup#General: {
+  Data: [
+    { Value: title },
+    { Value: author_ID, Label: 'Author' },
+    { Value: genre_code, Label: 'Genre' },
+    { Value: descr, Label: 'Description' }
+  ]
+};
+```
+
+## Value Helps
+
+```cds
+// Simple (auto value list)
+@cds.odata.valuelist
+entity Genres { ... }
+
+// Custom value help with parameters
+annotate CatalogService.Books with {
+  author_ID @Common.ValueList: {
+    Label: 'Authors',
+    CollectionPath: 'Authors',
+    Parameters: [
+      {
+        $Type: 'Common.ValueListParameterInOut',
+        LocalDataProperty: author_ID,
+        ValueListProperty: 'ID'
+      },
+      {
+        $Type: 'Common.ValueListParameterDisplayOnly',
+        ValueListProperty: 'name'
+      }
+    ]
+  };
+};
+```
+
+## Text and TextArrangement
+
+```cds
+annotate CatalogService.Books with {
+  @Common.Text: author.name
+  @Common.TextArrangement: #TextOnly
+  author_ID;
+
+  @Common.Text: genre.name
+  @Common.TextArrangement: #TextFirst
+  genre_code;
+};
+```
+
+| Value | Display | Example |
+|---|---|---|
+| `#TextOnly` | Text only, hide ID | "Fiction" |
+| `#TextFirst` | Text (ID) | "Fiction (FIC)" |
+| `#TextLast` | (ID) Text | "(FIC) Fiction" |
+| `#TextSeparate` | Separate columns | ID and text apart |
+
+## Field Control
+
+```cds
+// Static
+annotate CatalogService.Books with {
+  ID @UI.Hidden;
+  createdAt @UI.Hidden;
+  modifiedAt @readonly;
+};
+
+// Dynamic field control values: 0=Hidden, 1=Mandatory, 3=Optional, 7=ReadOnly
+```
+
+## Criticality (Colors)
+
+```cds
+// In handler: set criticality field value
+// 0=Neutral(grey), 1=Negative(red), 2=Critical(yellow), 3=Positive(green)
+this.after('READ', 'Orders', orders => {
+  for (const order of orders) {
+    switch (order.status) {
+      case 'completed': order.criticality = 3; break;
+      case 'pending':   order.criticality = 2; break;
+      case 'cancelled': order.criticality = 1; break;
+      default:          order.criticality = 0;
+    }
+  }
+});
+
+// In annotation
+annotate CatalogService.Orders with @UI.LineItem: [
+  { Value: status, Criticality: criticality }
+];
+```
+
+## Actions in UI
+
+```cds
+// Bound actions in CDS
+service OrderService {
+  entity Orders { ... } actions {
+    action confirm();
+    action cancel(reason: String);
+  };
+}
+
+// In LineItem (table row action)
+annotate OrderService.Orders with @UI.LineItem: [
+  {
+    $Type: 'UI.DataFieldForAction',
+    Action: 'OrderService.confirm',
+    Label: 'Confirm'
+  }
+];
+
+// In Identification (header action on object page)
+annotate OrderService.Orders with @UI.Identification: [
+  {
+    $Type: 'UI.DataFieldForAction',
+    Action: 'OrderService.cancel',
+    Label: 'Cancel Order'
+  }
+];
+
+// Action availability (conditional)
+annotate OrderService.Orders with actions {
+  confirm @Core.OperationAvailable: {
+    $edmJson: { $Eq: [{ $Path: 'status' }, 'pending'] }
+  };
+};
+```
+
+## Side Effects
+
+```cds
+annotate AdminService.OrderItems with @Common.SideEffects: {
+  SourceProperties: [quantity],
+  TargetProperties: ['_parent/total']
+};
+```
+
+## Semantic Key
+
+```cds
+annotate CatalogService.Books with @Common.SemanticKey: [isbn];
+```
+
+## Project Structure
+
+```
+app/
+├── browse/
+│   └── annotations.cds     # Browse-specific annotations
+├── admin/
+│   └── annotations.cds     # Admin-specific annotations
+├── common.cds              # Shared field labels
+└── index.html              # Test page
+srv/
+db/
+```
+
+## Separation of Concerns
+
+```cds
+// app/common.cds — shared labels
+annotate CatalogService.Books with {
+  ID    @title: '{i18n>ID}';
+  title @title: '{i18n>Title}';
+};
+
+// app/browse/annotations.cds — app-specific UI
+annotate CatalogService.Books with @UI: {
+  SelectionFields: [title, genre_code],
+  LineItem: [
+    { Value: title },
+    { Value: author.name }
+  ]
+};
+```
+
+## Rules
+
+- Enable `@odata.draft.enabled` on service projection, not base entity
+- Only compositions are editable in drafts; associations are read-only
+- Action names in annotations must be fully qualified: `ServiceName.actionName`
+- `$Type: 'UI.DataFieldForAction'` for actions; `$Type: 'UI.DataFieldForAnnotation'` for DataPoints
+- `ReferenceFacet` points to a FieldGroup or child LineItem; `CollectionFacet` groups facets
+- Criticality is an integer field computed in handler, referenced by annotation
+- Keep annotations in `app/` folder, separate from `srv/` and `db/`
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Pattern |
+|---|---|
+| `@odata.draft.enabled` on base entity in `db/` | Enable on service projection in `srv/` or `app/` |
+| Action: `Action: 'confirm'` (unqualified) | `Action: 'OrderService.confirm'` (fully qualified) |
+| Editing associations in draft | Only compositions are editable in drafts |
+| Annotations mixed into `db/schema.cds` | Annotations belong in `app/` folder |
+| Criticality as string (`'Positive'`) | Criticality is integer: 0, 1, 2, 3 |
+| `UI.FieldGroup` without `#qualifier` when multiple exist | Use `@UI.FieldGroup#Name` for each group |
+| ValueList without `InOut` parameter | Always include `ValueListParameterInOut` for the binding field |

package/dist/knowledge/cap/service-definitions.md

@@ -0,0 +1,287 @@
+# Service Definitions — CAP Service Design and Exposure
+
+## Basic Service
+
+```cds
+using { my.bookshop as my } from '../db/schema';
+
+service CatalogService @(path: '/browse') {
+  entity Books as projection on my.Books;
+  entity Authors as projection on my.Authors;
+}
+```
+
+## Projections
+
+```cds
+// Column selection + exclusion
+service CatalogService {
+  entity Books as projection on my.Books {
+    *, author.name as author
+  } excluding { createdBy, modifiedBy };
+}
+
+// With filtering
+service CatalogService {
+  entity AvailableBooks as projection on my.Books {
+    key ID, title, price
+  } where stock > 0;
+}
+
+// Calculated fields in projection
+service CatalogService {
+  entity Books as projection on my.Books {
+    *,
+    author.name as author,
+    price * 0.9 as discountedPrice : Decimal
+  };
+}
+```
+
+## Actions and Functions
+
+```cds
+service OrderService {
+  // Unbound action (service-level, changes state)
+  action cancelOrder(orderID: UUID, reason: String) returns {
+    success: Boolean;
+    message: String;
+  };
+
+  // Unbound function (read-only)
+  function getOrderCount() returns Integer;
+  function getBooksByGenre(genre: String) returns array of Books;
+
+  // Bound actions (entity-level)
+  entity Products {
+    key ID : UUID;
+    name   : String;
+    price  : Decimal;
+    stock  : Integer;
+  } actions {
+    action discount(percent: Decimal) returns Decimal;
+    function getStock() returns Integer;
+  };
+}
+```
+
+## Complex Action Types
+
+```cds
+service OrderService {
+  type OrderResult : {
+    success : Boolean;
+    orderID : UUID;
+    message : String;
+    items   : array of {
+      productID : UUID;
+      quantity  : Integer;
+      price     : Decimal;
+    };
+  };
+
+  action placeOrder(order: OrderInput) returns OrderResult;
+}
+```
+
+## Service Configuration
+
+```cds
+// Read-only entity
+service CatalogService {
+  @readonly
+  entity Authors as projection on my.Authors;
+}
+
+// Insert-only (audit log pattern)
+service LogService {
+  @insertonly
+  entity AuditLog as projection on my.AuditLog;
+}
+
+// Draft-enabled
+service AdminService {
+  @odata.draft.enabled
+  entity Books as projection on my.Books;
+}
+```
+
+## Access Control
+
+```cds
+service MyService {
+  @requires: 'authenticated-user'
+  entity SensitiveData { ... }
+
+  @requires: ['admin', 'support']
+  action adminOperation() returns String;
+}
+```
+
+## Protocol Configuration
+
+```cds
+// Default: OData V4
+service CatalogService { ... }
+
+// REST
+service RESTService @(protocol: 'rest') { ... }
+
+// Multiple protocols
+@protocol: ['odata', 'rest']
+service MultiService { ... }
+
+// Internal only (no external access)
+@protocol: 'none'
+service InternalService { ... }
+```
+
+## Service Extension
+
+```cds
+extend service CatalogService with {
+  entity FeaturedBooks as projection on my.Books where featured = true;
+}
+```
+
+## External Service Integration
+
+```cds
+// Define external service model
+service ExternalAPI {
+  entity BusinessPartners { ... }
+}
+
+// Use in local service
+using { ExternalAPI as ext } from '../external';
+
+service MyService {
+  entity LocalPartners as projection on ext.BusinessPartners;
+}
+```
+
+```json
+// package.json — external service config
+{
+  "cds": {
+    "requires": {
+      "ExternalAPI": {
+        "kind": "odata-v2",
+        "credentials": {
+          "url": "https://api.example.com"
+        }
+      }
+    }
+  }
+}
+```
+
+## Handler Implementation
+
+```js
+const cds = require('@sap/cds');
+
+module.exports = class OrderService extends cds.ApplicationService {
+  async init() {
+    const { Products, Orders } = this.entities;
+
+    this.before('CREATE', Orders, this.validateOrder);
+    this.on('cancelOrder', this.onCancelOrder);
+    this.on('discount', Products, this.onDiscount);
+
+    return super.init();
+  }
+
+  async validateOrder(req) {
+    if (!req.data.items?.length) req.reject(400, 'Order must have items');
+  }
+
+  async onCancelOrder(req) {
+    const { orderID, reason } = req.data;
+    await UPDATE('Orders', orderID).set({ status: 'cancelled', reason });
+    return { success: true, message: 'Order cancelled' };
+  }
+
+  async onDiscount(req) {
+    const { ID } = req.params[0];
+    const { percent } = req.data;
+    const product = await SELECT.one.from('Products', ID);
+    const newPrice = product.price * (1 - percent / 100);
+    await UPDATE('Products', ID).set({ price: newPrice });
+    return newPrice;
+  }
+}
+```
+
+## Complete Multi-Service Example
+
+```cds
+using { sap.capire.bookshop as db } from '../db/schema';
+
+// Public catalog (read-only)
+service CatalogService @(path: '/browse') {
+  @readonly
+  entity Books as projection on db.Books {
+    key ID, title, descr, price, stock,
+    author { key ID, name }
+  } excluding { createdBy, modifiedBy }
+    where stock > 0;
+
+  @readonly
+  entity Authors as projection on db.Authors;
+
+  @requires: 'authenticated-user'
+  action submitOrder(book: UUID, quantity: Integer) returns {
+    orderID: UUID;
+    status: String;
+  };
+}
+
+// Admin (full CRUD + drafts)
+service AdminService @(path: '/admin') {
+  @odata.draft.enabled
+  entity Books as projection on db.Books;
+
+  @odata.draft.enabled
+  entity Authors as projection on db.Authors;
+
+  @requires: 'admin'
+  action bulkUpdatePrices(updates: array of {
+    book: UUID;
+    newPrice: Decimal;
+  }) returns { updated: Integer; };
+}
+
+// REST API for external consumers
+service PublicAPI @(protocol: 'rest', path: '/api/v1') {
+  entity PublicBooks as projection on db.Books {
+    key ID, title, price
+  } where published = true;
+
+  function getFeaturedBooks(limit: Integer) returns array of PublicBooks;
+}
+```
+
+## Rules
+
+- Actions change state; functions are read-only — use the correct keyword
+- Bound actions are defined inside `entity { ... } actions { ... }` block
+- Unbound actions are defined directly in the service body
+- Projections should expose only what the consumer needs — minimize surface area
+- `@readonly` prevents INSERT/UPDATE/DELETE at framework level
+- `@protocol: 'none'` hides service from external access completely
+- Service path defaults to service name if `@path` not specified
+- `@requires` accepts a single role string or array of roles (any match grants access)
+- Handler file auto-resolved: `ServiceName` looks for `srv/service-name.js`
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Pattern |
+|---|---|
+| Exposing all fields: `entity Books as projection on my.Books` without filtering | Use `excluding` or explicit column list to limit exposed fields |
+| Using `action` for read-only operations | Use `function` for queries that don't change state |
+| Single monolithic service for all consumers | Separate services per consumer: catalog, admin, API |
+| `@requires` on service level blocking all access | Apply `@requires` on individual entities/actions for granularity |
+| Defining entities directly in service (not as projections) | Project from `db/schema.cds` entities to keep single source of truth |
+| Missing `@path` resulting in naming collisions | Always set explicit `@path` on services |
+| External service without `cds.requires` config | Always configure credentials/URL in `package.json` |