sap-cap-capire

SAP CAP-Capire 开发技能

相关技能

• sap-fiori-tools：用于 UI 层开发、Fiori Elements 集成和前端应用生成
• sapui5：用于自定义 UI 开发、高级 UI 模式和自由式应用构建
• sap-btp-cloud-platform：用于部署选项、Cloud Foundry/Kyma 配置和 BTP 服务集成
• sap-hana-cli：用于数据库管理、架构检查和 HDI 容器管理
• sap-abap：用于 ABAP 系统集成、外部服务使用和 SAP 扩展
• sap-btp-best-practices：用于生产部署模式和架构指导
• sap-ai-core：用于为 CAP 应用添加 AI 功能，或与 SAP AI 服务集成
• sap-cloud-sdk-ai：用于在 CAP 事件处理器中进行 SDK 级别的 AI 集成（聊天补全、流式传输、工具调用）
• sap-cloud-sdk-ai-python：用于基于 Python 的 AI 集成，适用于 CAP Java 或独立 BTP 服务
• sap-api-style：用于编写 CAP OData 服务文档，或遵循 API 文档标准
• sap-dependency-security：用于 CAP 服务代码库中的安全依赖项、锁文件、供应链和精确 MCP 服务固定控制

何时使用此技能

在创建 CAP 项目、建模 CDS 实体/服务、实现 Node.js 或 Java 事件处理器、配置 HANA/SQLite/PostgreSQL 持久化、部署到 BTP Cloud Foundry 或 Kyma、添加 Fiori UI、配置授权/多租户/消息传递，或使用 CAP MCP/LSP 工具时，请使用此技能。

常见问题

问题	首先检查
cds watch 或 cds serve 失败	确认 @sap/cds-dk、Node.js 版本和项目 package.json 脚本。
找不到实体/服务	如果可用，请使用 CAP MCP search_model，然后检查 db/ 和 srv/ CDS 文件。
HANA 部署失败	检查 HDI 服务绑定、mta.yaml 和 HANA 部署引用。
授权行为异常	检查 @requires、@restrict、XSUAA/IAS 绑定和用户角色映射。

目录

• 快速入门
• 项目结构
• 核心概念
• AI 集成
• 数据库设置
• 部署
• 捆绑资源

快速入门

项目初始化

# Use an approved CAP toolchain:
# - project-local devDependencies
# - user-local npm prefix
# - enterprise-managed Node/CAP installation
# Ensure cds and optional cds-lsp commands are on PATH.
cds --version

# Create new project
cds init <project-name>
cds init <project-name> --add sample,hana

# Start development server with live reload
cds watch

# Add capabilities
cds add hana          # SAP HANA database
cds add sqlite        # SQLite for development
cds add xsuaa         # Authentication
cds add mta           # Cloud Foundry deployment
cds add multitenancy  # SaaS multitenancy
cds add typescript    # TypeScript support

基本实体示例

using { cuid, managed } from '@sap/cds/common';

namespace my.bookshop;

entity Books : cuid, managed {
  title       : String(111) not null;
  author      : Association to Authors;
  stock       : Integer;
  price       : Decimal(9,2);
}

entity Authors : cuid, managed {
  name        : String(111);
  books       : Association to many Books on books.author = $self;
}

基本服务

using { my.bookshop as my } from '../db/schema';

service CatalogService @(path: '/browse') {
  @readonly entity Books as projection on my.Books;
  @readonly entity Authors as projection on my.Authors;
  
  @requires: 'authenticated-user'
  action submitOrder(book: Books:ID, quantity: Integer) returns String;
}

MCP 集成

此技能集成了官方 CAP MCP（模型上下文协议）服务，使 AI Agent 能够实时访问项目编译后的 CDS 模型和 CAP 文档。

可用的 MCP 工具：

• search_model - 在编译后的 CSN 模型中模糊搜索 CDS 实体、服务、操作和关系
• search_docs - 语义搜索 CAP 文档，查找语法、模式和最佳实践

主要优势：

