Initial commit

2025-11-30 08:55:02 +08:00
commit 6942e32e6b
26 changed files with 7173 additions and 0 deletions
--- a/references/cap-development.md
+++ b/references/cap-development.md
@@ -0,0 +1,374 @@
+# CAP Development Reference
+
+## Overview
+
+SAP Cloud Application Programming Model (CAP) is SAP's recommended framework for building enterprise-grade applications on SAP BTP using Node.js or Java.
+
+## Operational Profiles
+
+CAP provides three operational profiles for different development stages:
+
+### Development Profile
+
+**Database**: SQLite (Node.js) / H2 (Java)
+
+**Features:**
+- Rapid prototyping with minimal setup
+- Mocked variants of SAP BTP services (authentication, database, messaging, app gateway)
+- No BTP subscription required
+- Cost-effective testing
+
+**Usage:**
+```bash
+cds watch  # Automatically uses development profile
+```
+
+### Hybrid Profile
+
+**Database**: Cloud services (e.g., SAP HANA Cloud)
+
+**Features:**
+- Run application locally
+- Bind to real cloud services for integration testing
+- Use `cds bind` or local configuration files
+- Test with production-like data
+
+**Usage:**
+```bash
+cds bind --to hana:my-hana-instance
+cds watch --profile hybrid
+```
+
+### Production Profile
+
+**Database**: SAP HANA Cloud
+
+**Features:**
+- Deployed to SAP BTP (Cloud Foundry or Kyma)
+- Platform-managed service bindings
+- Production configuration for logging and security
+- Database migrations via `cds deploy`
+
+**Usage:**
+```bash
+cds build --production
+cf deploy mta_archives/my-app.mtar
+```
+
+### Profile Summary
+
+| Profile | Database | Use Case |
+|---------|----------|----------|
+| Development | SQLite/H2 | Local prototyping, mock services |
+| Hybrid | Cloud services | Local app with cloud DB/services |
+| Production | SAP HANA Cloud | Full cloud deployment |
+
+## Supported Languages and Runtimes
+
+| Language | Framework | Runtime Options |
+|----------|-----------|-----------------|
+| Node.js | Express.js | Cloud Foundry, Kyma |
+| Java | Spring Boot | Cloud Foundry, Kyma |
+| TypeScript | Node.js | Cloud Foundry, Kyma |
+
+## Development Tools
+
+| Tool | Purpose |
+|------|---------|
+| SAP Business Application Studio | Primary cloud IDE |
+| Visual Studio Code | Local development with CDS extension |
+| IntelliJ IDEA | Java CAP development |
+| CDS CLI | Command-line development |
+
+## Core CDS Commands
+
+```bash
+# Initialize new project
+cds init my-project
+
+# Add features
+cds add hana          # SAP HANA Cloud support
+cds add xsuaa         # Authentication
+cds add mta           # MTA descriptor
+cds add helm          # Helm charts for Kyma
+cds add multitenancy  # Multitenant support
+cds add approuter     # Application router
+
+# Development
+cds watch             # Run with live reload
+cds build             # Build for deployment
+cds deploy            # Deploy to HANA
+
+# Service inspection
+cds compile           # Compile CDS models
+cds serve             # Start services
+```
+
+## Domain Modeling with CDS
+
+### Entity Definition
+```cds
+namespace my.bookshop;
+
+entity Books {
+  key ID : UUID;
+  title  : String(111);
+  author : Association to Authors;
+  stock  : Integer;
+}
+
+entity Authors {
+  key ID : UUID;
+  name   : String(111);
+  books  : Association to many Books on books.author = $self;
+}
+```
+
+### Service Definition
+```cds
+using my.bookshop from '../db/schema';
+
+service CatalogService {
+  @readonly entity Books as projection on bookshop.Books;
+  entity Authors as projection on bookshop.Authors;
+
+  action submitOrder(book: Books:ID, quantity: Integer);
+}
+```
+
+## CAP Design Principles
+
+### Domain-Driven Design
+- Focus on core domain logic
+- Align code structure with business concepts
+- Collaboration between technical and domain experts
+
+### Agnostic Design
+CAP abstracts:
+- Deployment approaches
+- Authentication strategies
+- Protocols (REST, OData, GraphQL)
+- Asynchronous channels
+- Database technologies
+
+### Out-of-the-Box Integration
+- SAP HANA Cloud for persistence
+- Authorization management services
+- Connectivity tools for external systems
+
+## Platform Integration
+
+### Database Support
+| Database | Use Case |
+|----------|----------|
+| SQLite | Development (Node.js) |
+| H2 | Development (Java) |
+| PostgreSQL | Production alternative |
+| SAP HANA Cloud | Production (recommended) |
+
+### Service Bindings
+```yaml
+# mta.yaml service binding example
+modules:
+  - name: my-srv
+    type: nodejs
+    requires:
+      - name: my-hana
+      - name: my-xsuaa
+      - name: my-destination
+
+resources:
+  - name: my-hana
+    type: com.sap.xs.hdi-container
+  - name: my-xsuaa
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: xsuaa
+      service-plan: application
+```
+
+## Microservices Architecture
+
+CAP supports microservice development with:
+- Separate lifecycles per service
+- Independent runtimes
+- Event-based communication
+
+**Considerations:**
+- Microservices introduce complexity
+- Potential performance trade-offs
+- Start monolithic, extract when needed
+
+## API Consumption
+
+### Supported Protocols
+- OData V2/V4
+- REST
+- OpenAPI
+
+### SAP Cloud SDK Integration
+
+**Generate typed client** (recommended approach):
+```bash
+# Generate OData client from service specification
+npx @sap-cloud-sdk/generator --input ./API_BUSINESS_PARTNER.edmx --outputDir ./generated
+```
+
+**Use generated client**:
+```javascript
+// Import from generated client (path depends on generator output)
+const { businessPartnerApi } = require('./generated/business-partner-service');
+
+// Fetch business partners from S/4HANA
+const businessPartners = await businessPartnerApi
+  .requestBuilder()
+  .getAll()
+  .execute({ destinationName: 'S4HANA' });
+```
+
+> **Note**: The `@sap/cloud-sdk-vdm-*` packages are deprecated. Use `@sap-cloud-sdk/generator` to generate typed clients from OData service specifications. See [SAP Cloud SDK documentation](https://sap.github.io/cloud-sdk/docs/js/features/odata/generate-client) for details.
+
+## Multitenancy
+
+### Enable Multitenancy
+```bash
+cds add multitenancy
+```
+
+### Key Features
+- Tenant isolation
+- Per-tenant database schemas
+- Subscription lifecycle hooks
+- Resource sharing across tenants
+
+### SaaS Entry Points
+
+| Approach | Description | Consumer Requirements |
+|----------|-------------|----------------------|
+| Central | SAP Build Work Zone managed | Own Work Zone instance |
+| Local | Standalone app router | None |
+
+## Extensibility
+
+### In-App Extensions
+```cds
+// Extend existing service
+extend service CatalogService with {
+  entity CustomEntity {
+    key ID : UUID;
+    customField : String;
+  }
+}
+```
+
+### Custom Handlers
+```javascript
+// srv/cat-service.js
+module.exports = (srv) => {
+  srv.before('CREATE', 'Books', async (req) => {
+    // Validation logic
+    if (!req.data.title) {
+      req.error(400, 'Title is required');
+    }
+  });
+
+  srv.on('submitOrder', async (req) => {
+    // Custom action implementation
+    const { book, quantity } = req.data;
+    // Process order...
+  });
+};
+```
+
+## Security Implementation
+
+### Authentication
+```cds
+// Require authentication
+service CatalogService @(requires: 'authenticated-user') {
+  entity Books as projection on bookshop.Books;
+}
+```
+
+### Authorization
+```cds
+// Role-based access
+service AdminService @(requires: 'admin') {
+  entity Books as projection on bookshop.Books;
+
+  @(restrict: [{ grant: 'READ', to: 'viewer' }])
+  entity Reports { ... }
+}
+```
+
+### Built-in Security Features
+- Parameterized queries (SQL injection prevention)
+- CSRF protection for UI applications
+- CDS constraints for input validation
+
+## Testing
+
+### Unit Testing with Jest
+```javascript
+const cds = require('@sap/cds');
+
+describe('CatalogService', () => {
+  let srv;
+
+  beforeAll(async () => {
+    srv = await cds.connect.to('CatalogService');
+  });
+
+  it('should return books', async () => {
+    const books = await srv.read('Books');
+    expect(books).toBeDefined();
+  });
+});
+```
+
+### Integration Testing
+```bash
+# Run tests
+npm test
+
+# With coverage
+npm test -- --coverage
+```
+
+## Deployment Commands
+
+### Cloud Foundry
+```bash
+# Build MTA
+mbt build
+
+# Deploy
+cf deploy mta_archives/my-project_1.0.0.mtar
+
+# Or with cf push for simple apps
+cf push
+```
+
+### Kyma
+```bash
+# Add Helm support
+cds add helm
+
+# Deploy with Helm
+helm upgrade --install my-app ./chart
+```
+
+## Common Issues and Solutions
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `HANA deployment fails` | Wrong HDI container | Verify `requires` in mta.yaml |
+| `Authentication errors` | XSUAA not bound | Run `cf bind-service` |
+| `Database connection refused` | Wrong profile | Set `NODE_ENV=production` |
+| `Model compilation errors` | CDS syntax | Run `cds compile --to json` for details |
+
+## Source Documentation
+
+- CAP Documentation: [https://cap.cloud.sap/docs/](https://cap.cloud.sap/docs/)
+- SAP BTP CF/Kyma with CAP: [https://github.com/SAP-docs/btp-developer-guide/blob/main/docs/sap-btp-cloud-foundry-and-sap-btp-kyma-runtimes-with-cap-0f9cfe9.md](https://github.com/SAP-docs/btp-developer-guide/blob/main/docs/sap-btp-cloud-foundry-and-sap-btp-kyma-runtimes-with-cap-0f9cfe9.md)
+- Development Guide: [https://github.com/SAP-docs/btp-developer-guide/blob/main/docs/develop-7e30686.md](https://github.com/SAP-docs/btp-developer-guide/blob/main/docs/develop-7e30686.md)