在开发 SAP CAP 应用、定义 CDS 模型/服务…

构建 SAP CAP 应用（CDS 模型、Node.js/Java 服务、HANA/SQLite/PostgreSQL、BTP CF/Kyma 部署、Fiori、授权、多租户、消息、AI 集成）时使用。

适用场景

解决思路

1. 按领域选择相关技能：UI 层与 Fiori Elements 用 sap-fiori-tools；自定义 UI 和 freestyle 应用用 sapui5；部署选项、Cloud Foundry/Kyma 配置和 BTP 服务集成用 sap-btp-cloud-platform；数据库管理、schema 检查和 HDI container 管理用 sap-hana-cli；ABAP 系统集成、外部服务消费和 SAP 扩展用 sap-abap；生产部署模式和架构指导用 sap-btp-best-practices；为 CAP 应用添加 AI 能力或集成 SAP AI 服务用 sap-ai-core；CAP 事件处理器中的 SDK 级 AI 集成（chat completion、streaming、tool calling）用 sap-cloud-sdk-ai；Python 版 AI 集成用 sap-cloud-sdk-ai-python；记录 CAP OData 服务或遵循 API 文档标准用 sap-api-style；CAP service repos 中的依赖、lockfile、供应链安全和精确 MCP server pin 控制用 sap-dependency-security。
2. 排查 `cds watch` 或 `cds serve` 失败：验证 `@sap/cds-dk`、Node.js 版本和项目 `package.json` scripts。
3. 排查实体/服务未找到：可用时使用 CAP MCP `search_model`，然后检查 `db/` 和 `srv/` CDS 文件。
4. 排查 HANA 部署失败：检查 HDI service binding、`mta.yaml` 和 HANA deployment references。
5. 排查授权行为异常：审查 `@requires`、`@restrict`、XSUAA/IAS bindings 和用户角色映射。
6. 使用经过批准的 CAP toolchain：project-local devDependencies、user-local npm prefix 或 enterprise-managed Node/CAP installation；确保 `cds` 和可选的 `cds-lsp` 命令在 PATH，并运行 `cds --version`。
7. 创建新项目：运行 `cds init <project-name>`，或带样例和 HANA 运行 `cds init <project-name> --add sample,hana`。
8. 启动带 live reload 的开发服务器：运行 `cds watch`。
9. 按需添加能力：运行 `cds add hana`、`cds add sqlite`、`cds add xsuaa`、`cds add mta`、`cds add multitenancy`、`cds add typescript`。
10. 定义基础实体：使用 `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; }`。
11. 定义基础服务：使用 `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; }`。
12. 集成官方 CAP MCP server，为 AI agents 提供对项目编译后 CDS model 和 CAP documentation 的实时访问。
13. 使用 CAP MCP 工具：`search_model` 模糊搜索编译后 CSN model 中的 CDS 实体、服务、动作和关系；`search_docs` 对 CAP documentation 做语义搜索，查找语法、模式和最佳实践。
14. 利用 MCP 优势：即时模型发现、上下文感知文档、零配置、离线可用（model 搜索本地、docs 搜索缓存）。
15. 配置 MCP：参见 `references/mcp-integration.md` 配置 Claude Code、opencode 或 GitHub Copilot；MCP package pins 由 sap-dependency-security 管辖，并通过 `npm run validate:mcp-security` 验证。
16. 查看 MCP 用例：参见 `references/mcp-use-cases.md` 获取说明性本地工作流示例和规划假设，不将其作为仓库验证过的 ROI。
17. Agent 集成：专用 agents（cap-cds-modeler、cap-service-developer、cap-project-architect、cap-performance-debugger）会自动使用这些 MCP 工具作为工作流的一部分。
18. 本地 model 和 docs 问题优先使用 MCP，MCP 不可用时回退到直接文件搜索。
19. 定位最窄参考：运行 `rg -n "<entity|service|aspect|annotation|handler|cds compile|deployment>" references/*.md srv db app`，再加载较长的 CAP 指南。
20. MCP 配置和 package pin checks 使用 `references/mcp-integration.md`。
21. 工作流选择和说明性影响示例仅使用 `references/mcp-use-cases.md`。
22. CAP editor integration 使用 `.lsp.json` 作为 Claude-compatible sidecar；其他 harnesses 不应假设它会自动加载。
23. 对 Codex、OpenCode、editors 或其他 LSP-capable clients，手动配置命令 `node <sap-cap-capire-plugin-root>/lsp/cds-lsp-launcher.mjs --stdio`；仍需通过 approved project-local devDependency、user-local npm prefix 或 enterprise-managed toolchain 安装 `@sap/cds-lsp`，并确保 `cds-lsp` 在 PATH。
24. 无 LSP 集成时，直接使用 Markdown guidance、bundled references、`rg` 和 CAP CLI checks。
25. 除非有目标项目或 tenant 证据，否则将 live deployment、HANA、XSUAA 和 multitenancy 验证标记为 pending。
26. 遵循项目结构：`app/` 放 UI 内容（Fiori、UI5）；`srv/` 放服务定义（`.cds`、`.js`/`.ts`）；`db/` 放数据模型和 schema（`schema.cds` 实体定义，`data/` CSV 种子数据）；`package.json` 放依赖和 CDS 配置；`.cdsrc.json` 放可选 CDS 配置。
27. 使用 CDS 内置类型映射：`UUID` 映射 NVARCHAR(36)，用于主键；`String(n)` 映射 NVARCHAR(n)，用于文本字段；`Integer` 映射 INTEGER，用于整数；`Decimal(p,s)` 映射 DECIMAL(p,s)，用于货币值；`Boolean` 映射 BOOLEAN；`Date` 映射 DATE；`Timestamp` 映射 TIMESTAMP。
28. 使用常用 aspects：从 `@sap/cds/common` 引入 `using { cuid, managed, temporal } from '@sap/cds/common';`；`cuid` = UUID key；`managed` = createdAt、createdBy、modifiedAt、modifiedBy；`temporal` = validFrom、validTo。
29. 实现 Node.js 事件处理器：在 `srv/cat-service.js` 中 `module.exports = class CatalogService extends cds.ApplicationService { init() { const { Books } = this.entities; this.before('CREATE', Books, req => { if (!req.data.title) req.error(400, 'Title required'); }); this.on('submitOrder', async req => { const { book, quantity } = req.data; return { success: true }; }); return super.init(); } }`。
30. 使用 CQL 查询：`SELECT.from(Books).where({ stock: { '>': 0 } }).orderBy('title');`；`INSERT.into(Books).entries({ title: 'New Book', stock: 10 });`；`UPDATE(Books, bookId).set({ stock: { '-=': 1 } });`。
31. AI 集成使用 SAP Cloud SDK for AI 连接 SAP AI Core；推荐模式是通过 CAP 事件处理器使用 Orchestration Service，所有凭证管理由 BTP service bindings 处理。
32. 在 MTA 中定义 AI Core service binding：`resources: - name: my-ai-core type: org.cloudfoundry.managed-service parameters: service: aicore service-plan: extended`。
33. 本地开发使用 Hybrid Mode：运行 `cds bind -2 <AICORE_INSTANCE> && cds-tsx watch --profile hybrid`。
34. 实现 Node.js/TypeScript AI 事件处理器模式：`import { OrchestrationClient } from '@sap-ai-sdk/orchestration';`，在 `AnalysisService extends cds.ApplicationService` 的 `init()` 中监听 `analyzeFeedback`，从 `req.data.text` 取文本，创建 `OrchestrationClient`（`promptTemplating: { model: { name: 'gpt-4o' }, prompt: [ { role: 'system', content: 'Categorize feedback as JSON: sentiment, category, urgency.' }, { role: 'user', content: '{{?userText}}' } ] }`），调用 `client.chatCompletion({ placeholderValues: { userText } })`，用 `response.getContent()` 得到 `aiResult`，`INSERT.into('FeedbackResults').entries({ originalText: userText, analysisJson: aiResult })`，返回 `aiResult`。
35. 生产异步处理 LLM 调用：LLM 调用可能耗时 30-60 秒，绝不同步处理；在 `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' }); })`；在 `processWithLLM(id, text)` 中调用 `client.chatCompletion({ placeholderValues: { userText: text } })`，再 `UPDATE('FeedbackResults', id).set({ analysisJson: response.getContent(), status: 'completed' })`。
36. 构建 RAG 时使用 HANA Vector Type：`entity Documents { key id : UUID; content : String(5000); embedding : Vector(1536); }`，结合 HANA Cloud Vector Engine 和 AI Core orchestration grounding。
37. 外部化 prompts：不要把 prompts 硬编码在事件处理器；存储在 JSON 文件或 CDS 配置实体中，例如 `entity PromptTemplates { key id : UUID; name : String(100); systemPrompt : LargeString; updatedBy : String; modifiedAt : Timestamp; }`。
38. 部署内存要求：Node.js 容器中 AI SDK 处理大文本 payload 时，在 MTA descriptor 中至少分配 512MB memory。
39. AI SDK 完整文档参见 sap-cloud-sdk-ai skill；AI Core 平台设置和 orchestration 配置参见 sap-ai-core skill。
40. 开发环境使用 SQLite：在 `package.json` 的 `cds.requires.db` 中配置 "[development]" 为 `{ "kind": "sqlite", "credentials": { "url": ":memory:" } }`，"[production]" 为 `{ "kind": "hana" }`。
41. 生产环境使用 SAP HANA：运行 `cds add hana`，然后运行 `cds deploy --to hana`。
42. 初始数据用 CSV：文件放在 `db/data/my.bookshop-Books.csv`，格式为 `<namespace>-<EntityName>.csv`，部署时自动加载。
43. 部署到 Cloud Foundry：运行 `cds add hana,xsuaa,mta,approuter`，再运行 `npm install --package-lock-only`，然后 `mbt build`，最后 `cf deploy mta_archives/<project>_<version>.mtar`。
44. 实现 SaaS 多租户：运行 `cds add multitenancy`，并在配置中设置 `cds.requires.multitenancy` 为 `true`。
45. 配置授权：服务级使用 `@requires: 'authenticated-user' service CatalogService { ... }`；实体级使用 `@restrict: [ { grant: 'READ' }, { grant: 'WRITE', to: 'admin' } ] entity Books { ... }`。
46. 按需查阅 bundled reference documentation：annotations-reference.md、cdl-syntax.md、cql-queries.md、csn-cqn-cxn.md、data-privacy-security.md、databases.md、deployment-cf.md、event-handlers-nodejs.md、extensibility-multitenancy.md、fiori-integration.md、java-runtime.md、localization-temporal.md、nodejs-runtime.md、plugins-reference.md、tools-complete.md、consuming-services-deployment.md、service-definitions.md、event-handlers-patterns.md、cql-patterns.md、cli-complete.md、mcp-integration.md、mcp-use-cases.md。
47. 按需使用 templates：bookshop-schema.cds、catalog-service.cds、fiori-annotations.cds、mta.yaml、package.json、service-handler.js、service-handler.ts、xs-security.json。
48. 参考快速链接：CAP Documentation `https://cap.cloud.sap/docs/`、CDS Language `https://cap.cloud.sap/docs/cds/`、Node.js Runtime `https://cap.cloud.sap/docs/node.js/`、Java Runtime `https://cap.cloud.sap/docs/java/`、Best Practices `https://cap.cloud.sap/docs/about/best-practices`、GitHub Repository `https://github.com/cap-js/docs`。
49. 使用常见 CLI 命令：`cds init [name]` 创建项目；`cds add <feature>` 添加能力；`cds watch` 启动开发服务器并 live reload；`cds serve` 启动服务器；`cds compile <model>` 编译 CDS 为 CSN/SQL/EDMX；`cds deploy --to hana` 部署到 HANA；`cds build` 为部署构建；`cds env` 显示配置；`cds repl` 进入交互式 REPL；`cds version` 显示版本信息。
50. 遵循 DO 实践：使用 `@sap/cds/common` 的 `cuid` 和 `managed` aspects；域模型放 `db/`、服务放 `srv/`、UI 放 `app/`；使用 managed associations 让 CAP 处理外键；按用例设计单一职责服务；从 SQLite 开始，生产切换到 HANA。
51. 避免 DON'T 实践：不要使用 `SELECT *`，要显式投影；不要用 raw SQL 绕过 CAP 的 query API；不要过早创建 microservices；不要在配置文件中硬编码 credentials；不要编写自定义 OData providers。
52. 版本信息：CAP Version `@sap/cds 9.7.x`，MCP Version `@cap-js/mcp-server 0.0.5`，LSP Version `@sap/cds-lsp 9.7.x`，License GPL-3.0。

适用边界 · 注意事项

• 不适用于非 SAP CAP/BTP 技术栈的项目。
• 不适用于没有 SAP BTP、HANA、XSUAA/IAS、AI Core 等服务绑定、权限或租户证据的场景。
• 不应用来替代对 live deployment、HANA、XSUAA、multitenancy 的目标项目或租户验证；缺少证据时应标记为 pending。