• 即时发现模型：无需读取文件即可查询项目的实体、关联和服务
• 上下文感知文档：根据语义相似度而非关键词查找相关 CAP 文档
• 零配置：无需凭据或环境变量
• 支持离线：所有搜索均在本地（模型）执行或使用缓存（文档）

设置：有关 Claude Code、opencode 或 GitHub Copilot 的配置，请参阅 MCP 集成指南。MCP 包固定由 sap-dependency-security 管理，并通过 npm run validate:mcp-security 验证。

使用场景：请参阅 MCP 使用场景，其中包含示例性的本地工作流案例和规划假设，并非经过代码库验证的投资回报率。

Agent 集成：专用 Agent（cap-cds-modeler、cap-service-developer、cap-project-architect、cap-performance-debugger）会在工作流中自动使用这些 MCP 工具。

CAP MCP 和 LSP 路由

本地模型和文档问题优先使用 MCP；如果 MCP 不可用，再使用直接文件搜索。使用 rg -n "<entity|service|aspect|annotation|handler|cds compile|deployment>" references/*.md srv db app，在加载篇幅较长的 CAP 指南之前，先定位最相关的参考资料。

• 使用 references/mcp-integration.md 检查 MCP 配置和软件包固定版本。
• 仅在选择工作流和说明影响示例时使用 references/mcp-use-cases.md。
• 将 .lsp.json 用作兼容 Claude 的 CAP 编辑器集成辅助配置；其他运行环境不应假定它会自动加载。
• 对于 Codex、OpenCode、编辑器或其他支持 LSP 的客户端，请手动将命令配置为 node <sap-cap-capire-plugin-root>/lsp/cds-lsp-launcher.mjs --stdio。这仍要求通过经过批准的项目本地 devDependency、用户本地 npm 前缀或企业管理的工具链安装 @sap/cds-lsp，并确保 cds-lsp 可通过 PATH 使用。
• 如果没有 LSP 集成，请直接使用 Markdown 指南、捆绑的参考资料、rg 和 CAP CLI 检查。
• 除非有目标项目或租户的证据，否则应将实时部署、HANA、XSUAA 和多租户验证标记为待处理。

项目结构

project/
├── app/              # UI content (Fiori, UI5)
├── srv/              # Service definitions (.cds, .js/.ts)
├── db/               # Data models and schema
│   ├── schema.cds    # Entity definitions
│   └── data/         # CSV seed data
├── package.json      # Dependencies and CDS config
└── .cdsrc.json       # CDS configuration (optional)

核心概念

CDS 内置类型

CDS 类型	SQL 映射	常见用途
UUID	NVARCHAR(36)	主键
String(n)	NVARCHAR(n)	文本字段
Integer	INTEGER	整数
Decimal(p,s)	DECIMAL(p,s)	货币值
Boolean	BOOLEAN	是/否
Date	DATE	日历日期
Timestamp	TIMESTAMP	日期/时间

常见切面

using { cuid, managed, temporal } from '@sap/cds/common';
// cuid = UUID key
// managed = createdAt, createdBy, modifiedAt, modifiedBy
// temporal = validFrom, validTo

事件处理器（Node.js）

// srv/cat-service.js
module.exports = class CatalogService extends cds.ApplicationService {
  init() {
    const { Books } = this.entities;
    
    // Before handlers - validation
    this.before('CREATE', Books, req => {
      if (!req.data.title) req.error(400, 'Title required');
    });
    
    // On handlers - custom logic
    this.on('submitOrder', async req => {
      const { book, quantity } = req.data;
      // Custom business logic
      return { success: true };
    });
    
    return super.init();
  }
}

基本 CQL 查询

const { Books } = cds.entities;

// SELECT with conditions
const books = await SELECT.from(Books)
  .where({ stock: { '>': 0 } })
  .orderBy('title');

// INSERT
await INSERT.into(Books)
  .entries({ title: 'New Book', stock: 10 });

// UPDATE
await UPDATE(Books, bookId)
  .set({ stock: { '-=': 1 } });

AI 集成

CAP 应用通过 SAP Cloud SDK for AI 与 SAP AI Core 集成。建议的模式是通过 CAP 事件处理器使用 Orchestration Service，并由 BTP 服务绑定处理所有凭据管理。

服务绑定（MTA）

resources:
  - name: my-ai-core
    type: org.cloudfoundry.managed-service
    parameters:
      service: aicore
      service-plan: extended

本地开发（混合模式）

cds bind -2 <AICORE_INSTANCE> && cds-tsx watch --profile hybrid

事件处理器模式（Node.js/TypeScript）

import { OrchestrationClient } from '@sap-ai-sdk/orchestration';

module.exports = class AnalysisService extends cds.ApplicationService {
  async init() {
    const { Feedback } = this.entities;

    this.on('analyzeFeedback', async (req) => {
      const userText = req.data.text;

      const client = new OrchestrationClient({
        promptTemplating: {
          model: { name: 'gpt-4o' },
          prompt: [
            { role: 'system', content: 'Categorize feedback as JSON: sentiment, category, urgency.' },
            { role: 'user', content: '{{?userText}}' }
          ]
        }
      });

      const response = await client.chatCompletion({
        placeholderValues: { userText }
      });

      const aiResult = response.getContent();

      await INSERT.into('FeedbackResults').entries({
        originalText: userText,
        analysisJson: aiResult
      });

      return aiResult;
    });

    return super.init();
  }
};

异步处理（生产模式）

大模型调用可能需要 30–60 秒。生产环境中切勿同步处理，因为在大模型响应之前，BTP 负载均衡器就会超时。

this.on('analyzeFeedback', async (req) => {
  const id = await INSERT.into('FeedbackResults').entries({
    originalText: req.data.text,
    status: 'processing'
  });

  cds.spawn(() => processWithLLM(id, req.data.text));

  return req.reply(202, { id, status: 'processing' });
});

async function processWithLLM(id, text) {
  const response = await client.chatCompletion({
    placeholderValues: { userText: text }
  });
  await UPDATE('FeedbackResults', id).set({
    analysisJson: response.getContent(),
    status: 'completed'
  });
}

RAG 的 HANA 向量类型

entity Documents {
  key id    : UUID;
  content   : String(5000);
  embedding : Vector(1536);
}

将其与 HANA Cloud Vector Engine 和 AI Core 编排接地功能搭配使用，可直接在 CAP 数据模型中构建 RAG 场景。

提示词外置

不要在事件处理器中硬编码提示词。将其存储在 JSON 文件或 CDS 配置实体中，以便无需重新部署即可更新：

entity PromptTemplates {
  key id       : UUID;
  name         : String(100);
  systemPrompt : LargeString;
  updatedBy    : String;
  modifiedAt   : Timestamp;
}

内存和部署

使用 AI SDK 处理大型文本负载的 Node.js 容器，在 MTA 描述符中至少需要 512MB 内存。AI SDK 和 JSON 负载处理所消耗的内存比典型的 CAP 服务更多。

完整的 SDK 文档请参阅 sap-cloud-sdk-ai 技能。AI Core 平台设置和编排配置请参阅 sap-ai-core 技能。

数据库设置

开发（SQLite）

// package.json
{
  "cds": {
    "requires": {
      "db": {
        "[development]": { 
          "kind": "sqlite", 
          "credentials": { "url": ":memory:" } 
        },
        "[production]": { "kind": "hana" }
      }
    }
  }
}

生产（SAP HANA）

cds add hana
cds deploy --to hana

初始数据（CSV）

• 文件位置：db/data/my.bookshop-Books.csv
• 格式：<namespace>-<EntityName>.csv
• 部署时自动加载

部署

Cloud Foundry

# Add CF deployment support
cds add hana,xsuaa,mta,approuter

# Build and deploy
npm install --package-lock-only
mbt build
cf deploy mta_archives/<project>_<version>.mtar

多租户（SaaS）

cds add multitenancy

配置：

{
  "cds": {
    "requires": {
      "multitenancy": true
    }
  }
}

授权示例

// Service-level
@requires: 'authenticated-user'
service CatalogService { ... }

// Entity-level
@restrict: [
  { grant: 'READ' },
  { grant: 'WRITE', to: 'admin' }
]
entity Books { ... }

捆绑资源

参考文档（22 个文件）

1. references/annotations-reference.md - 完整的 UI 注解参考（10K 行）
2. references/cdl-syntax.md - 完整的 CDL 语法参考（503 行）
3. references/cql-queries.md - CQL 查询语言指南
4. references/csn-cqn-cxn.md - 核心架构表示法和查询 API
5. references/data-privacy-security.md - GDPR 和安全实现
6. references/databases.md - 数据库配置和部署
7. references/deployment-cf.md - Cloud Foundry 部署详情
8. references/event-handlers-nodejs.md - Node.js 事件处理程序模式
9. references/extensibility-multitenancy.md - SaaS 多租户实现
10. references/fiori-integration.md - Fiori Elements 和 UI 集成
11. references/java-runtime.md - Java 运行时支持
12. references/localization-temporal.md - i18n 和时态数据
13. references/nodejs-runtime.md - Node.js 运行时参考
14. references/plugins-reference.md - CAP 插件和扩展
15. references/tools-complete.md - 完整的 CLI 工具参考
16. references/consuming-services-deployment.md - 服务消费模式
17. references/service-definitions.md - 服务定义模式
18. references/event-handlers-patterns.md - 事件处理模式
19. references/cql-patterns.md - CQL 使用模式
20. references/cli-complete.md - 完整的 CLI 参考
21. references/mcp-integration.md - MCP 服务设置和使用指南 （新增）
22. references/mcp-use-cases.md - MCP 工作流场景示例 （新增）

模板（8 个文件）

1. templates/bookshop-schema.cds - 完整的数据模型示例
2. templates/catalog-service.cds - 服务定义模板
3. templates/fiori-annotations.cds - UI 注解示例
4. templates/mta.yaml - 多目标应用描述符
5. templates/package.json - 项目配置模板
6. templates/service-handler.js - Node.js 处理程序模板
7. templates/service-handler.ts - TypeScript 处理程序模板
8. templates/xs-security.json - XSUAA 安全配置

快速参考

• CAP 文档：https://cap.cloud.sap/docs/
• CDS 语言：https://cap.cloud.sap/docs/cds/
• Node.js 运行时：https://cap.cloud.sap/docs/node.js/
• Java 运行时：https://cap.cloud.sap/docs/java/
• 最佳实践：https://cap.cloud.sap/docs/about/best-practices
• GitHub 仓库：https://github.com/cap-js/docs

常用 CLI 命令

cds init [name]           # Create project
cds add <feature>         # Add capability
cds watch                 # Dev server with live reload
cds serve                 # Start server
cds compile <model>       # Compile CDS to CSN/SQL/EDMX
cds deploy --to hana      # Deploy to HANA
cds build                 # Build for deployment
cds env                   # Show configuration
cds repl                  # Interactive REPL
cds version               # Show version info

最佳实践

应该 ✓

• 使用 @sap/cds/common 中的 cuid 和 managed 特性
• 将领域模型放在 db/ 中，将服务放在 srv/ 中，将 UI 放在 app/ 中
• 使用托管关联（让 CAP 处理外键）
• 针对每个用例设计单一用途的服务
• 从 SQLite 开始，在生产环境中切换到 HANA

不应该 ✗

• 不要使用 SELECT *，应明确指定投影
• 不要通过原始 SQL 绕过 CAP 的查询 API
• 不要过早创建微服务
• 不要在配置文件中硬编码凭据
• 不要编写自定义 OData 提供程序

版本信息

• CAP 版本：@sap/cds 9.7.x
• MCP 版本：@cap-js/mcp-server 0.0.5
• LSP 版本：@sap/cds-lsp 9.7.x
• 许可证：GPL-3.0