sap-fiori-app-development

SAP Fiori 应用开发指南（CAP 和独立项目）

通用指南（适用于 CAP 和独立 Fiori 项目）

1. 始终询问用户，他们想创建用于 CAP（Cloud Application Programming）的 Fiori 应用，还是连接到外部 OData 服务的独立 Fiori 项目；除非用户的请求中已明确指定技术栈，否则应在开始实施前询问。
2. 使用 Fiori MCP 工具，通过 SAP Fiori Elements 创建 Fiori UI。
3. Fiori MCP Server 工具成功执行后，告知用户已完成。不要验证或再次检查——将工具执行成功视为确认。
4. 数据模型应适用于 SAP Fiori elements：至少包含一个作为应用主实体的实体类型。可选地添加指向相关实体的导航属性，以支持更丰富的 UI 模式。
5. 实体的每个属性都必须具有合适的数据类型。
6. 直接修改代码前，先检查 Fiori MCP server 是否提供合适的函数或工具，或者是否存在专用技能（例如 sap-fiori-analytical-chart）。

可用的应用模板（适用于 CAP 和独立项目）

Fiori MCP 可为 CAP 和独立项目后端创建以下应用模板：

1. FE_LROP - 列表报表对象页（最常用，OData V2/V4）
2. FE_ALP - 分析列表页（OData V2/V4）
3. FE_OVP - 概览页（OData V2/V4）
4. FE_WORKLIST - 工作清单（OData V2/V4）
5. FE_FEOP - 表单录入对象页（仅限 OData V4）
6. FE_FPM - 灵活编程模型 / 自定义页（仅限 OData V4）
7. FF_SIMPLE - 基本 SAPUI5 自由风格模板（可在没有数据源的情况下使用）

可用的页面类型

Fiori MCP 可向现有应用添加以下页面类型：

1. ListReport - 带筛选和搜索功能的表格视图
2. ObjectPage - 用于查看或编辑记录的详情页
3. CustomPage - 使用自定义视图的完全自定义页面

应用结构

• 用户要求创建 SAP Fiori elements 应用时，检查用户输入是否可以理解为由一个或多个页面组成的应用，这些页面包含表格数据或表单。
• 应用通常以显示表格数据的列表报表页面作为起始页，但也提供其他模板（见上文）。
• 根据基础实体，在对象页中显示特定表格行的详情。
• 对象页可以根据其实体类型的导航属性（包括对一关联（0..1）和对多关联）包含多个分区。
• 对于对多关联，可根据关联的目标实体，在另一个对象页中显示表格分区行的详情。

应用预览指南

• 使用 package.json 中针对该应用最具体的脚本。
• 对于 CAP：使用 watch 脚本（例如 npm run watch-manage-travel）
• 对于独立 Fiori 项目：使用 npm start（实时后端）或 npm run start-mock（模拟数据）

CAP 专用指南

1. Fiori 应用必须创建在 CAP 应用根目录下的 app 文件夹中。该根目录应事先通过 cds init 操作创建，并且始终是工作目录的直接子文件夹。
2. 根据 CAP 应用摘要创建 UI 应用时，除非用户明确提出其他要求，否则请使用摘要项目结构中描述的 UI 应用名称。
3. 对完整栈 CAP 应用的 UI 提出后续更改或修改请求时，始终优先尝试在 Fiori 应用中进行更改，除非确实需要修改服务。
4. 所有实体都必须使用 UUID 类型的主键。
5. 在 CSV 文件中创建示例数据时，所有主键和外键都必须使用 UUID 格式（例如 550e8400-e29b-41d4-a716-446655440001）。

独立 Fiori 项目指南

1. 基于外部服务的独立 Fiori 项目由 Fiori MCP 工具在根目录中创建应用。
2. 目标或 SAP 系统名称：如果用户未提供目标名称或 SAP 系统名称，请使用 Fiori MCP Server 检索可用的目标／系统并提供给用户选择。
3. 获取 OData 服务元数据（仅限初始应用创建）：请参阅工具说明，了解如何下载 OData 服务元数据。如果 Service Center MCP 可用，请使用该工具；否则，请使用 Fiori MCP Server 下载元数据文件。若要刷新已创建应用中的元数据，请参阅下方第 8 点。
4. 注释应主要在后端服务中维护，只有特定于应用的 UI 自定义或覆盖内容才应放在本地（前端）注释中。
5. 仅将前端注释用于特定于应用的 UI 调整（例如 /webapp/annotations/annotation.xml），并在 manifest.json 中通过匹配的 uri 和 localUri 值引用：

   "annotation": {
     "type": "ODataAnnotation",
     "uri": "annotations/annotation.xml",
     "settings": {
       "localUri": "annotations/annotation.xml"
     }
   }
   

6. 独立 Fiori 项目连接到远程 OData V2 或 V4 服务（在 manifest.json 的 dataSources 中定义）。
7. OData 服务元数据为只读：不得在本地编辑 manifest.json 中引用的服务元数据文件（/webapp/localService/mainService/metadata.xml）。实体定义、属性或服务结构的任何更改都必须在后端源中进行：

   "dataSources": {
     "mainService": {
       "uri": "/path/to/odata/service/",
       "type": "OData",
       "settings": {
         "annotations": ["annotation"],
         "localUri": "localService/mainService/metadata.xml",
         "odataVersion": "4.0"
       }
     }
   }
   

8. 更新服务元数据：若要从实时后端刷新现有 Fiori 应用的本地 metadata.xml，请勿使用 download_odata_service_metadata（该工具用于应用或页面创建期间的初始元数据下载，而非刷新项目中已有的元数据）。请改为调用 sap-fiori-create-cli 技能中的 update service-metadata 部分。