Initial commit

2025-11-30 08:55:20 +08:00
commit fee63d563a
11 changed files with 3748 additions and 0 deletions
--- a/references/annotations.md
+++ b/references/annotations.md
@@ -0,0 +1,415 @@
+# Annotations Reference
+
+Comprehensive reference for working with annotations in SAP Fiori tools.
+
+## Table of Contents
+
+1. [Language Server Features](#language-server-features)
+2. [Supported File Types](#supported-file-types)
+3. [Supported Vocabularies](#supported-vocabularies)
+4. [Code Completion](#code-completion)
+5. [Micro-Snippets](#micro-snippets)
+6. [Diagnostics](#diagnostics)
+7. [Internationalization](#internationalization)
+8. [Service Modeler](#service-modeler)
+9. [Common Annotation Patterns](#common-annotation-patterns)
+
+---
+
+## Language Server Features
+
+SAP Fiori tools provides two annotation language servers:
+
+| Server | File Type | Scope |
+|--------|-----------|-------|
+| CDS OData Language Server | `.cds` files | CAP projects |
+| XML Annotation Language Server | `annotation.xml` files | All projects |
+
+### Capabilities
+
+- Code completion for annotation targets, terms, attributes, values
+- Validation against OData vocabularies and project metadata
+- Navigation to referenced annotations
+- Quick vocabulary information views
+- Internationalization (i18n) support
+
+---
+
+## Supported File Types
+
+### CDS Annotation Files
+
+Location: CAP project `.cds` files
+
+```cds
+annotate CatalogService.Products with @(
+    UI: {
+        HeaderInfo: {
+            TypeName: 'Product',
+            TypeNamePlural: 'Products',
+            Title: { Value: name }
+        },
+        LineItem: [
+            { Value: ID },
+            { Value: name },
+            { Value: price }
+        ]
+    }
+);
+```
+
+### XML Annotation Files
+
+Location: `webapp/annotations/*.xml`
+
+**Prerequisites**:
+1. OData Service with local metadata copy
+2. Path specified in `manifest.json` as local `Uri`
+3. Metadata contains `<edm:Schema>` definitions
+4. Single `EntityContainer` in metadata
+5. Valid XML file with `</edmx:DataServices/Schema>` nodes
+
+**Manifest Configuration**:
+```json
+{
+  "sap.app": {
+    "dataSources": {
+      "mainService": {
+        "uri": "/sap/opu/odata/sap/SERVICE/",
+        "type": "OData",
+        "settings": {
+          "localUri": "localService/metadata.xml",
+          "annotations": ["annotation"]
+        }
+      },
+      "annotation": {
+        "type": "ODataAnnotation",
+        "uri": "annotations/annotation.xml"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Supported Vocabularies
+
+### OASIS OData v4 Vocabularies
+
+| Vocabulary | Namespace | Description |
+|------------|-----------|-------------|
+| Core | Org.OData.Core.V1 | Core vocabulary terms |
+| Capabilities | Org.OData.Capabilities.V1 | Service capabilities |
+| Aggregation | Org.OData.Aggregation.V1 | Aggregation support |
+| Authorization | Org.OData.Authorization.V1 | Authorization schemes |
+| JSON | Org.OData.JSON.V1 | JSON-related terms |
+| Measures | Org.OData.Measures.V1 | Units of measure |
+| Repeatability | Org.OData.Repeatability.V1 | Request repeatability |
+| Temporal | Org.OData.Temporal.V1 | Temporal data |
+| Validation | Org.OData.Validation.V1 | Data validation |
+
+### SAP OData Vocabularies
+
+| Vocabulary | Namespace | Description |
+|------------|-----------|-------------|
+| Analytics | com.sap.vocabularies.Analytics.v1 | Analytical annotations |
+| CodeList | com.sap.vocabularies.CodeList.v1 | Code list definitions |
+| Common | com.sap.vocabularies.Common.v1 | Common terms |
+| Communication | com.sap.vocabularies.Communication.v1 | Contact information |
+| DataIntegration | com.sap.vocabularies.DataIntegration.v1 | Data integration |
+| DirectEdit | com.sap.vocabularies.DirectEdit.v1 | Direct editing |
+| Graph | com.sap.vocabularies.Graph.v1 | Graph structures |
+| Hierarchy | com.sap.vocabularies.Hierarchy.v1 | Hierarchical data |
+| HTML5 | com.sap.vocabularies.HTML5.v1 | HTML5 rendering |
+| ODM | com.sap.vocabularies.ODM.v1 | One Domain Model |
+| PDF | com.sap.vocabularies.PDF.v1 | PDF generation |
+| PersonalData | com.sap.vocabularies.PersonalData.v1 | Personal data marking |
+| Preview | com.sap.vocabularies.Preview.v1 | Preview features |
+| Session | com.sap.vocabularies.Session.v1 | Session handling |
+| UI | com.sap.vocabularies.UI.v1 | UI annotations |
+
+---
+
+## Code Completion
+
+### Activation
+
+- **Windows**: `Ctrl + Space`
+- **macOS**: `Cmd + Space`
+
+### Context-Aware Suggestions
+
+Code completion provides suggestions based on:
+- Project metadata (entities, properties, associations)
+- OData vocabulary definitions
+- Current cursor context
+
+### Path Navigation
+
+Use `/` character to:
+1. Accept current segment selection
+2. Trigger completion for next segment
+3. Navigate multi-segment annotation paths
+
+### Supported Contexts
+
+- Annotation targets
+- Terms and term values
+- Attributes and attribute values
+- Record properties
+- Path expressions
+
+---
+
+## Micro-Snippets
+
+Pre-defined code blocks for rapid annotation development.
+
+### Available Snippets
+
+| Snippet Type | Description |
+|--------------|-------------|
+| Annotation Target | `<Annotations Target=""></Annotations>` |
+| Terms | Complete term structures |
+| Records | Record with properties |
+| Property Values | Property value templates |
+
+### Record Snippet Types
+
+1. **Minimal Version**: Only mandatory properties (nullable=false)
+2. **Complete Version**: All available properties
+
+### Usage Example
+
+Within `<Schema>` tags:
+1. Trigger code completion
+2. Select annotation target snippet
+3. Cursor positions inside quotes for immediate target selection
+
+---
+
+## Diagnostics
+
+### Validation Scope
+
+The language server validates:
+- Annotation syntax
+- Vocabulary compliance
+- Metadata references
+- Property types and values
+
+### Message Types
+
+| Type | Severity | Description |
+|------|----------|-------------|
+| Error | High | Must fix before deployment |
+| Warning | Medium | Potential issues |
+| Info | Low | Informational messages |
+
+### Accessing Diagnostics
+
+1. **Hover**: Mouse over highlighted sections
+2. **Problems Panel**: View > Problems (all issues)
+
+### Quick Fixes
+
+Light bulb icon provides automatic fixes:
+- Missing required properties
+- Type mismatches
+- Value corrections
+
+### Limitations
+
+**Not Supported**:
+- Annotations embedded in metadata
+- Dynamic expressions
+- Backend annotation file modifications (local copies only)
+
+---
+
+## Internationalization
+
+### Configuration
+
+**Non-CAP Projects**:
+```json
+// webapp/manifest.json
+{
+  "sap.ui5": {
+    "models": {
+      "i18n": {
+        "type": "sap.ui.model.resource.ResourceModel",
+        "settings": {
+          "bundleName": "project.i18n.i18n"
+        }
+      }
+    }
+  }
+}
+```
+
+**CAP Projects**:
+```json
+// .cdsrc.json or package.json
+{
+  "i18n": {
+    "folders": ["_i18n", "i18n", "assets/i18n"]
+  }
+}
+```
+
+### Key Naming Conventions
+
+| Project Type | Format | Example |
+|--------------|--------|---------|
+| Non-CAP | camelCase | `productTitle` |
+| CAP | PascalCase | `ProductTitle` |
+
+### i18n Scenarios
+
+1. **Non-internationalized labels**: Convert to i18n key references
+2. **Missing i18n keys**: Auto-generate with matching values
+3. **Duplicate text**: Link to existing i18n entries
+
+### Mass i18n Generation
+
+Bulk externalization of multiple UI texts:
+1. Access via Page Editor or annotation file
+2. Select multiple translatable strings
+3. Generate keys in batch operation
+
+### Best Practice
+
+Handle i18n near project completion to minimize unused entries and reduce localization costs.
+
+---
+
+## Service Modeler
+
+### Purpose
+
+Visualize OData service metadata and annotations for exploration and overriding.
+
+### Launching
+
+- Command Palette: `Fiori: Open Service Modeler`
+- Context Menu: Right-click folder > "Override Annotations"
+- Editor: Click icon when metadata.xml is open
+
+### Features
+
+**Annotation Display**:
+- View backend and local annotation files
+- Local annotations override backend annotations
+- Search annotations by term or target
+
+**Source Navigation**:
+- "Show in Source" icon opens original file
+- Highlighting for context
+
+### Editing Annotations
+
+Backend annotations cannot be modified directly. Local annotations:
+- Location: `/webapp/annotations/<filename>.xml`
+- Edit via XML Code Editor
+- Delete using Service Modeler delete icon
+
+### Override Priority
+
+Local annotations win over backend annotations when:
+- Same annotation term
+- Same qualifier
+- Same target
+
+---
+
+## Common Annotation Patterns
+
+### List Report Line Item
+
+```xml
+<Annotations Target="Namespace.EntityType">
+    <Annotation Term="UI.LineItem">
+        <Collection>
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" Path="PropertyName"/>
+                <PropertyValue Property="Label" String="Column Label"/>
+            </Record>
+        </Collection>
+    </Annotation>
+</Annotations>
+```
+
+### Selection Fields (Filter Bar)
+
+```xml
+<Annotation Term="UI.SelectionFields">
+    <Collection>
+        <PropertyPath>Property1</PropertyPath>
+        <PropertyPath>Property2</PropertyPath>
+    </Collection>
+</Annotation>
+```
+
+### Header Info
+
+```xml
+<Annotation Term="UI.HeaderInfo">
+    <Record Type="UI.HeaderInfoType">
+        <PropertyValue Property="TypeName" String="Entity"/>
+        <PropertyValue Property="TypeNamePlural" String="Entities"/>
+        <PropertyValue Property="Title">
+            <Record Type="UI.DataField">
+                <PropertyValue Property="Value" Path="Name"/>
+            </Record>
+        </PropertyValue>
+    </Record>
+</Annotation>
+```
+
+### Object Page Facets
+
+```xml
+<Annotation Term="UI.Facets">
+    <Collection>
+        <Record Type="UI.ReferenceFacet">
+            <PropertyValue Property="Label" String="General"/>
+            <PropertyValue Property="ID" String="GeneralFacet"/>
+            <PropertyValue Property="Target" AnnotationPath="@UI.FieldGroup#General"/>
+        </Record>
+    </Collection>
+</Annotation>
+```
+
+### Field Group
+
+```xml
+<Annotation Term="UI.FieldGroup" Qualifier="General">
+    <Record Type="UI.FieldGroupType">
+        <PropertyValue Property="Data">
+            <Collection>
+                <Record Type="UI.DataField">
+                    <PropertyValue Property="Value" Path="Property1"/>
+                </Record>
+            </Collection>
+        </PropertyValue>
+    </Record>
+</Annotation>
+```
+
+---
+
+## Documentation Source
+
+**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Developing-an-Application](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Developing-an-Application)
+
+Key files:
+- `maintaining-annotations-with-language-server-6fc93f8.md`
+- `code-completion-dd4fc3b.md`
+- `micro-snippets-addf811.md`
+- `diagnostics-1fd8f54.md`
+- `internationalization-i18n-eb427f2.md`
+- `visualizing-annotations-with-service-modeler-58784b5.md`
+- `working-with-annotations-55bfb91.md`
+- `overriding-annotations-2f1bb9c.md`