销售订单明细报表 —— S/4HANA Cloud 公有云开发手把手教程

适用环境:SAP S/4HANA Cloud Public Edition(中国区 GQN),release 2608,client 100,开发租户 D(my201458) 技术栈:ABAP Cloud(ABAP for Cloud Development)· CDS 视图实体 · Service Definition/Binding (OData V4) · Fiori elements List Report · BAS · IAM 业务目录/业务角色 软件包:ZZSD | 传输:gCTS 仓库 SAP-ZZSD(DEV → TEST → PROD) 文档性质:开发实施教程。所有对象名、字段名、代码片段均已与本地线上源码核对,出处逐条标注。 版本:v1.2 —— 补齐正文引用却未内嵌的 9 张配图(图 6–图 14,原图 6–11 顺延为图 15–20)。 修订明细见 附录 D 复核记录。


开工前必读(一页速览)

要做什么:把模板的 31 列做成本项目的一张 Fiori elements 清单报表,支持筛选 + 导出 Excel。

怎么做(一句话):ZR_ 层 4 个 CDS 视图做数据 → ZC_ 层 1 个消费视图 + 元数据扩展做 UI → 1 个 DCL 做权限 → Service Definition/Binding (OData V4) → BAS 生成 List Report → 部署到 SAPUI5 ABAP 仓库 → IAM App + 业务目录 + 业务角色。

三个关键设计判定(错一个就要返工):

#

判定

取值

依据

1

粒度

一行 = 一个销售订单行;交货数量与开票金额是跨交货/发票的合计

模板无交货单号/发票号列,且"交货数量"副表头写"交货总数"

2

架构

纯 CDS 视图实体链(不是项目现行的 custom entity + IF_RAP_QUERY_PROVIDER)

过滤/排序/分页可全部下推;无循环与外部取数需求。详见 §2.3 取舍表

3

开票金额来源

必须同时走 K/L(订单类) 与 J/T(交货类) 两条路径

线上 zcl_query_sd002.clas.abap L847-856 的实际连接条件

五个必须先问清楚的(附录 B V7 有完整清单,V8/V9 是技术验证脚本):

  1. 粒度确认(一行 = 订单行,还是订单行 × 交货行 × 发票行)→ 李婕 / 陈锦财

  2. 「拒绝原因」要的是哪个——订单原因(抬头,有标准文本)还是行项目拒绝原因(只有代码)? 复核线上代码发现:OA 审批回传里根本没有拒绝原因字段,且项目把行项目拒绝原因挪用成了删除标记。详见 §1.6

  3. 「SKU(客户)」以哪个为准——订单行标准字段 MaterialByCustomer,还是物料主数据自定义字段 YY1_SKU_PRD?详见 §1.7

  4. "订单含税单价"取反算值还是定价条件净价 → 销售 + 财务

  5. 导出是否必须复刻模板的两行表头(标准导出只有单行表头,两行需额外开发 3~5 人天)

开工第一步不是写代码,是跑附录 B 的 9 个验证脚本——尤其是 V8(拒绝原因口径)、V9(SKU 字段比对) 和 V1(开票类别统计),这三项的结论会直接改代码。

最容易踩的四个坑:

  • ❌ 直接把订单行 JOIN 交货行再 JOIN 发票行 → 行数成倍放大,金额全错。必须先在交货侧/开票侧聚合(§Step 1)。

  • ❌ 把 I_SDDocumentReasonText(订单原因的文本视图)连到 SalesDocumentRjcnReason(行项目拒绝原因)—— 两个字段域完全不同,连了能编译但结果是错的。这是初稿犯过的错,见 §1.6。

  • ❌ 忘了 cast( ... as abap.fltp ) 就写除法 → CDS 语法错误(§2.3)。

  • ❌ 忘了 @Semantics.amount.currencyCode / quantity.unitOfMeasure → Fiori 表格里金额没有币别、不能正确合计(§Step 1.4)。


目录

  1. 需求解析:模板逐列拆解

  2. 技术选型:为什么是这条路线

  3. 开工准备

  4. Step 1 — 建查询基视图(ZR_ 层)

  5. Step 2 — 建消费视图与元数据扩展(ZC_ 层)

  6. Step 3 — 权限:CDS 访问控制(DCL)

  7. Step 4 — 发布 OData V4 服务

  8. Step 5 — 用 BAS 生成 Fiori elements 应用

  9. Step 6 — 部署回 SAPUI5 ABAP 仓库

  10. Step 7 — IAM 应用 / 业务目录 / 业务角色

  11. Step 8 — 测试与验收清单

  12. 附录 A — 与项目现行范式(custom entity)的对照

  13. 附录 B — 待确认事项与验证脚本

  14. 附录 C — 本目录参考资料索引

  15. 附录 D — 复核记录


1. 需求解析:模板逐列拆解

1.1 模板的性质

收到的模板 销售订单明细报表模板 (2).xlsx 经解包核对,是一个 WPS 制作的规格样张,不是系统导出物:

观察项

事实

结论

工作表名

SAPUI5 导出

客户对"目标输出长什么样"的标注

命名空间

xmlns:dbsheet="http://web.wps.cn/et/2021/dbsheet"、etc="http://www.wps.cn/officeDocument/2017/etCustomData"

由 WPS 生成/保存

结构

1 行表头(A1:AE1)+ 1 行副表头(A2/E2/AB2)+ 1 行样例行 + 冻结首行 + 自动筛选

人工搭建的样张

样例数据

只有 1 行,且多列留空(SKU、订单数量、工厂、金额类全空)

字段是"要什么",不是"有什么"

结论:模板定义的是列清单与列顺序(31 列),不是数据精度要求。教程按此 31 列实现。

1.2 粒度判定(关键设计决策)

模板中没有交货单号、发票号列,而第 28 列"交货数量"的副表头写的是**"交货总数"**。据此判定:

一行 = 一个销售订单行项目(SalesDocument + SalesDocumentItem) 交货数量与开票金额是跨该订单行的所有交货/发票的合计值。

这个判定直接决定了后面要不要做聚合视图。如果客户实际想要"一行 = 一个订单行 × 一个交货行 × 一个发票行"的明细粒度,请在第 4 步之前告知——那样可以省掉两个聚合视图,但导出后行数会成倍膨胀。

1.3 31 列字段映射表

字段名均为本地线上源码中已实际编译通过的写法(来源见"实证出处"列)。

#

列

模板位置

字段 / 表达式

来源视图

实证出处

1

销售凭证(销售订单号)

A

SalesDocument

I_SalesDocumentItem

SD002 主键

2

订单类型

B

SalesDocumentType

I_SalesDocument

zcl_query_sd002 L473

3

订单类型描述

C

SalesDocumentTypeName

I_SalesDocumentTypeText

L637-639

4

订单凭证日期

D

SalesDocumentDate

I_SalesDocument

L474

5

客户参考(客户 PO 号)

E

PurchaseOrderByCustomer

I_SalesDocument

L475

6

售达方

F

SoldToParty

I_SalesDocument

L476

7

客户名称

G

CustomerName

I_Customer

L640

8

销售组织

H

SalesOrganization

I_SalesDocument

L477

9

产品组描述

I

ProductGroupName

I_ProductGroupText_2

L649-651

10

订单行

J

SalesDocumentItem

I_SalesDocumentItem

SD002 主键

11

产品

K

Product

I_SalesDocumentItem

L503

12

项目描述

L

SalesDocumentItemText

I_SalesDocumentItem

L504

13

物料长文本

M

ProductDescription

I_ProductDescription ⚠️待确认

项目未用过,见附录 B

14

客户品名

N

YY1_ZKHPM_PRD ⚠️ 待定

I_Product

见 §1.7

15

SKU(客户)

O

MaterialByCustomer(标准)

I_SalesDocumentItem

见 §1.7

16

订单数量

P

CASE sddocumentcategory WHEN 'K'/'L' THEN targetquantity ELSE orderquantity END

I_SalesDocumentItem

L517-522

17

工厂

Q

Plant

I_SalesDocumentItem

L505

18

存储地点

R

StorageLocation

I_SalesDocumentItem

L506

19

订单含税单价

S

Subtotal1Amount / OrderQuantity

计算字段

L327-329(除法写法)

20

订单含税金额

T

Subtotal1Amount(退货取负)

I_SalesDocumentItem

L434-438

21

订单未税金额

U

Subtotal2Amount(退货取负)

I_SalesDocumentItem

L440-444

22

订单税额

V

Subtotal6Amount(退货取负)

I_SalesDocumentItem

L446-450

23

交易币别

W

TransactionCurrency

I_SalesDocumentItem

L507

24

汇率

X

PriceDetnExchangeRate

I_SalesDocumentItem

L509

25

拒绝原因

Y

口径未定:候选 A SDDocumentReason+文本 / 候选 B SalesDocumentRjcnReason

I_SalesDocument / I_SalesDocumentItem

见 §1.6

26

审批状态

Z

SalesDocApprovalStatus(被 YY1_ZREWORK_SDH 覆盖)+ SalesDocApprovalStatusDesc

I_SalesDocument + I_SalesDocApprovalStatusT

L482-488 / L662-664

27

创建日期

AA

CreationDate

I_SalesDocument

—

28

交货数量(交货总数)

AB

sum(ActualDeliveredQtyInBaseUnit)

I_DeliveryDocumentItem

L1159-1168

29

开票含税金额

AC

sum(Subtotal1Amount)

I_BillingDocumentItem

L809-812

30

开票未税金额

AD

sum(Subtotal2Amount)

I_BillingDocumentItem

L814-817

31

开票税额

AE

sum(Subtotal6Amount)

I_BillingDocumentItem

L831-846

⚠️ 第 26 列要注意:项目对"审批状态"做了业务覆盖——如果订单抬头自定义字段 YY1_ZREWORK_SDH 有值, 就用它,否则用标准的 SalesDocApprovalStatus。该字段已查清是"返工标记"(OA 传 2 时由 ZZCL_API_SD009 置 'D'),新报表必须沿用这个口径,否则状态显示与客户认知不一致。详见 §1.4。

1.4 哪些是自定义字段,哪些其实是标准字段

本节结论在复核后已修正。 初稿把第 15 列「SKU(客户)」也当成自定义字段,复核线上代码后改判为标准字段 MaterialByCustomer(理由见 §1.7)。现在真正需要自定义字段的只剩两列。

模板 31 列中,只有两列必须落到 Key User 自定义字段上:

模板列

字段

落点

备注

14 客户品名

YY1_ZKHPM_PRD(候选)

物料主数据

三个候选,附录 B V3 定夺

26 审批状态(覆盖)

YY1_ZREWORK_SDH

销售订单抬头

已确认,见下方

其余列全部是标准字段。项目里 YY1_ 命名空间的自定义字段在源码中出现过的有:

YY1_SKU_PRD    YY1_SHM_PRD    YY1_ZKHPM_PRD   YY1_CPDM   YY1_GYSPM
YY1_ZCPZT_PRD  YY1_SKU        YY1_ZKHPM       YY1_ZREWORK_SDH  ...(共 30+ 个)

后缀即落点:_PRD = 产品(物料)主数据;_SDH = 销售订单抬头;_SDI = 销售订单行。

YY1_ZREWORK_SDH 的作用已经查清(不再是待确认项):它存返工标记。 证据链:

  • ZZCL_API_SD009 收到 OA 的 salesdocapprovalstatus = '2'(返工)时, 调用 releaseApprovalRequest 放行,并额外把 YY1_ZREWORK_SDH 置为 'D':

    "实施状态
    CASE ls_req-salesdocapprovalstatus.
      WHEN '1'. "审批
        gv_entity = 'releaseApprovalRequest'.  lv_rework = ''.
      WHEN '2'. "返工 = 审批 + 返工标识
        gv_entity = 'releaseApprovalRequest'.  lv_rework = 'D'.
      WHEN '3'. "拒绝
        gv_entity = 'rejectApprovalRequest'.   lv_rework = ''.
    ENDCASE.
    

    以及 update_rework_flag 方法里 ls_cdata-d-yy1_zrework_sdh = i_rework.

  • 报表侧的口径(zcl_query_sd002.clas.abap L482-488):YY1_ZREWORK_SDH 有值就用它当审批状态显示, 否则用标准 SalesDocApprovalStatus。教程已沿用这个口径,无需再确认。

仍需确认的只有「客户品名」一列(附录 B V3):打开 Fiori 应用 「自定义字段」, 查看 YY1_ZKHPM_PRD / YY1_CPDM / YY1_SHM_PRD 的业务上下文与字段标签,确定哪一个才是"客户品名"。 确认后只需改第 4 步主视图里的一行。

1.5 验证截图

下面两张是本项目线上实际在用的 Fiori elements 页面模板与体系结构,本报表就是照此交付:

List Report 页面模板

图 1:清单报表(List Report)页面模板——筛选栏 + 表格 + 设置/导出工具栏。来源:docs/SAP官方开发培训课程/assets/UX406-.../ListReportFloorplan_Scr.png

Fiori elements 体系结构

图 2:SAP Fiori elements 体系结构——注解驱动 UI,后端 CDS 注解是唯一事实来源。来源:UX406-.../FioriElementsArchitecture.png


1.6 ⚠️ 模板第 25 列「拒绝原因」的口径——这是一处必须澄清的坑

复核线上代码后确认:这个"拒绝原因"没有唯一答案,而且我最初的理解是错的。 三条实证:

实证 1:OA 审批回传里根本没有拒绝原因。 审批结果回传接口结构 ZZS_SDI010_IN 全部字段只有 5 个:

WORKFLOWINTERNALID
COMPLETIONDATE
COMPLETIONTIME
SALESDOCAPPROVALSTATUS     ← 就一个状态码
SALESORDER

OA 传 salesdocapprovalstatus = 1(审批) / 2(返工) / 3(拒绝), SAP 侧由 ZZCL_API_SD009 分别调标准 OData 的 releaseApprovalRequest / rejectApprovalRequest (API_SALES_ORDER_SRV / API_CREDIT_MEMO_REQUEST_SRV / API_DEBIT_MEMO_REQUEST_SRV) ——标准审批 API 不接受、也不落任何拒绝文本。所以"OA 拒绝了,原因是什么"在系统里查不到。

实证 2:项目里的 SalesDocumentRjcnReason 被挪用成了"删除标记"。 ZZCL_API_SD001(销售订单创建接口)在收到外围系统的删除请求时,写的是:

MODIFY ENTITIES OF i_salesorderwithoutchargetp PRIVILEGED
ENTITY salesorderwithoutchargeitem
UPDATE FIELDS ( salesdocumentrjcnreason )
  WITH VALUE #( ( salesdocumentrjcnreason = '01'   "← 删除标记
                  %key-salesorderwithoutcharge     = ls_body-referencesddocument
                  %key-salesorderwithoutchargeitem = ls_body-referencesddocumentitem ) )

实证 3:全项目没有任何拒绝原因的文本视图。 I_SDDocumentReasonText 是 SDDocumentReason(订单原因,抬头)的文本视图,字段域与 SalesDocumentRjcnReason(行项目)完全不同, 两者不能互连。

两个候选口径:

候选 A:订单原因 SDDocumentReason

候选 B:行项目拒绝原因 SalesDocumentRjcnReason

位置

抬头 I_SalesDocument

行项目 I_SalesDocumentItem

文本视图

✅ I_SDDocumentReasonText(项目已验证,zcl_query_sd002 L656-658)

❌ 项目未用过,需自行在 ADT 已发布对象视图里找

项目用法

正经的业务字段,且已随审批请求发给 OA(ZZS_SDI009_REQ-SDDOCUMENTREASON)

被集成接口当删除标记('01')

业务含义

订单原因(细分订单类型,见《销售订单专题》第 26 页「订单原因(细分订单类型)」表)

行项目的拒绝/失效原因

现有先例

现有报表 SD002 的"订单原因"列

现有报表 SD002 的"拒绝原因"列(只出代码,无文本)

教程默认取候选 A(因为它是唯一有标准文本、经项目验证、且真正走审批链路的字段), 代码里两个候选都放进视图了。开工前必须找李婕确认一句(附录 B V8)。

1.7 ⚠️ 模板第 15 列「SKU(客户)」——标准字段优先

我最初直接用了自定义字段 YY1_SKU_PRD。复核后改判:优先用标准字段 MaterialByCustomer,理由:

  1. I_SalesDocumentItem.MaterialByCustomer(客户物料号)在项目里被广泛使用—— 建单接口 ZZFM_API_SALES_DOCUMENTS_PRC、Job ZZCL_JOB_SD004、以及现有报表视图 ZR_QUERY_SD001_I / ZC_QUERY_SD001_I 都在用;

  2. 上线支持问题清单第 195 条原文:「销售发货明细报表添加 创建人 和客户物料编码(SKU) 字段」 ——客户的原话就是"客户物料编码(SKU)",对应的正是 standard MaterialByCustomer;

  3. 审批接口 ZZS_SDI009_ITEM_IN 也带 MATERIALBYCUSTOMER,说明这条链路上它是有值的。

但仍有不确定性:SD002 的实体里声明的是 YY1_SKU_PRD //I_Product-YY1_SKU_PRD(物料主数据上的自定义字段)。 两个字段可能都有值但口径不同(一个是订单上手工填的客户料号,一个是物料主数据上维护的客户料号)。

做法:教程用 Item.MaterialByCustomer,并保留 Product.YY1_SKU_PRD 作为注释掉的备选。 附录 B V3 的核对脚本会一次性把两个字段都拉出来比对——如果两者值不同,请业务确认以哪个为准。

同理,第 14 列「客户品名」标准字段确实没有对应项,只能用自定义字段 (YY1_ZKHPM_PRD / YY1_CPDM / YY1_SHM_PRD 三个候选,见附录 B V3)。


2. 技术选型:为什么是这条路线

2.1 环境给出的硬约束

本项目是 S/4HANA Cloud Public Edition,开发走 ABAP Cloud(开发者扩展)。这不是可选项,是平台强制:

「并非所有方法都与云原生方法的需求兼容,因此在 ABAP Cloud 中仅使用其中的子集。例如,禁止使用 TABLES 语句等过时关键字。同样禁止 Dynpro 和 Web Dynpro……禁止直接在 SAP 表上使用 SELECT 语句代替使用核心数据服务。」 —— S4D426 / 03-深入探索_ABAP_Cloud / 02-Exploring_ABAP_Cloud.md

「客户同意仅在其新开发中使用公共发布的接口。实际上,这是通过语法检查和 ABAP 测试主控室检查在 Eclipse 的 ABAP 开发工具中强制执行的」 —— S4D426 / 03-... / 05-Exploring_Released_APIs.md

所以:不能用 SE80 / SE38 / SE11 老办法,不能 SELECT FROM vbak。报错长这样:

不允许使用表 T005。改用 CDS 实体 I_COUNTRY。

这意味着:数据源只能是 I_* / C_* / Z* 已发布 CDS 视图,交付形态只能是 Fiori。

ABAP 公有云 API

图 3:ABAP 公有云上的 API 与扩展点分类。来源:S4D426/.../ABAP_Public_Cloud_APIs_001.png

扩展模型

图 4:S/4HANA Cloud 的三类扩展——关键用户扩展(类型 1)、开发人员扩展(类型 2)、并排扩展(类型 3)。本报表走类型 2。来源:S4D426/.../Extensibility_Model_001.png

三条不可逾越的扩展原则(S4D426 单元 04,逐字):

  1. 「扩展只能在 SAP S/4HANA Cloud 中作为堆栈内扩展在内部实施,或者作为在 SAP BTP 上运行的并排扩展在外部实施。」

  2. 「扩展只能使用已发布的本地或远程公共 SAP API 和业务加载项以及 ABAP RESTful 应用程序编程模型业务对象扩展点。」

  3. 「扩展只能使用启用云和发布的技术实施。」

2.2 三个候选方案对比

方案 A:纯 CDS 视图实体链(本教程主线)

方案 B:custom entity + if_rap_query_provider(项目现行范式)

方案 C:Custom Analytical Query(关键用户)

数据获取

CDS join / association,下推到 HANA

ABAP 类里写 SELECT + 内存处理

关键用户拖拽建模

分页 / 排序 / 过滤

框架自动,下推数据库

手写:ZZCL_QUERY_UTILS=>filtering/orderby/paging

框架自动

代码量

只在 DDL 里,无 ABAP 类

每个报表几百到上千行 ABAP

无代码

性能

好(只取当前页)

差(全量拉到应用层再切片)

好

复杂逻辑

受 CDS 表达力限制

无限制(循环、调函数、读自定义表)

受工具限制

事务一致性

只读,无

只读,无

只读,无

本项目先例

少(ZR_QUERY_* 有,但消费层多为 custom entity)

主力:ZC_QUERY_SD001~SD016、ZZCL_QUERY_* 一大批

未使用

Clean Core 级别

A

A(只用已发布视图)

A

2.3 推荐结论

主推方案 A(纯 CDS),理由:

  1. 本报表的全部数据都能在 CDS 里表达——订单行驱动,交货数量与开票金额各做一级聚合后 LEFT JOIN 回来。没有需要循环、需要读外部系统、需要动态拼接 SQL 的地方。

  2. 分页下推是真实收益。销售订单明细动辄几十万行,方案 B 的 ZZCL_QUERY_UTILS=>paging 是把全量结果集拉到应用服务器再切片,数据量上来后必然成为瓶颈。

  3. 少一个 ABAP 类就少一个维护点。方案 B 的查询实现类普遍 1000+ 行(zcl_query_sd002.clas.abap 就有 1423 行),单元测试成本高。

  4. 这正是 SAP 培训里 Day4 讲的"报表标准骨架"的纯 CDS 版本,符合 Clean Core 级别 A。

什么时候必须退回方案 B(写清楚,免得走错):

  • 过滤器要作用在聚合结果上(如"只看交货数量 > 0 的订单行")——CDS 里 WHERE 不能引用聚合别名;

  • 需要跨系统取数(调 OData、读外部接口结果表);

  • 需要逐行迭代计算(如按批次分龄、按配置表动态展开);

  • 需要自由文本搜索作用在计算字段上,且 CDS 的 @Search 满足不了。

只要出现其中一条,就用附录 A 的范式改写——它和本教程前面 3 步完全兼容,只需要把"消费视图"换成 custom entity、把数据获取从 DDL 挪进实现类。


3. 开工准备

3.1 账号与角色

事项

要求

开发租户

D 系统(Dev/Starter)my201458,client 100,语言 ZH

后端用户

CB9980000000(IdP jeff@kexcelled3d.com SSO 映射)

业务角色模板

SAP_BR_ADMINISTRATOR、SAP_BR_DEVELOPER、SAP_BR_BPC_EXPERT、SAP_BR_EXTENSIBILITY_SPEC

⚠️ 本项目纪律:任何连接生产/开发系统的动作都要先征得同意(锁账号风险)。默认只做离线分析。 Eclipse ADT 是当前可用通道;VS Code 的 abapfs 因 SSO 尚未打通。

3.2 工具

工具

用途

版本要求

Eclipse + ADT(ABAP Development Tools)

建 CDS、服务定义/绑定

ADT 3.16 或以上

BAS(Business Application Studio)

生成 Fiori elements 应用

BTP 试用账户已订阅

浏览器

Fiori 应用测试

—

3.3 编号占用核查(先做这一步)

本项目 SD 查询类对象编号现状(已扫本地源码导出包):

CDS 消费视图  ZC_QUERY_SD001 ~ SD016   (SD003 未用)
服务定义/绑定 ZUI_QUERY_SD001 ~ SD016
查询实现类    ZCL_QUERY_SD002 / SD004,ZZCL_QUERY_SD001 / SD005 ~ SD017
              ⚠️ ZZCL_QUERY_SD017 是空壳类(无实现、无对应视图)

本教程取 SD018。开工前请与 陈锦财(SD 报表开发负责人)确认 SD018 未被预订。

3.4 对象命名清单(本项目命名规范)

对象

名称

规范依据

交货数量聚合视图

ZR_QUERY_SD018_DN

ZR_* = Root/基础 CDS

开票行视图

ZR_QUERY_SD018_BILL

同上

开票聚合视图

ZR_QUERY_SD018_BILLA

同上

主查询视图

ZR_QUERY_SD018

同上

消费视图

ZC_QUERY_SD018

ZC_* = Consumption

元数据扩展

ZC_QUERY_SD018

与目标视图同名

访问控制

ZC_QUERY_SD018

与受保护实体同名(官方强建议)

服务定义

ZUI_QUERY_SD018_O4

ZUI_* + _O4 = OData V4

服务绑定

ZUI_QUERY_SD018_O4

与 srvd 同名

Fiori 应用(UI5 仓库)

ZZQUERYSD018_UI5R

对齐 ZZQUERYSD002_UI5R

IAM 应用

ZZSD018_EXT

对齐 ZZSD002_EXT

业务目录

ZBC_SD_0018

ZBC_*

业务角色

ZBR_SD_ORDER_DETAIL

—

全部对象所在包

ZZSD

—

3.5 建议的开发顺序与自检点

① ZR_QUERY_SD018_DN  ─┐
② ZR_QUERY_SD018_BILL ─┼→ ④ ZR_QUERY_SD018 → ⑤ ZC_QUERY_SD018 → ⑥ DDLX
③ ZR_QUERY_SD018_BILLA ┘         ↓
                        ⑦ DCL(权限)→ ⑧ srvd + srvb → ⑨ 预览
                                                      ↓
                        ⑩ BAS 生成 App → ⑪ 部署 → ⑫ IAM/Catalog/Role

每个 ZR_ 视图激活后,立刻用 ADT 的 Data Preview(F8)看数据,别攒到最后一起调。


Step 1 — 建查询基视图(ZR_ 层)

在 Eclipse ADT 中:右键包 ZZSD → New → ABAP Repository Object → Core Data Services → Data Definition。

ADT 新建 Data Definition

图 5:ADT 新建 ABAP 资源库对象对话框,选「Core Data Services → Data Definition」。来源:本项目 docs/12、SAP公有云开发培训/Day4_S4HC_Embedded Analytics_练习脚本.docx 第 4 张截图

1.1 交货数量聚合视图 ZR_QUERY_SD018_DN

为什么要单独一个视图:一个销售订单行可能对应 0~N 个交货行。如果直接把 I_SalesDocumentItem 和 I_DeliveryDocumentItem 放在一个 SELECT 里,订单行会按交货行数复制, 后续再 JOIN 开票就会再次翻倍(行数膨胀 / fan-out),金额全错。

所以:先在交货侧聚合到"订单行"粒度,再 JOIN 回订单行。

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: '销售订单明细报表-交货数量聚合'
@ObjectModel.usageType: { serviceQuality: #C, sizeCategory: #L, dataClass: #TRANSACTIONAL }
define view entity ZR_QUERY_SD018_DN
  as select from I_DeliveryDocumentItem as DeliveryItem
{
      // ---- 键:回到销售订单行 ----
  key DeliveryItem.ReferenceSDDocument     as SalesDocument,
  key DeliveryItem.ReferenceSDDocumentItem as SalesDocumentItem,

      // ---- 交货数量:退货交货取负,与项目既有口径一致 ----
      sum(
        case DeliveryItem.ReturnsDeliveryItemCode
          when 'X' then -DeliveryItem.ActualDeliveredQtyInBaseUnit
          else          DeliveryItem.ActualDeliveredQtyInBaseUnit
        end
      )                                        as DeliveredQuantity
}
group by
      DeliveryItem.ReferenceSDDocument,
      DeliveryItem.ReferenceSDDocumentItem

逐点说明:

  • ReferenceSDDocument / ReferenceSDDocumentItem —— 交货行回指的销售订单 / 订单行。 实证:zcl_query_sd002.clas.abap L1159-1168 就是这三个字段(含 ActualDeliveredQtyInBaseUnit)做的同样聚合。

  • ReturnsDeliveryItemCode = 'X' 取负 —— 退货交货的数量要冲减。 实证:SD002 L752-756 用的是完全相同的 CASE ... WHEN 'X' THEN - ...。

  • 故意不暴露单位字段。如果把 BaseUnit 也放进 SELECT,就必须进 GROUP BY; 一旦同一订单行存在基础单位不一致的交货,聚合就会被拆成两行,JOIN 回去又变成行放大。 单位统一从订单行侧取,见 4.4 节。

  • @AccessControl.authorizationCheck: #NOT_REQUIRED —— 中间视图不单独做权限, 权限在最终消费视图(Step 3)统一控制。这是项目既有做法(ZR_* 层普遍不挂 DCL)。

⚠️ WHERE 子句要不要加:本视图没有加交货单状态过滤。 理由是 ActualDeliveredQtyInBaseUnit 本身就是"实际已交货数量",未过账的发货不会计入。 如果验收时发现已取消的交货单仍被计入,在 as select from 后补 inner join I_DeliveryDocument as Delivery on Delivery.DeliveryDocument = DeliveryItem.DeliveryDocument 并在 where 加取消标志判断(取消标志的确切字段名请用附录 B 脚本 V2 核实,不要猜)。

1.2 开票行视图 ZR_QUERY_SD018_BILL

为什么开票要拆成两个视图:开票行挂在销售订单上,有两条完全不同的路径 (这一点是项目的关键业务知识,藏在 zcl_query_sd002.clas.abap L847-856):

路径

ReferenceSDDocumentCategory

关联方式

订单类

'K' 贷项凭证请求、'L' 借项凭证请求

发票行的 SalesDocument / SalesDocumentItem 直接指向销售凭证

交货类

'J' 交货、'T' 退货交货

发票行经 ReferenceSDDocument 指向交货单,要再跳一层才到订单

两条路径必须 union all 合起来;而 union 之后不能再聚合,所以聚合要放到下一个视图。

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: '销售订单明细报表-开票行(订单类)'
@ObjectModel.usageType: { serviceQuality: #C, sizeCategory: #L, dataClass: #TRANSACTIONAL }
@Metadata.ignorePropagatedAnnotations: true
define view entity ZR_QUERY_SD018_BILL
  as select from I_BillingDocumentItem as BillingItem
    inner join I_BillingDocument as Billing
      on  Billing.BillingDocument = BillingItem.BillingDocument
      and Billing.BillingDocumentIsCancelled = ''
      and Billing.CancelledBillingDocument    = ''
{
  key BillingItem.SalesDocument     as SalesDocument,
  key BillingItem.SalesDocumentItem as SalesDocumentItem,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case BillingItem.ReturnItemProcessingType
        when 'X' then -BillingItem.Subtotal1Amount
        else          BillingItem.Subtotal1Amount
      end                            as BilledAmountInclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case BillingItem.ReturnItemProcessingType
        when 'X' then -BillingItem.Subtotal2Amount
        else          BillingItem.Subtotal2Amount
      end                            as BilledAmountExclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case BillingItem.ReturnItemProcessingType
        when 'X' then -BillingItem.Subtotal6Amount
        else          BillingItem.Subtotal6Amount
      end                            as BilledTaxAmount,

      BillingItem.TransactionCurrency as TransactionCurrency
}
where BillingItem.ReferenceSDDocumentCategory in ( 'K', 'L' )

union all

@EndUserText.label: '销售订单明细报表-开票行(交货类)'
  select from I_BillingDocumentItem as BillingItem
    inner join I_BillingDocument as Billing
      on  Billing.BillingDocument = BillingItem.BillingDocument
      and Billing.BillingDocumentIsCancelled = ''
      and Billing.CancelledBillingDocument    = ''
    inner join I_DeliveryDocumentItem as DeliveryItem
      on  DeliveryItem.DeliveryDocument     = BillingItem.ReferenceSDDocument
      and DeliveryItem.DeliveryDocumentItem = BillingItem.ReferenceSDDocumentItem
{
  key DeliveryItem.ReferenceSDDocument     as SalesDocument,
  key DeliveryItem.ReferenceSDDocumentItem as SalesDocumentItem,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case BillingItem.ReturnItemProcessingType
        when 'X' then -BillingItem.Subtotal1Amount
        else          BillingItem.Subtotal1Amount
      end                                    as BilledAmountInclTax,
      /* 其余字段同上 */
      BillingItem.TransactionCurrency        as TransactionCurrency
}
where BillingItem.ReferenceSDDocumentCategory in ( 'J', 'T' )

逐点说明:

  • BillingDocumentIsCancelled = '' / CancelledBillingDocument = '' —— 排除已冲销发票。 实证:SD002 L858-860 的判断。注意:ABAP 里写 IS INITIAL,CDS 里不能照抄—— 本项目 57 个 CDS 视图(.asddls)中 IS [NOT] INITIAL 出现 0 次, 而 = '' / <> '' 有已激活的实例 (sap-fi-master/src/zr_vh_zjsph.ddls.asddls L15、sap-zzmm-master/src/zc_materialdocumentheader_tims.ddls.asddls L19)。 教程按项目实证写 = '';若某处语法检查报错,退回 = ' '(单空格)。

  • case ... end 取负用 ReturnItemProcessingType = 'X' 判定退货。 实证:SD002 L809-846 全篇同一写法。

  • 第二个分支的完整字段必须与第一个分支逐个对齐(数量、顺序、类型都要一致), 且 元素注释只能出现在第一个 SELECT 分支,第二个分支写注释会报语法错误。这是 CDS union 的硬规则:

    「元素名称:对于元素列表中的每一列,直接元素名称或别名必须匹配。」 「关键要素:所有元素列表的关键元素必须匹配。」「元素注释:只有第一个 SELECT 语句的元素列表才能定义元素注释。」 —— S4D430 / 06-在_CDS_视图中使用代码下推 / 04-Processing_Data_Sets_in_CDS_Views.md

  • @Metadata.ignorePropagatedAnnotations: true —— 含 union 的 CDS 视图必须加,否则注解传播会冲突。

  • 上面第二个分支我用 /* 其余字段同上 */ 省略了,实际编码时必须逐个写全。

1.3 开票聚合视图 ZR_QUERY_SD018_BILLA

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: '销售订单明细报表-开票金额聚合'
@ObjectModel.usageType: { serviceQuality: #C, sizeCategory: #L, dataClass: #TRANSACTIONAL }
define view entity ZR_QUERY_SD018_BILLA
  as select from ZR_QUERY_SD018_BILL as BillingLine
{
  key BillingLine.SalesDocument     as SalesDocument,
  key BillingLine.SalesDocumentItem as SalesDocumentItem,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      sum( BillingLine.BilledAmountInclTax ) as BilledAmountInclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      sum( BillingLine.BilledAmountExclTax ) as BilledAmountExclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      sum( BillingLine.BilledTaxAmount )     as BilledTaxAmount,

      BillingLine.TransactionCurrency        as TransactionCurrency
}
group by
      BillingLine.SalesDocument,
      BillingLine.SalesDocumentItem,
      BillingLine.TransactionCurrency

为什么这里的 TransactionCurrency 可以进 GROUP BY 而交货单位不行? 因为同一订单行的开票币别在业务上必然一致(都来自同一张订单的定价);即使极端情况出现两种币别, 拆成两行也是正确结果(金额不能跨币别相加)。而数量单位若被拆开则是错误结果。 这就是聚合建模里"哪些维度可以进 GROUP BY"的判断标准。

CDS 聚合语法要点(来自 S4D430 / 06-.../04-...md):

  • AS 在 CDS 里是必需的(ABAP SQL 里可选);

  • GROUP BY 必须列出元素列表中所有非聚合字段;

  • avg() 必须指定结果类型,如 avg( x as abap.dec(11,1) );

  • CDS 视图不支持 ORDER BY(排序交给 Fiori 表格)。

1.4 主查询视图 ZR_QUERY_SD018

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: '销售订单明细报表-主查询'
@ObjectModel.usageType: { serviceQuality: #C, sizeCategory: #L, dataClass: #TRANSACTIONAL }
define view entity ZR_QUERY_SD018
  as select from I_SalesDocumentItem as Item
    inner join I_SalesDocument as Header
      on Header.SalesDocument = Item.SalesDocument

    left outer join ZR_QUERY_SD018_DN    as DeliverySum
      on  DeliverySum.SalesDocument     = Item.SalesDocument
      and DeliverySum.SalesDocumentItem = Item.SalesDocumentItem

    left outer join ZR_QUERY_SD018_BILLA as BillingSum
      on  BillingSum.SalesDocument      = Item.SalesDocument
      and BillingSum.SalesDocumentItem  = Item.SalesDocumentItem

    left outer join I_Customer as Customer
      on Customer.Customer = Header.SoldToParty

    left outer join I_SalesDocumentTypeText as DocTypeText
      on  DocTypeText.SalesDocumentType = Header.SalesDocumentType
      and DocTypeText.Language          = $session.system_language

    left outer join I_SalesOrganizationText as SalesOrgText
      on  SalesOrgText.SalesOrganization = Header.SalesOrganization
      and SalesOrgText.Language          = $session.system_language

    left outer join I_ProductGroupText_2 as ProductGroupText
      on  ProductGroupText.ProductGroup = Item.ProductGroup
      and ProductGroupText.Language     = $session.system_language

    left outer join I_SDDocumentReasonText as OrderReasonText
      on  OrderReasonText.SDDocumentReason = Header.SDDocumentReason
      and OrderReasonText.Language          = $session.system_language

    left outer join I_SalesDocApprovalStatusT as ApprStatusText
      on  ApprStatusText.SalesDocApprovalStatus = Header.SalesDocApprovalStatus
      and ApprStatusText.Language               = $session.system_language

    left outer join I_StorageLocation as StorageLocationText
      on  StorageLocationText.StorageLocation = Item.StorageLocation
      and StorageLocationText.Plant           = Item.Plant

    left outer join I_Product as Product
      on Product.Product = Item.Product
{
      // ============ 键 ============
  key Item.SalesDocument                        as SalesDocument,
  key Item.SalesDocumentItem                    as SalesDocumentItem,

      // ============ 权限用(UI 隐藏)============
      Header.SalesOrganization                  as SalesOrganization,
      Header.DistributionChannel                as DistributionChannel,
      Item.OrganizationDivision                 as OrganizationDivision,

      // ============ 模板 1~9:抬头信息 ============
      Header.SalesDocumentType                  as SalesDocumentType,
      DocTypeText.SalesDocumentTypeName         as SalesDocumentTypeName,
      Header.SalesDocumentDate                  as SalesDocumentDate,
      Header.PurchaseOrderByCustomer            as PurchaseOrderByCustomer,
      Header.SoldToParty                        as SoldToParty,
      Customer.CustomerName                     as CustomerName,
      SalesOrgText.SalesOrganizationName        as SalesOrganizationName,
      ProductGroupText.ProductGroupName         as ProductGroupName,

      // ============ 模板 10~18:行项目信息 ============
      Item.Product                              as Product,
      Item.SalesDocumentItemText                as SalesDocumentItemText,
      Product.ProductDescription                as ProductDescription,      // ⚠️视图名待确认,见附录B V4
      // 模板 15:SKU(客户)—— 优先用标准字段(见 §1.7)
      Item.MaterialByCustomer                   as CustomerSKU,
      // 若客户的"SKU(客户)"实际指物料主数据上的自定义字段,改用下面这行:
      // Product.YY1_SKU_PRD                    as CustomerSKU,
      // 模板 14:客户品名 —— 标准字段没有对应项,只能取自定义字段(附录 B V3)
      Product.YY1_ZKHPM_PRD                     as CustomerProductName,
      Item.RequestedQuantityUnit                as OrderQuantityUnit,
      Item.Plant                                as Plant,
      Item.StorageLocation                      as StorageLocation,
      StorageLocationText.StorageLocationName   as StorageLocationName,

      // ============ 模板 16、19~24:数量与金额 ============
      @Semantics.quantity.unitOfMeasure: 'OrderQuantityUnit'
      case Item.SDDocumentCategory
        when 'K' then Item.TargetQuantity
        when 'L' then Item.TargetQuantity
        else          Item.OrderQuantity
      end                                       as OrderQuantity,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case Item.IsReturnsItem
        when 'X' then -Item.Subtotal1Amount
        else          Item.Subtotal1Amount
      end                                       as OrderAmountInclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case Item.IsReturnsItem
        when 'X' then -Item.Subtotal2Amount
        else          Item.Subtotal2Amount
      end                                       as OrderAmountExclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case Item.IsReturnsItem
        when 'X' then -Item.Subtotal6Amount
        else          Item.Subtotal6Amount
      end                                       as OrderTaxAmount,

      // 模板 19:订单含税单价 = 订单含税金额 ÷ 订单数量(除法细节见 §2.3)
      @Semantics.amount.currencyCode: 'TransactionCurrency'
      case
        when Item.OrderQuantity <> 0
        then cast( Item.Subtotal1Amount as abap.fltp ) / cast( Item.OrderQuantity as abap.fltp )
        else 0
      end                                       as OrderPriceInclTaxPerUnit,

      Item.TransactionCurrency                  as TransactionCurrency,
      Item.PriceDetnExchangeRate                as PriceDetnExchangeRate,

      // ============ 模板 25~27:状态与日期 ============
      // ⚠️ 模板第 25 列"拒绝原因"的口径未定,两种候选都列出来,
      //    见 §1.6 与附录 B V8 —— 定稿后删掉不用的那一组
      // 候选 A:订单原因(VBAK,有标准文本视图,项目已验证)
      Header.SDDocumentReason                   as SDDocumentReason,
      OrderReasonText.SDDocumentReasonText      as SDDocumentReasonText,
      // 候选 B:行项目拒绝原因(VBAP,项目未配文本视图,只出代码)
      Item.SalesDocumentRjcnReason              as SalesDocumentRjcnReason,

      // 审批状态:自定义返工标记优先,否则用标准字段(沿用项目口径,见 §1.4)
      case
        when Header.YY1_ZREWORK_SDH = '' or Header.YY1_ZREWORK_SDH = ' '
        then Header.SalesDocApprovalStatus
        else Header.YY1_ZREWORK_SDH
      end                                       as SalesDocApprovalStatus,
      ApprStatusText.SalesDocApprovalStatusDesc as SalesDocApprovalStatusDesc,

      Header.CreationDate                       as CreationDate,

      // ============ 模板 28~31:交货与开票聚合 ============
      @Semantics.quantity.unitOfMeasure: 'OrderQuantityUnit'
      coalesce( DeliverySum.DeliveredQuantity, 0 )   as DeliveredQuantity,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      coalesce( BillingSum.BilledAmountInclTax, 0 )  as BilledAmountInclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      coalesce( BillingSum.BilledAmountExclTax, 0 )  as BilledAmountExclTax,

      @Semantics.amount.currencyCode: 'TransactionCurrency'
      coalesce( BillingSum.BilledTaxAmount, 0 )      as BilledTaxAmount

}
where Header.SalesDocumentType <> 'AG'      // 排除报价单(AG),只留订单类凭证

逐点说明:

  • I_SalesDocumentItem 是驱动表,其余全部 left outer join(或文本表 inner 也行,但 left 更安全)。 驱动表选错是这类报表最常见的错误来源。

  • coalesce(..., 0) —— 没有交货/没有开票的订单行,LEFT JOIN 出来是 NULL。 报表里 NULL 会显示成空白,金额列体验很差,所以补 0。

  • $session.system_language 用于取文本表当前语言。 实证:SD002 用的是 @sy-langu(ABAP SQL 写法);CDS 里对应写法是 $session.system_language。

    「在 ABAP CDS 视图实体中,您可以使用会话变量访问 ABAP 系统字段的值……目前提供六个内置会话变量。」 对照表:$session.client→sy-mandt、$session.system_date→sy-datum、$session.system_language→sy-langu、$session.user→sy-uname、$session.user_date→sy-datlo、$session.user_timezone→sy-zonlo —— S4D430 / 06-.../02-Calling_Built-in_Functions_in_CDS_Views.md(值表来自配图 Session_Variables_001.png)

    会话变量与 ABAP 系统字段对照表

    图 6:六个会话变量与 ABAP 系统字段的对照——$session.system_language 对应 sy-langu,文本表取当前登录语言就靠它。来源:S4D430 / 06-.../02-Calling_Built-in_Functions_in_CDS_Views.md 配图 Session_Variables_001.png

    ⚠️ 使用时要知道的坑:

    「**仅当读取请求来自 ABAP 系统时,会话变量才包含值。在任何其他情况下,会话变量的值均未定义!**这就是您应该选择输入参数来访问 ABAP 系统字段的原因。」

    我们的场景是 OData 服务由 ABAP 栈自己提供,会话变量有效,可以放心用。 但如果以后要把这个视图做成远程 API 给别人调,就得改成输入参数 + @Environment.systemField: #SYSTEM_LANGUAGE。 对照表见配图 Default_Value_for_Parameters_in_Open_SQL_002.png(七值:#CLIENT/#SYSTEM_DATE/#SYSTEM_TIME/#SYSTEM_LANGUAGE/#USER/#USER_DATE/#USER_TIMEZONE)。

    输入参数缺省值注解对照表

    图 7:输入参数的缺省值注解——#SYSTEM_LANGUAGE 等七个值分别绑定 ABAP 系统字段,是「视图被远程 API 调用」时代替会话变量的写法。来源:S4D430 / 06-.../03-Defining_CDS_Views_with_Input_Parameters.md 配图 Default_Value_for_Parameters_in_Open_SQL_002.png。⚠️ 课件中文是机器翻译(如 #客户端#),代码里一律用英文枚举

  • where Header.SalesDocumentType <> 'AG' —— 项目把报价单类型定为 AG。 实证:SD002 L316 WHERE a~salesdocumenttype = 'AG'。排除它是因为模板要的是"销售订单明细",不是报价明细。 如果客户要包含报价,删掉这个 where 即可。

  • @Semantics.quantity.unitOfMeasure / @Semantics.amount.currencyCode 必须成对出现:

    「在 CDS 视图实体中,必须使用注释 @Semantics.amount.currencyCode 将金额元素链接到货币代码元素。同样,必须使用注释 @Semantics.quantity.unitOfMeasure 将数量元素链接到单位元素。」 —— S4D430 / 04-定义基本_CDS_视图 / 02-Using_ABAP_Annotations_in_CDS_Views.md 漏了注解,Fiori 表格里数量和金额会没有单位/币别,也不能正确合计。

  • YY1_ZREWORK_SDH 直接来自 I_SalesDocument(因为它是挂在 VBAK 上的自定义字段,会自动出现在该视图里)。 实证:SD002 L482-488 用的就是这个字段,逻辑一模一样。

1.5 检查点 ✅

对每个 ZR_ 视图按 F8(Data Preview)验证:

检查

期望

ZR_QUERY_SD018_DN

一个订单行只有一行。用 SELECT COUNT(*) 对比 COUNT(DISTINCT SalesDocument, SalesDocumentItem),两者相等

ZR_QUERY_SD018_BILL

行数 ≈ 开票行数(两个分支之和)

ZR_QUERY_SD018_BILLA

一个订单行一行

ZR_QUERY_SD018

行数必须等于 I_SalesDocumentItem 中非 AG 类型的行数。多一行都说明 JOIN 放大了

🔍 行数校验是这一步的核心。只要 ZR_QUERY_SD018 行数对得上,后面的金额就不可能错; 对不上,先回来查聚合视图,别往下走。


Step 2 — 建消费视图与元数据扩展(ZC_ 层)

2.1 消费视图 ZC_QUERY_SD018

@AccessControl.authorizationCheck: #CHECK
@EndUserText.label: '销售订单明细报表'
@Metadata.allowExtensions: true
@Metadata.ignorePropagatedAnnotations: true
@ObjectModel.usageType: { serviceQuality: #C, sizeCategory: #L, dataClass: #TRANSACTIONAL }
@ObjectModel.semanticKey: [ 'SalesDocument', 'SalesDocumentItem' ]
@Search.searchable: true
define root view entity ZC_QUERY_SD018
  provider contract transactional_query
  as projection on ZR_QUERY_SD018
{
  key SalesDocument,
  key SalesDocumentItem,

      SalesOrganization,
      DistributionChannel,
      OrganizationDivision,

      SalesDocumentType,
      SalesDocumentTypeName,
      SalesDocumentDate,
      PurchaseOrderByCustomer,
      SoldToParty,
      @Search.defaultSearchElement: true
      CustomerName,
      SalesOrganizationName,
      ProductGroupName,

      @Search.defaultSearchElement: true
      Product,
      @Search.defaultSearchElement: true
      SalesDocumentItemText,
      ProductDescription,
      CustomerProductName,
      CustomerSKU,
      OrderQuantityUnit,

      @Search.defaultSearchElement: true
      Plant,
      StorageLocation,
      StorageLocationName,

      OrderQuantity,
      OrderPriceInclTaxPerUnit,
      OrderAmountInclTax,
      OrderAmountExclTax,
      OrderTaxAmount,
      TransactionCurrency,
      PriceDetnExchangeRate,

      SalesDocumentRjcnReason,
      SDDocumentReason,
      SDDocumentReasonText,
      SalesDocApprovalStatus,
      SalesDocApprovalStatusDesc,
      CreationDate,

      DeliveredQuantity,
      BilledAmountInclTax,
      BilledAmountExclTax,
      BilledTaxAmount
}

要点:

  • @AccessControl.authorizationCheck: #CHECK —— 值含义(来自 S4D430 / 07-.../01-...md 与配图 05AnnotationAccessControl_001.png):

    值

    含义

    #NOT_REQUIRED

    缺省值。有 DCL 就评估,没有也不报警

    #CHECK

    同上,但没有 DCL 保护时语法检查报警告

    #MANDATORY

    同 #CHECK,但没有 DCL 时运行时抛错

    #NOT_ALLOWED

    不做访问控制;若分配了 DCL 则警告且运行时忽略

    #PRIVILEGED_ONLY

    只能通过 WITH PRIVILEGED ACCESS 访问

    用 #CHECK 的理由:它会在你忘记写 DCL 时给出编译期警告,是自查手段。

    authorizationCheck 的五个取值

    图 8:@AccessControl.authorizationCheck 的五个取值——缺省 #NOT_REQUIRED、#CHECK、#MANDATORY、#NOT_ALLOWED、#PRIVILEGED_ONLY。来源:S4D430 / 07-.../01-Preventing_Unauthorized_Access_to_Data.md 配图 05AnnotationAccessControl_001.png(图中中文枚举是机翻,代码用英文)

  • @Metadata.allowExtensions: true —— 必须加,否则下一步建不了元数据扩展:

    「作为创建 CDS 元数据扩展的前提条件,目标实体的所有者已通过将 @Metadata.allowExtensions: true 添加到定义显式允许此操作。」

  • @Search.searchable: true + @Search.defaultSearchElement: true —— 开启 Fiori 筛选栏的全局搜索框。

  • @ObjectModel.semanticKey —— 让 Fiori 表格整行高亮(项目既有做法,见 zc_query_sd002.ddls.asddls 的注释"设置列高亮")。

  • provider contract transactional_query + define root view entity —— 只读查询契约,配合 OData V4 UI 绑定。 实证:zc_query_sd001_h.ddls.asddls 的写法就是 define root view entity ZC_QUERY_SD001_H provider contract transactional_query as projection on Zr_Query_Sd001_H, 与本教程完全同构。

    📌 知识缺口提示:define root view entity 这个写法不在本目录的培训课件覆盖范围内 (S4D430 只讲 define view entity)。本教程的写法以线上源码为准,不靠推测。 区别是:root + transactional_query 声明这是可被 RAP 服务消费的根实体; 纯中间层视图(ZR_*)用普通 define view entity 即可。

  • 视图头还可以加两个可选注解(S4D430 单元 04 的标准注解块):

    @AbapCatalog: {
      dataMaintenance:        #RESTRICTED,     // 限制 ADT 数据预览中的维护操作
      viewEnhancementCategory: [#NONE]         // 不允许被 CDS 扩展扩展
    }
    

    含义(配图 ABAP_Annos4Views_002a.png 的中文标注):dataMaintenance = 限制 CDS 视图的数据预览; viewEnhancementCategory = 指定如何使用 CDS 扩展扩展视图实体。 本项目既有视图没写这两个,不加也能跑;加上是好习惯(防止别人无意扩展你的报表视图)。

    视图头注解及中文含义

    图 9:视图头常用注解及含义——前两行就是 @AbapCatalog.dataMaintenance(限制 ADT 数据预览里的维护操作)与 @AbapCatalog.viewEnhancementCategory(指定能否/如何被 CDS 扩展扩展)。来源:S4D430 / 04-.../02-Using_ABAP_Annotations_in_CDS_Views.md 配图 ABAP_Annos4Views_002a.png

2.2 元数据扩展 ZC_QUERY_SD018(DDLX)

右键 ZC_QUERY_SD018 → New → Metadata Extension,名称填 ZC_QUERY_SD018。 (前提:ZC_QUERY_SD018 必须已有 @Metadata.allowExtensions: true,否则这个菜单项不可用。)

ADT 新建 Metadata Extension

图 10:右键 CDS 视图 → New → Metadata Extension,模板选 Annotate View。截图为课程示例对象(对象名不同);本项目右键 ZC_QUERY_SD018,名称也填 ZC_QUERY_SD018。来源:S4D430 / 07-.../04-Creating_Metadata_Extensions.md 配图 05MetadataExtensionCreation_001.png

@Metadata.layer: #CUSTOMER
@EndUserText.label: '销售订单明细报表'

@UI: {
  headerInfo: {
    typeName:       '销售订单行',
    typeNamePlural: '销售订单行',
    title:          { type: #STANDARD, value: 'SalesDocument' },
    description:    { type: #STANDARD, value: 'CustomerName' }
  }
}
annotate view ZC_QUERY_SD018 with
{
  // ========== 筛选栏 ==========
  @UI.selectionField: [{ position: 10 }]
  @UI.lineItem:       [{ position: 10, label: '销售订单号' }]
  @UI.identification: [{ position: 10, label: '销售订单号' }]
  SalesDocument;

  @UI.selectionField: [{ position: 20 }]
  @UI.lineItem:       [{ position: 20, label: '订单行' }]
  @UI.identification: [{ position: 20, label: '订单行' }]
  SalesDocumentItem;

  @UI.selectionField: [{ position: 30 }]
  @UI.lineItem:       [{ position: 30, label: '订单类型' }]
  @UI.identification: [{ position: 30, label: '订单类型' }]
  SalesDocumentType;

  @UI.lineItem:       [{ position: 40, label: '订单类型描述' }]
  @UI.identification: [{ position: 40, label: '订单类型描述' }]
  SalesDocumentTypeName;

  @UI.selectionField: [{ position: 40 }]
  @UI.lineItem:       [{ position: 50, label: '订单凭证日期' }]
  @UI.identification: [{ position: 50, label: '订单凭证日期' }]
  SalesDocumentDate;

  @UI.selectionField: [{ position: 50 }]
  @UI.lineItem:       [{ position: 60, label: '客户参考' }]
  @UI.identification: [{ position: 60, label: '客户参考' }]
  PurchaseOrderByCustomer;

  @UI.selectionField: [{ position: 60 }]
  @UI.lineItem:       [{ position: 70, label: '售达方' }]
  @UI.identification: [{ position: 70, label: '售达方' }]
  SoldToParty;

  @UI.selectionField: [{ position: 70 }]
  @UI.lineItem:       [{ position: 80, label: '客户名称' }]
  @UI.identification: [{ position: 80, label: '客户名称' }]
  CustomerName;

  @UI.selectionField: [{ position: 80 }]
  @UI.lineItem:       [{ position: 90, label: '销售组织' }]
  @UI.identification: [{ position: 90, label: '销售组织' }]
  SalesOrganization;

  @UI.lineItem:       [{ position: 100, label: '产品组描述' }]
  @UI.identification: [{ position: 100, label: '产品组描述' }]
  ProductGroupName;

  // ========== 行项目 ==========
  @UI.selectionField: [{ position: 90 }]
  @UI.lineItem:       [{ position: 110, label: '产品' }]
  @UI.identification: [{ position: 110, label: '产品' }]
  Product;

  @UI.lineItem:       [{ position: 120, label: '项目描述' }]
  @UI.identification: [{ position: 120, label: '项目描述' }]
  SalesDocumentItemText;

  @UI.lineItem:       [{ position: 130, label: '物料长文本' }]
  @UI.identification: [{ position: 130, label: '物料长文本' }]
  ProductDescription;

  @UI.lineItem:       [{ position: 140, label: '客户品名' }]
  @UI.identification: [{ position: 140, label: '客户品名' }]
  CustomerProductName;

  @UI.lineItem:       [{ position: 150, label: 'SKU(客户)' }]
  @UI.identification: [{ position: 150, label: 'SKU(客户)' }]
  CustomerSKU;

  @UI.lineItem:       [{ position: 160, label: '订单数量' }]
  @UI.identification: [{ position: 160, label: '订单数量' }]
  OrderQuantity;

  @UI.selectionField: [{ position: 100 }]
  @UI.lineItem:       [{ position: 170, label: '工厂' }]
  @UI.identification: [{ position: 170, label: '工厂' }]
  Plant;

  @UI.lineItem:       [{ position: 180, label: '存储地点' }]
  @UI.identification: [{ position: 180, label: '存储地点' }]
  StorageLocation;

  @UI.lineItem:       [{ position: 185, label: '存储地点描述' }]
  @UI.identification: [{ position: 185, label: '存储地点描述' }]
  StorageLocationName;

  // ========== 金额 ==========
  @UI.lineItem:       [{ position: 190, label: '订单含税单价' }]
  @UI.identification: [{ position: 190, label: '订单含税单价' }]
  OrderPriceInclTaxPerUnit;

  @UI.lineItem:       [{ position: 200, label: '订单含税金额' }]
  @UI.identification: [{ position: 200, label: '订单含税金额' }]
  OrderAmountInclTax;

  @UI.lineItem:       [{ position: 210, label: '订单未税金额' }]
  @UI.identification: [{ position: 210, label: '订单未税金额' }]
  OrderAmountExclTax;

  @UI.lineItem:       [{ position: 220, label: '订单税额' }]
  @UI.identification: [{ position: 220, label: '订单税额' }]
  OrderTaxAmount;

  @UI.lineItem:       [{ position: 230, label: '交易币别' }]
  @UI.identification: [{ position: 230, label: '交易币别' }]
  TransactionCurrency;

  @UI.lineItem:       [{ position: 240, label: '汇率' }]
  @UI.identification: [{ position: 240, label: '汇率' }]
  PriceDetnExchangeRate;

  // ========== 状态 ==========
  // ⚠️ 拒绝原因:口径未定,下面按"候选 A:订单原因"出列。
  //    若定稿为"候选 B:行项目拒绝原因",把这一处换成 SalesDocumentRjcnReason 即可。
  @UI.selectionField: [{ position: 110 }]
  @UI.lineItem:       [{ position: 250, label: '拒绝原因' }]
  @UI.identification: [{ position: 250, label: '拒绝原因' }]
  SDDocumentReasonText;

  @UI.selectionField: [{ position: 120 }]
  @UI.lineItem:       [{ position: 260, label: '审批状态' }]
  @UI.identification: [{ position: 260, label: '审批状态' }]
  SalesDocApprovalStatusDesc;

  @UI.selectionField: [{ position: 130 }]
  @UI.lineItem:       [{ position: 270, label: '创建日期' }]
  @UI.identification: [{ position: 270, label: '创建日期' }]
  CreationDate;

  // ========== 交货与开票 ==========
  @UI.lineItem:       [{ position: 280, label: '交货数量' }]
  @UI.identification: [{ position: 280, label: '交货数量' }]
  DeliveredQuantity;

  @UI.lineItem:       [{ position: 290, label: '开票含税金额' }]
  @UI.identification: [{ position: 290, label: '开票含税金额' }]
  BilledAmountInclTax;

  @UI.lineItem:       [{ position: 300, label: '开票未税金额' }]
  @UI.identification: [{ position: 300, label: '开票未税金额' }]
  BilledAmountExclTax;

  @UI.lineItem:       [{ position: 310, label: '开票税额' }]
  @UI.identification: [{ position: 310, label: '开票税额' }]
  BilledTaxAmount;

  // ========== 技术字段:不进 UI ==========
  @UI.hidden: true
  DistributionChannel;

  @UI.hidden: true
  OrganizationDivision;

  @UI.hidden: true
  OrderQuantityUnit;

  @UI.hidden: true
  SalesOrganizationName;

  @UI.hidden: true
  SalesDocumentRjcnReason;

  @UI.hidden: true
  SDDocumentReason;

  @UI.hidden: true
  SalesDocApprovalStatus;
}

要点:

  • @Metadata.layer: #CUSTOMER —— 必填。优先级顺序(高 → 低,来自 S4D430 / 07-.../04-Creating_Metadata_Extensions.md 与配图 Metadata_Extensions_002.png):

    #CUSTOMER  →  #PARTNER  →  #INDUSTRY  →  #LOCALIZATION  →  #CORE
    (客户)      (非SAP)                    (本地化)        (SAP 最低)
    

    同一实体最多可建 5 个元数据扩展,分别占一层。 我们用 #CUSTOMER——理由有两个:① 我们是最终客户,占最高层才能覆盖一切; ② 项目线上既有的 zc_query_sd002.ddlx.asddlxs 第 1 行就是 @Metadata.layer: #CUSTOMER,保持一致。

    补充一条容易搞混的规则:SAP 官方建议做产品/行业解决方案的一方把 UI 元数据放在 #CORE 层, 「这为行业解决方案、合作伙伴和客户提供了根据自身需求调整(覆盖)UI 配置的优雅方式」。 我们不是产品方,是客户方,所以用 #CUSTOMER。

    元数据扩展的五个 layer

    图 11:@Metadata.layer 的五个层级与优先级——#CUSTOMER 最高、#CORE 最低;同一 CDS 实体最多 5 个元数据扩展,各占一层,高层覆盖低层。来源:S4D430 / 07-.../04-Creating_Metadata_Extensions.md 配图 Metadata_Extensions_002.png

  • annotate view ... with { ... } —— 用 ANNOTATE VIEW 而不是 ANNOTATE ENTITY:

    「还有一个"注释实体"模板……ANNOTATE ENTITY 可用于任何类型的 CDS 实体,但可用注释集较小。我们建议您在为 CDS 视图创建元数据扩展时使用 ANNOTATE VIEW。」

  • @UI.lineItem 里的 label 只在需要覆盖字段标签时才写。不写就用 ZC_QUERY_SD018 上的 @EndUserText.label(DDL 里已经通过注解传播继承下来)。 这里显式写出来是为了让表头与客户模板逐字对齐。

  • 元数据扩展的限制(必须知道):

    「无法在元数据扩展中定义新元素。您只能处理目标实体的现有元素并向其添加注释。」

  • @UI.hidden: true —— 权限字段(DistributionChannel、OrganizationDivision)必须在视图里存在(DCL 要用),但不能出现在表格里。

2.3 关于"订单含税单价"这个计算字段

模板第 19 列"订单含税单价"在系统里没有对应字段,是算出来的(含税金额 ÷ 数量)。 它的定义已经写在上面的 ZR_QUERY_SD018 元素列表里(模板 19 那一行),这里解释为什么必须那么写。

CDS 除法的硬限制: 「最重要的限制是仅允许在浮点表达式中使用除法运算符 ( / )。通过使用 CAST() 将类型转换为 FLTP,可以在浮点表达式中使用任何数值操作数。」 —— S4D430 / 06-.../01-Implementing_SQL_Expressions_in_CDS_Views.md

所以 Item.Subtotal1Amount / Item.OrderQuantity 直接写会语法错误,两侧都必须先 cast( ... as abap.fltp )。同时要防除零(when Item.OrderQuantity <> 0)。

另一个必知点:「cast 表达式的操作数不能只是文字」——可以使用字段、算术表达式、CASE 区分、SQL 函数等。 所以 cast( 100 as abap.fltp ) 这种写法是不允许的;但 cast( Item.OrderQuantity as abap.fltp ) 允许。

参考实证:zcl_query_sd002.clas.abap L327-329 是 ABAP 侧的同款计算 subtotal1amountunit = subtotal1amountunit / orderquantity2——ABAP 侧没有浮点限制,CDS 侧有。

更好的替代方案(建议评估):单价直接取定价条件里的净价,而不是从金额反算—— I_SalesDocumentItem 有 NetPriceAmount / NetPriceQuantity, 或走 I_SalesDocItemPricingElement(SD002 L1111-1118 用过,条件类型 'ZCIP')。 反算值在"含税金额包含运费/折扣"时会有尾差。

⚠️ 这是必须找业务确认的一项(附录 B V7 第 2 条)。含税单价的三种可能口径: ① 含税金额 ÷ 数量(本教程默认);② 定价条件的净价;③ 含税金额 ÷ 数量再按汇率折算本位币。 三者结果不同,选错了整个报表的单价列都要返工。

注意:OrderPriceInclTaxPerUnit 是金额语义(每单位含税金额),所以挂 @Semantics.amount.currencyCode: 'TransactionCurrency' 而不是 quantity 注解—— 这样 Fiori 表格里它能正确显示币别。但要注意:Fiori 表格对"带币别的金额列"默认会求和, 单价列求和没有业务意义。若不希望求和,在 DDLX 里对该列设 @UI.lineItem: [{ position: 190, type: #STANDARD }] 并评估是否改用 @UI.dataPoint 呈现。


Step 3 — 权限:CDS 访问控制(DCL)

3.1 为什么必须做

销售数据必须按销售范围隔离。本项目既有报表 ZZSD002_EXT 的权限对象就是 V_VBAK_VKO(销售组织 VKORG / 分销渠道 VTWEG / 产品组 SPART / 活动 ACTVT='03'),新报表必须一致。

CDS 的做法是 DCL(数据控制语言),而不是 ABAP 里的 AUTHORITY-CHECK:

「CDS 访问控制类型的资源库对象使用关键字 DEFINE ROLE 定义 CDS 角色。在角色中,关键字 GRANT SELECT ON 将 CDS 角色与 CDS 实体相关联,在关键字 WHERE 之后定义访问条件。每当 ABAP 代码访问 CDS 实体时,数据库接口都会根据这些访问条件过滤选择结果。」 —— S4D430 / 07-.../01-Preventing_Unauthorized_Access_to_Data.md

3.2 建 DCL

右键 ZC_QUERY_SD018 → New → Access Control,名称 ZC_QUERY_SD018(与实体同名,官方强建议)。

ADT 新建 Access Control

图 12:右键 CDS 视图 → New → Access Control(截图为课程示例对象;本项目右键 ZC_QUERY_SD018)。来源:S4D430 / 07-.../01-Preventing_Unauthorized_Access_to_Data.md 配图 Create_a_new_Access_Control_001.png

选择访问控制模板

图 13:新建 DCL 时选模板——Define Role with PFCG Aspect 对应本教程的 pfcg_auth 写法;另有简单条件、继承条件、通用 aspect 等模板。来源:同上 Create_Access_Control_003.png

@EndUserText.label: '销售订单明细报表-权限'
@MappingRole: true
define role ZC_QUERY_SD018
{
  grant select on ZC_QUERY_SD018
    where ( SalesOrganization )
        = aspect pfcg_auth ( V_VBAK_VKO,
                             VKORG,
                             ACTVT = '03' );
}

要点:

  • pfcg_auth 的语法结构(来自 S4D430 / 07-.../01-...md 的模板与配图 CDSAccessControlExample.png):

    where ( <视图元素列表> ) = aspect pfcg_auth ( <权限对象>, <权限字段...>, <过滤字段> = '<值>' );
    

    教程里 ( SalesOrganization ) 对应权限字段 VKORG,ACTVT = '03'(显示)。

    CDS 访问控制示例

    图 14:define role + grant select on <实体> + where (<元素>) = aspect pfcg_auth(<权限对象>, <字段...>, ACTVT = '03') 的结构——where 里的元素与 pfcg_auth 里的权限字段按位置一一对应。来源:S4D430 / 07-.../01-Preventing_Unauthorized_Access_to_Data.md 配图 CDSAccessControlExample.png

  • 要同时管控分销渠道和产品组,需要把三个元素和三个权限字段按位置一一对应写全。 官方模板(S4D430 / 07-.../01-...md)就是这个形式:

    where (entity_element_1, entity_element_2)
        = aspect pfcg_auth( <权限对象>,
                            authorization_field_1,
                            authorization_field_2,
                            filter_field_1 = 'filter_value_1' );
    

    套到我们的场景:

    where ( SalesOrganization, DistributionChannel, OrganizationDivision )
        = aspect pfcg_auth ( V_VBAK_VKO, VKORG, VTWEG, SPART, ACTVT = '03' );
    

    ⚠️ 位置对应的规则是"左边第 N 个元素 ↔ 右边第 N 个权限字段",数量必须一致、顺序必须对应。 这里左边 3 个元素 ↔ 右边 3 个权限字段(ACTVT = '03' 是过滤条件,不占位置)。 写错了不会报错,只会静默地按错的维度过滤——所以第 8 步的权限测试(A1~A4)必须真跑。 (项目既有报表是在 ABAP 类里手工做三字段 AUTHORITY-CHECK,纯 CDS 路线在项目内没有先例,这是本教程第一个要你在 D 系统验证的点。)

    参考实证(ABAP 侧三字段检查,zcl_query_sd002.clas.abap L1194-1201):

    AUTHORITY-CHECK OBJECT 'V_VBAK_VKO'
      ID 'VKORG' FIELD ls_data-salesorganization
      ID 'VTWEG' FIELD ls_data-distributionchannel
      ID 'SPART' FIELD ls_data-organizationdivision
      ID 'ACTVT' FIELD '03'.
    IF sy-subrc NE 0.
      CONTINUE.
    ENDIF.
    
  • ⚠️ 一个必须记住的坑:

    「仅当直接从 ABAP 代码访问 CDS 实体时,CDS 访问控制才有效。如果间接访问 CDS 实体(例如,通过其他 CDS 实体),则会将其忽略。」

    好消息:我们的 ZC_QUERY_SD018 是被 OData 服务直接访问的消费视图,DCL 会生效。 但要注意——ZR_QUERY_SD018 里的 I_Customer、I_Product 等标准视图自身的 DCL 不会传递到这里, 所以权限必须在 ZC_QUERY_SD018 这一层自己写全。

3.3 检查点 ✅

  • ADT 里对 ZC_QUERY_SD018 做 Data Preview(F8),结果应比不挂 DCL 时少(当前用户权限受限的话)。

  • 语法检查不应再有 #CHECK 相关的警告。


Step 4 — 发布 OData V4 服务

4.1 服务定义 ZUI_QUERY_SD018_O4

右键包 ZZSD → New → ABAP Repository Object → Core Data Services → Service Definition。

@EndUserText.label: '销售订单明细报表-服务定义'
define service ZUI_QUERY_SD018_O4 {
  expose ZC_QUERY_SD018 as SalesOrderItemDetail;
}

结构对齐项目既有服务(zui_query_sd002_o2.srvd.srvdsrv、zui_query_sd004_o4.srvd.srvdsrv 的写法一致)。

4.2 服务绑定 ZUI_QUERY_SD018_O4

右键刚建的服务定义 → New Service Binding,名称 ZUI_QUERY_SD018_O4。

配置项

取值

说明

Binding Type

OData V4

新报表统一用 V4(项目 SD004~SD016 已是 V4;只有早期 SD001/SD002 还是 V2)

Service Version

0001

Binding Type Version

V4

Binding Type (UI)

OData V4 - UI

⚠️ 关键:要选带 UI 的那个,否则 Fiori elements 的注解不生效

Contract

C1

内部使用系统契约(对齐 zui_query_sd002_o2.srvb.xml 的 <CONTRACT>C1</CONTRACT>)

保存 → 激活 → 点 Publish。

4.3 预览验证

OData URL 组成

图 15:OData URL 的三个组成部分——服务路径、实体集、查询选项。拼 $metadata 和调试时按这个结构拆。来源:UX406-.../ODataURLparts_Scr.png

绑定激活后,在 ADT 的服务绑定编辑器里点 Preview(或直接拼 URL):

https://<你的D租户域名>/sap/opu/odata4/sap/zui_query_sd018_o4/srvd/sap/zui_query_sd018_o4/0001/$metadata

自查三件事:

  1. $metadata 里能看到 SalesOrderItemDetail 实体集,且 31 个字段都在;

  2. 每个字段带 sap:label(中文列名)——说明 DDLX 注解生效了;

  3. 带 $top=5 取数,不报 DCL 权限错误。

💡 V2 与 V4 查注解的差别:V2 的注解在单独的注释文件里(.../$metadata 旁边的 .../Annotations), V4 的注解内联在 $metadata 的 <Annotations> 段里。别对着 V4 找注释文件。

4.4 ⚠️ 导出 Excel 的说明(重要,先跟客户对齐预期)

模板的工作表名叫 SAPUI5 导出,客户显然期望一个 Excel 导出。

SAP Fiori elements List Report 自带「导出到电子表格」(表格工具栏 → 设置 → 导出 / Export to Spreadsheet), 无需额外开发。但要注意:

事项

事实

支持情况

Fiori elements 的表格导出功能是标准内置的(SAPUI5 文档 "Using the Export Button")

导出的列

跟随当前表格配置——用户可以在"设置"里改列,导出也会跟着变

导出的表头

单行表头,即模板 A1:AE1 那 31 个列名

模板的两行表头

模板第 2 行("销售订单号"/"客户PO号"/"交货总数")是客户手工加的说明行。标准导出不会产生这一行

工作表名

不保证等于"SAPUI5 导出"

结论与建议:

  • 优先方案:向客户说明标准导出的形态,接受单行表头。绝大多数客户在这一步就能接受。

  • 如果客户坚持要完全复刻模板的两行表头 + 指定工作表名:那是自定义导出,需要 ① 用 Fiori elements 的 controller extension 覆盖导出动作,或 ② 单独做一个导出按钮,走 export to Excel 的自定义实现(后端 API / 前端 sap.ui.export.Spreadsheet)。 工作量约 3~5 人天,属于新增开发清单,需要单独报批。

这一条务必在开发前写进需求确认,不要等验收时才发现。


Step 5 — 用 BAS 生成 Fiori elements 应用

📌 本节操作步骤与截图来自本项目 Day4 官方练习脚本(docs/12、SAP公有云开发培训/Day4_S4HC_Embedded Analytics_练习脚本.docx)。 脚本原来连的是培训用的 OData V2 服务;你只需把服务换成自己的 ZUI_QUERY_SD018_O4。

5.1 配置 BAS 到 S/4HANA Cloud 的 Destination

参考 SAP 官方教程: https://developers.sap.com/tutorials/abap-custom-ui-bas-connect-s4hc.html

注意:要连 Dev/Starter 租户(my201458),不是生产。

5.2 新建 BAS 开发空间

参考:https://developers.sap.com/tutorials/appstudio-devspace-fiori-create.html 模板选 SAP Fiori。

5.3 用向导生成 List Report 应用

参考:https://developers.sap.com/tutorials/abap-custom-ui-bas-develop-s4hc.html

BAS 选择数据源与服务

图 16:BAS「Data Source and Service Selection」——Data source 选 Connect to a System,System 选 DEV (S4HC),Service 选你的服务。原脚本选的是 ZSB_MATERIAL_AGING (1) - OData V2;本项目要选 ZUI_QUERY_SD018_O4(OData V4)

向导中的取值:

步骤

取值

Data source

Connect to a System

System

DEV (S4HC)

Service

ZUI_QUERY_SD018_O4

Main entity

SalesOrderItemDetail

Project attributes — Name

salesorderdetail

Project attributes — Application title

销售订单明细报表

勾选

Add deployment configuration ✅ Add FLP configuration ✅

FLP 配置:

项

取值

Semantic Object

SalesOrderItemDetail

Action

display

Title

销售订单明细报表

Subtitle

Display

关于页面模板:向导会基于实体的注解推荐 floorplan。因为我们做的是只读明细列表, 保证选到 List Report 即可(参考图 1)。不需要 Object Page——本报表没有明细钻取页面。

5.4 保存并本地预览

生成后直接 npm start / 用 BAS 的预览,确认:

  • 31 列都在,顺序与模板一致;

  • 筛选栏有 销售订单号、订单类型、订单日期、客户、产品、工厂、审批状态、创建日期;

  • 金额列有币别、数量列有单位;

  • 全局搜索框可用。

5.5 可选增强(按需,非必须)

需求

做法

表格初始不自动取数

页面编辑器 → 表 → 初始加载 → 选「已启用」(延迟加载)

多个视图切换(如"全部/未交货/未开票")

在 DDLX 里加 @UI.presentationVariant + selectionVariant,或在 manifest.json 配 table mode

关键性着色(如未交货标红)

在 ZR_ 视图加 Criticality 计算字段(1=红 2=黄 3=绿 0=中性),DDLX 里 @UI.lineItem: [{ criticality: 'Criticality' }]。参考 UX406/03/01 的 OverallStatusCriticality 写法

列的显隐/顺序微调

直接在 DDLX 里改 position,不要在前端硬编码

⚠️ 关于多视图与导出:本地 UX406 官方课程未覆盖 single/multiple table mode 与导出配置的具体写法。 需要这两项时,查 SAP Help「Adapting the UI: List Report and Object Page」而不要凭记忆写。


Step 6 — 部署回 SAPUI5 ABAP 仓库

⚠️ 关键差异:SAP 官方 UX406 课程教的是部署到 BTP Cloud Foundry + Work Zone; 本项目实际用的是部署回 S/4HANA 的 SAPUI5 ABAP 仓库(证据:ZZSD002_EXT 的 UI_APP_ID = ZZQUERYSD002_UI5R, 而 ZZQUERYSD002_UI5R 正是一个 UI5 ABAP 仓库对象)。请按下面这条路径走。

BAS 部署配置

图 17:BAS「Deployment Configuration」——Target 选 ABAP,Destination 指向 DEV (S4HC),填写 SAPUI5 ABAP Repository / Package / Transport Request。来源:Day4 练习脚本第 10 张截图

部署配置取值:

项

取值

Please choose the target

ABAP

Destination

DEV (S4HC) - https://my201458.lab.s4hana.cloud.sap(选你自己的 D 租户)

SAPUI5 ABAP Repository

ZZQUERYSD018_UI5R

Deployment Description

销售订单明细报表

How do you want to enter the package?

Choose from existing

Package

ZZSD

How do you want to enter the transport request?

Choose from existing(或新建)

Transport Request

你为本次开发创建的请求号

执行部署:在 BAS 里右键项目 → Deploy(或在 Application Info 里点 Deploy)。

部署后检查(在 ADT 里):

  1. 包 ZZSD 下出现 BSP Application / UI5 Repository 对象 ZZQUERYSD018_UI5R;

  2. 展开它能看到 Fiori User Interface → Launchpad App Descriptor Items,里面有向导生成的 Semantic Object - Action 条目;

  3. 记下这个 Launchpad App Descriptor Item 的 ID——下一步 IAM 应用要填。


Step 7 — IAM 应用 / 业务目录 / 业务角色

本节完全对齐 ZZSD002_EXT(zzsd002_ext.sia6.xml)在线上项目的实际配置。

7.1 新建 IAM 应用

在 ADT 中:右键包 ZZSD → New → ABAP Repository Object → Identity and Access Management → IAM App。

新建 IAM 外部应用

图 18:ADT「New IAM App」对话框——Application Type 必须是 External App,Name 如 ZMATERIALAGE_UI。来源:Day4 练习脚本第 14 张截图

项

取值

Name

ZZSD018_EXT

Description

销售订单明细报表

Application Type

External App ⚠️ 不要选成其他类型

Application ID Suffix

_EXT(自动)

然后在 IAM App 里挂两样东西:

  1. UI 应用:UI_APP_ID = ZZQUERYSD018_UI5R(Step 6 部署的 UI5 仓库对象)

  2. OData 服务:

    项

    取值

    Relative Name

    ZUI_QUERY_SD018_O4  0001

    Relative Type

    IWSV

    Type Text

    OData V4

    UIAD Source

    ZZQUERYSD018_UI5R

权限对象(点 IAM App 的 Authorizations 页签 → Add):

权限对象

字段

值

V_VBAK_VKO

VKORG / VTWEG / SPART / ACTVT

留空 = 不受限(STATUS = U)

对照线上实物:zzsd002_ext.sia6.xml 里 <AUTH_OBJECT>V_VBAK_VKO</AUTH_OBJECT> <STATUS>U</STATUS>, 三个字段 VKORG/VTWEG/SPART 的 <STATUS>U</STATUS> 即"不受限"。 这里留空 = 由业务角色去分配具体值,是正确做法。

7.2 新建业务目录并挂载

项

取值

Name

ZBC_SD_0018

Description

销售订单明细报表

内容

把 IAM App ZZSD018_EXT 加进去

Package

ZZSD

保存后 Publish 业务目录(本地发布)。

对齐线上:zbc_sd_* / ZIAM_* + SIA1/SIA6/SIA7 三层结构。

7.3 维护业务角色并分配给用户

Maintain Business Roles

图 19:Fiori 应用「Maintain Business Roles」列表。来源:Day4 练习脚本第 18 张截图

Part 2 —— 到定制租户(Customizing Tenant)操作:

  1. 打开 Fiori 应用 「维护业务角色」(Maintain Business Roles)

  2. 点 New 新建角色:

    项

    取值

    Role ID

    ZBR_SD_ORDER_DETAIL

    Description

    销售订单明细报表-查看

  3. 在该角色的 Business Catalogs 页签里,加入 ZBC_SD_0018

  4. 在 General Role Details 里把所有访问级别改成 Unrestricted(不受限) (本项目既有报表 ZZSD002_EXT 的权限就是 STATUS = U 不受限)

  5. 在 Assigned Business Users 里加入需要看这张报表的业务用户

  6. Save

  7. 刷新浏览器,搜索 销售订单明细报表,应能打开

7.4 检查点 ✅

检查

期望

业务角色保存后,用户的 Fiori 启动板出现该磁贴

✅

用不同销售组织权限的两个用户登录

看到的数据条数不同(DCL 生效)

点「导出 → 电子表格」

能下载 xlsx,31 列在


Step 8 — 测试与验收清单

8.1 数据正确性(最重要)

#

用例

方法

通过标准

D1

行数不放大

报表行数 vs I_SalesDocumentItem 中非 AG 行数

完全相等

D2

单交货单订单

挑一张只有 1 个交货单、1 张发票的订单

交货数量 = 交货单数量;开票金额 = 发票金额

D3

多交货单订单(分批交货)

挑一张有 3 个交货单的订单行

交货数量 = 3 张交货单之和

D4

退货订单(IsReturnsItem = 'X')

挑一张退货单

订单金额、交货数量均为负数

D5

红冲发票

挑一张已冲销的发票

不计入开票金额

D6

未交货订单

挑一张还没交货的订单

交货数量显示 0(不是空白)

D7

未开票订单

同上

开票金额显示 0

D8

贷项凭证请求类开票(category K/L)

挑一张 CR 类型凭证的开票

金额出现在对应的订单行上

D9

交货类开票(category J/T)

常规 TOB 出货开票

金额出现在对应的订单行上

D10

报价单不出现

搜一张 AG 类型凭证

报表里查不到

D11

审批状态覆盖

找一张 YY1_ZREWORK_SDH 有值的订单

显示自定义值,不是标准状态

D12

金税差异(若涉及)

对比 ZZC_QUERY_FI019(金税发票本位币含税)

口径与财务确认一致

D8/D9 是最容易漏的:只处理 K/L 或只处理 J/T,都会漏掉一半开票金额。 这两条务必用真实单据各跑一遍。

8.2 权限

#

用例

通过标准

A1

全权限用户

看到全部数据

A2

只授权销售组织 1000 的用户

只看到 1000 的数据

A3

只授权销售组织 1010 的用户

只看到 1010 的数据

A4

无任何销售权限的用户

看不到数据(不是报错)

8.3 性能

#

用例

通过标准

P1

不带筛选条件打开

首屏 < 3 秒(框架默认只取前 20/100 行)

P2

按销售订单号筛选

< 2 秒

P3

按日期区间(1 个月)筛选

< 5 秒

P4

导出 1 万行

< 60 秒

若 P1 明显慢:检查是不是忘了给 ZC_QUERY_SD018 加 @ObjectModel.usageType.sizeCategory: #L, 以及 ZR_QUERY_SD018 是不是真的走了聚合视图(而不是被优化器展开成全量 JOIN)。

8.4 Clean Core 合规检查(ATC)

发布前必须跑一遍 ATC。本项目是 ABAP Cloud 软件组件,映射到 Clean Core 级别 A:

「在 ABAP 云类型的软件组件中创建的所有对象都必须遵循 ABAP 云开发模型。…… 基于 ABAP Cloud 的软件组件有效映射到 clean core 级别 "A"」 —— S4D426 / 05-.../03-Setting_Up_For_Clean_Core_Development.md

ATC 变式

用途

通过标准

ABAP_CLOUD_DEVELOPMENT_DEFAULT

确认代码符合云要求,强制执行基本 ABAP 云规则

0 个错误、0 个警告

ABAP_CLOUD_READINESS

检查是否只用了 ABAP Cloud 可用的对象类型 / 语言语句 / 已发布 SAP API

0 个错误

ATC 结果与级别的对应关系(官方原话,可直接当 gate 判据):

「已发布 API:级别 A:在 ATC 中没有结果。」 「经典 API:级别 B:优先级 3(信息消息)。」 「内部对象:级别 C:优先级 2(警告消息)。」 「不建议:级别 D:优先级 1(错误消息)。」

操作:ADT 里右键包 ZZSD → Run As → ABAP Test Cockpit with... → 选变式 → 执行。 出现任何优先级 1/2 的消息都必须修掉,否则这个报表会把包从级别 A 拖下来 (级别判定规则:「扩展根据其中使用的最低等级技术进行评估」)。

8.5 交付物清单

  • CDS:ZR_QUERY_SD018_DN / _BILL / _BILLA / ZR_QUERY_SD018 / ZC_QUERY_SD018

  • DDLX:ZC_QUERY_SD018

  • DCL:ZC_QUERY_SD018

  • SRVD + SRVB:ZUI_QUERY_SD018_O4

  • UI5 仓库对象:ZZQUERYSD018_UI5R

  • IAM App:ZZSD018_EXT

  • 业务目录:ZBC_SD_0018

  • 业务角色:ZBR_SD_ORDER_DETAIL

  • 传输请求:全部对象已记录,gCTS SAP-ZZSD 仓库已推送

  • 测试记录:§8.1~8.3 全部用例签字

  • 操作手册:按本项目 NSBR-…_最终用户操作手册_…docx 的格式补一份


附录 A — 与项目现行范式(custom entity)的对照

如果你判断必须走方案 B(或只是想读懂同事写的代码),这里是项目现行范式的骨架。 证据来自线上源码 sap-zzsd-master/src/。

A.1 对象链

ADT 新建类并加 IF_RAP_QUERY_PROVIDER

图 20:ADT「New ABAP Class」对话框——Interfaces 必须填 IF_RAP_QUERY_PROVIDER,这是方案 B 的入口。来源:Day4 练习脚本第 5 张截图

ZR_ / ZI_ 接口视图
      ↓
ZC_QUERY_SDxxx ── custom entity(不是 view entity!)
      ↓            @ObjectModel.query.implementedBy: 'ABAP:ZCL_QUERY_SDxxx'
ZCL_QUERY_SDxxx ── ABAP 类,implements if_rap_query_provider
      ↓
ZUI_QUERY_SDxxx_O4/O2 ── Service Definition + Binding
      ↓
Fiori elements App(部署为 ZZQUERYSDxxx_UI5R)

A.2 实体定义(逐字,zc_query_sd002.ddls.asddls 头部)

@EndUserText.label: '销售发货明细报表'
@ObjectModel.query.implementedBy: 'ABAP:ZCL_QUERY_SD002'
@Metadata.allowExtensions: true
@ObjectModel.semanticKey: ['SalesDocument','DeliveryDocument','BillingDocument'] //设置列高亮
define custom entity ZC_QUERY_SD002
{
  key SalesDocument                  : vbeln_va;
  key SalesDocumentItem              : posnr_va;
  key DeliveryDocument               : vbeln_vl;
  key DeliveryDocumentItem           : posnr_vl;
  key BillingDocument                : vbeln;
  key BillingDocumentItem            : posnr;
  ...
}

A.3 实现类骨架(逐字,zcl_query_sd002.clas.abap)

CLASS zcl_query_sd002 DEFINITION PUBLIC FINAL CREATE PUBLIC.
  PUBLIC SECTION.
    INTERFACES if_rap_query_provider .
    TYPES: ty_result  TYPE zc_query_sd002,
           tty_result TYPE TABLE OF ty_result WITH EMPTY KEY.
    METHODS get_result
      IMPORTING it_ranges        TYPE if_rap_query_filter=>tt_name_range_pairs
      RETURNING VALUE(rt_result) TYPE tty_result.
    METHODS get_data
      IMPORTING io_request  TYPE REF TO if_rap_query_request
                io_response TYPE REF TO if_rap_query_response
      RAISING   cx_rap_query_prov_not_impl cx_rap_query_provider.
ENDCLASS.

CLASS zcl_query_sd002 IMPLEMENTATION.
  METHOD if_rap_query_provider~select.
    TRY.
        CASE io_request->get_entity_id( ).
          WHEN 'ZC_QUERY_SD002'.
            get_data( io_request  = io_request
                      io_response = io_response ).
        ENDCASE.
      CATCH cx_rap_query_provider INTO DATA(lx_query).
        RETURN.
      CATCH cx_sy_no_handler INTO DATA(lx_synohandler).
        RETURN.
      CATCH cx_sy_open_sql_db.
        RETURN.
    ENDTRY.
  ENDMETHOD.

  METHOD get_data.
    TRY.
        DATA(lt_filters) = io_request->get_filter(  )->get_as_ranges(  ).
        " 1) 逐字段解析 range ...
        " 2) 取分页
        DATA(lo_paging)     = io_request->get_paging( ).
        DATA(lv_offset)     = lo_paging->get_offset( ).
        DATA(lv_page_size)  = lo_paging->get_page_size( ).
        " 3) 取数
        lt_result = get_result( lt_filters[] ).
        " 4) 未识别过滤条件 → 通用内存过滤
        IF lv_other_filter IS NOT INITIAL.
          zzcl_query_utils=>filtering( EXPORTING io_filter = io_request->get_filter(  )
                                       CHANGING  ct_data   = lt_result ).
        ENDIF.
        IF io_request->is_total_numb_of_rec_requested(  ).
          io_response->set_total_number_of_records( lines( lt_result ) ).
        ENDIF.
        " 5) 排序
        zzcl_query_utils=>orderby( EXPORTING it_order = io_request->get_sort_elements( )
                                   CHANGING  ct_data  = lt_result ).
        " 6) 分页
        zzcl_query_utils=>paging( EXPORTING io_paging = io_request->get_paging(  )
                                  CHANGING  ct_data   = lt_result ).
        io_response->set_data( lt_result ).
      CATCH cx_rap_query_filter_no_range.
    ENDTRY.
  ENDMETHOD.
ENDCLASS.

A.4 三个通用工具方法(ZZCL_QUERY_UTILS)

项目所有查询类都调这三个,签名从调用点反推:

zzcl_query_utils=>filtering( EXPORTING io_filter = io_request->get_filter(  )
                             CHANGING  ct_data   = lt_result ).

zzcl_query_utils=>orderby(   EXPORTING it_order  = io_request->get_sort_elements( )
                             CHANGING  ct_data   = lt_result ).

zzcl_query_utils=>paging(    EXPORTING io_paging = io_request->get_paging(  )
                             CHANGING  ct_data   = lt_result ).

⚠️ ZZCL_QUERY_UTILS 的源码不在本地四个导出包里——它属于一个未被导出的公共基础包 (同包还缺 ZZT_REST_SYSID、ZZT_REST_APPEND、ZTJOB_LOG、ZTMM002~005)。 要改它或要读它的实现,得先找顾问要这个包的完整导出。 参见 docs/SAP公有云开发现状认知.md §7.2。

A.5 两种范式的取舍速查

你的情况

选

纯读、过滤/排序都能下推、数据量大

方案 A(本教程)

需要过滤聚合值、需要调接口、需要循环

方案 B

团队只会抄 ZCL_QUERY_SDxxx

方案 B(但要接受性能与代码量代价)

想给项目留一个可复制的"纯 CDS 报表"样板

方案 A


附录 B — 待确认事项与验证脚本

下面每一项都必须在 ADT 里实测,不要凭记忆填。所有脚本都用 ADT 的 Data Preview(在 CDS 视图上按 F8)或 SQL Console 执行。

V1. I_BillingDocumentItem 实际用到哪些 ReferenceSDDocumentCategory

为什么要查:项目现有代码只处理了 K/L(订单类)和 J/T(交货类)。 但诺思贝瑞的业务蓝图里还有"无发货单销售"和"预开票"(按销售订单直接开票), 这类开票的 ReferenceSDDocumentCategory 可能是 C(订单)——如果属实,现有代码是有漏的,新报表必须补上。

SELECT ReferenceSDDocumentCategory,
       COUNT(*) AS Cnt
  FROM I_BillingDocumentItem
 GROUP BY ReferenceSDDocumentCategory
 ORDER BY Cnt DESC

判读:如果结果里出现 C,把 Step 1.2 第一个 union 分支的 where 改成 in ( 'C', 'K', 'L' )。

V2. I_DeliveryDocument 的取消标志字段名

SELECT DeliveryDocument, OverallGoodsMovementStatus
  FROM I_DeliveryDocument
 WHERE DeliveryDocument = '<一张已取消的交货单>'

用 ADT 的字段补全看该视图到底有没有 DeliveryDocumentIsCancelled 之类字段,别猜字段名。

V3. 「客户品名」自定义字段的确切业务上下文

YY1_ZREWORK_SDH 已查清(返工标记,见 §1.4),无需再验。YY1_SKU_PRD 已改判为标准字段 MaterialByCustomer(见 §1.7),留到 V9 一起比对。本项只剩"客户品名"一个字段要定。

打开 Fiori 应用 「自定义字段」(Custom Fields),搜索并逐个记录:

候选

要记录的

YY1_ZKHPM_PRD

业务上下文(是不是 PRODUCT)、字段标签是不是"客户品名"

YY1_CPDM

同上

YY1_SHM_PRD

同上

判读:

  • 上下文 = 产品 → 从 I_Product 取(教程当前写法,Product.YY1_ZKHPM_PRD),不用改;

  • 上下文 = 销售订单行 → 改成 Item.YY1_xxx_SDI,改 Step 1.4 主视图里的一行即可。

V3b. 客户品名到底在不在 SAP 里

先问一句再动手:模板的"客户品名"会不会其实来自外围系统(OA / 旺店通 / 领星), 只是没回写到 SAP?如果是,这一列就必须靠接口补字段,属于新增开发,不是报表范围。 上线支持清单第 195 条「销售发货明细报表添加 创建人 和客户物料编码(SKU) 字段」说明客户确实会追加字段需求—— 这类追加要走需求变更,别默默做。

V4. 物料长文本的取值视图

项目从没用过这个字段,I_ProductDescription 是候选。验证:

SELECT Product, Language, ProductDescription
  FROM I_ProductDescription
 WHERE Product = '<一个真实物料号>'
   AND Language = '1'      -- 中文语言码,用 SE16N/ADT 确认后再填

若该视图不存在或已发布状态为否,改用 I_Product.ProductDescription(短文本)并跟客户确认长文本口径。

V5. 报价单类型码确认

教程假设报价单类型 = AG(依据 zcl_query_sd002.clas.abap L316/L1003 的 salesdocumenttype = 'AG')。 用 V1 的同类方法统计 I_SalesDocument 里各 SalesDocumentType 的单据量,确认还有没有其它要排除的类型。

V6. DCL 多字段 pfcg_auth 语法

先按 Step 3.2 的单字段版本编译通过,再试三字段版本:

where ( SalesOrganization, DistributionChannel, OrganizationDivision )
    = aspect pfcg_auth ( V_VBAK_VKO, VKORG, VTWEG, SPART, ACTVT = '03' );

不通过就保持单字段,另两个维度靠业务角色控制。

V7. 出口条件与定稿口径(需业务确认,非技术)

#

问题

找谁

1

报表是"一行 = 一个订单行"(本教程)还是"一行 = 订单行 × 交货行 × 发票行"?

李婕 / 陈锦财

2

"订单含税单价"取反算值还是取定价条件净价?

销售 + 财务

3

导出必须复刻模板的两行表头吗?接受标准单行表头吗?

李婕

4

是否要包含报价单(AG)?

销售

5

是否只统计已审批的订单?未审批的要不要出现在报表里?

销售

6

数据保留范围(近 12 个月 / 全部)?影响性能方案

销售 + IT

7

「拒绝原因」要的是哪个:订单原因(抬头、有文本)还是行项目拒绝原因(只有代码)?

李婕

8

「SKU(客户)」以哪个为准:订单行上的客户物料号,还是物料主数据上的自定义 SKU?

销售 + 主数据

V8. 「拒绝原因」的口径(必答,团队最容易做错的一列)

先看事实(复核线上代码得出,详见 §1.6):

-- 事实 1:OA 审批回传结构里没有拒绝原因字段
--   ZZS_SDI010_IN 全部字段 = WORKFLOWINTERNALID / COMPLETIONDATE / COMPLETIONTIME
--                            / SALESDOCAPPROVALSTATUS / SALESORDER
-- 事实 2:项目把 VBAP 的拒绝原因挪用成了"删除标记"
--   ZZCL_API_SD001 写 salesdocumentrjcnreason = '01' 表示删除
-- 事实 3:全项目无任何拒绝原因文本视图

然后做技术验证——在 ADT 里查这两个字段的真实取值分布:

-- 候选 A:订单原因(抬头)
SELECT SalesDocument, SDDocumentReason, COUNT(*) AS Cnt
  FROM I_SalesDocument
 GROUP BY SalesDocument, SDDocumentReason
 ORDER BY Cnt DESC

-- 候选 B:行项目拒绝原因
SELECT SalesDocument, SalesDocumentItem, SalesDocumentRjcnReason
  FROM I_SalesDocumentItem
 WHERE SalesDocumentRjcnReason <> ''

判读:

  • 候选 B 查出来全是 '01'(或极少数固定值)→ 它确实只是内部删除标记,不能用, 模板要的必然是候选 A(订单原因)。

  • 候选 B 能查出有业务含义的多种值 → 说明它同时承担了业务语义,这时要问清楚客户看的是哪一个, 并且还要在 ADT 已发布对象视图里找一个拒绝原因的文本视图(项目里没有现成的)。

别忘了:定稿后要在 ZC_QUERY_SD018 里把不用的那个字段删掉,同时删掉 DDLX 里对应的 @UI.hidden 条目—— 留着不影响运行,但会让后来人搞不清哪列才是真的。

V9. 「SKU(客户)」两套字段的值比对

标准字段与自定义字段可能都有值但口径不同。用 ADT Data Preview 跑一次比对:

SELECT Item.SalesDocument,
       Item.SalesDocumentItem,
       Item.MaterialByCustomer  AS StdCustomerMaterial,   -- 标准:订单行上的客户物料号
       Product.YY1_SKU_PRD      AS CustomSku              -- 自定义:物料主数据上的 SKU
  FROM I_SalesDocumentItem AS Item
  INNER JOIN I_Product AS Product
    ON Product.Product = Item.Product
 WHERE Item.SalesDocument = '<一张真实订单号>'

判读:

  • 两者值相同 → 随便用哪个(建议用标准字段 MaterialByCustomer,少一个扩展依赖);

  • 两者值不同 → 必须问业务:客户在报表上看到的"SKU(客户)"到底抄的是哪一个。 这类"两个字段都叫客户料号"的情况,做错了客户一眼就能看出来。

  • YY1_SKU_PRD 全空、MaterialByCustomer 有值 → 用标准字段,收工。

  • 反过来 → 用自定义字段,把教程 Step 1.4 那一行换成注释里的备选写法。


附录 C — 本目录参考资料索引

C.1 本教程直接依赖的材料

材料

路径

用途

报表模板(客户给的规格样张)

tmp_ql/销售订单明细报表模板.xlsx(原件在附件目录)

31 列清单

Day4 Embedded Analytics 练习脚本(含 24 张截图)

docs/12、SAP公有云开发培训/Day4_S4HC_Embedded Analytics_练习脚本.docx

Step 5/6/7 全流程

Day4 课件

docs/12、SAP公有云开发培训/Day4_S4HC_Embedded Analytics.pptx

报表概念

Day2 RAP 练习脚本

docs/12、SAP公有云开发培训/Day2_S4HC_Developer Extensibility_RAP_练习脚本.docx

RAP 基础(走方案 B 时看)

UX406 课程(中译)

docs/SAP官方开发培训课程/zh/03-SAPUI5与Fiori开发/UX406-入门_基于_OData_V4_RAP_服务创建_SAP_Fiori_elements_应用/

CDS 注解、List Report、部署

S4D430 课程(中译)

docs/SAP官方开发培训课程/zh/01-核心ABAP基础/S4D430-使用_ABAP_数据字典与_ABAP_Core_Data_Services_构建数据模型/

CDS 语法、关联、聚合、DCL、元数据扩展

S4D426 课程(中译)

docs/SAP官方开发培训课程/zh/01-核心ABAP基础/S4D426-实践_SAP_S_4HANA_Cloud_的洁净核心扩展/

ABAP Cloud 规则、Clean Core、已发布对象

全部课程 PDF(可离线打印)

docs/SAP官方开发培训课程/pdf/

同上

本教程配图

docs/images/

见下

C.2 项目代码与认知文档

材料

路径

用途

线上源码(SD 包,1028 个对象)

docs/顾问开发的代码--现有线上代码/sap-zzsd-master/src/

范式与字段实证的唯一权威

交货明细报表(最接近的范本)

…/zc_query_sd002.ddls.asddls、…/zcl_query_sd002.clas.abap、…/zc_query_sd002.ddlx.asddlxs

字段来源、聚合、审批状态、开票双路径

服务定义/绑定范本

…/zui_query_sd004_o4.srvd.srvdsrv、…/zui_query_sd004_o4.srvb.xml

OData V4 + C1 契约

IAM/权限范本

…/zzsd002_ext.sia6.xml

External App + V_VBAK_VKO

OA 审批写入逻辑

…/zzcl_api_sd009.clas.abap

salesdocapprovalstatus 1/2/3 → release/rejectApprovalRequest;YY1_ZREWORK_SDH='D' 返工标记

审批回传接口结构

…/zzs_sdi010_in.tabl.xml

证明回传里没有拒绝原因字段

审批请求接口结构

…/zzs_sdi009_req.tabl.xml、…/zzs_sdi009_item_in.tabl.xml

携带 SDDOCUMENTREASON 与 MATERIALBYCUSTOMER

拒绝原因字段的真实用途

…/zzcl_api_sd001.clas.abap L284/L323/L483…

证明 SalesDocumentRjcnReason 被用作删除标记 '01'

MaterialByCustomer 用法

…/zc_query_sd001_i.ddls.asddls、…/zzcl_job_sd004.clas.abap

证明它是项目在用的标准客户料号字段

代码索引

docs/ZZSD项目代码记录.md

命名规范、对象速查

开发现状认知报告

docs/SAP公有云开发现状认知.md

环境、六大开发模式、与官方教程的差异、已知缺陷

环境记忆

C:\Users\Luke\.claude\projects\...\memory\*.md

连接纪律(连系统前必须先问)

C.3 本教程配图清单

文件

内容

原始出处

D4-01-ADT新建DataDefinition.png

ADT 新建 Data Definition 对话框

Day4 练习脚本 图4

D4-02-ADT新建类加IF_RAP_QUERY_PROVIDER.png

ADT 新建 ABAP 类并加接口

Day4 练习脚本 图5

D4-03-BAS选择数据源与服务.png

BAS 数据源与服务选择

Day4 练习脚本 图7

D4-04-BAS部署配置到ABAP仓库.png

BAS 部署配置(目标 ABAP 仓库)

Day4 练习脚本 图10

D4-05-新建IAMApp外部应用.png

ADT 新建 IAM App

Day4 练习脚本 图14

D4-06-MaintainBusinessRoles.png

Fiori 维护业务角色

Day4 练习脚本 图18

C-01-ListReport页面模板.png

List Report 页面模板

UX406 课程 assets

C-02-FioriElements体系结构.png

Fiori elements 体系结构

UX406 课程 assets

C-03-ODataURL组成.png

OData URL 三部分

UX406 课程 assets

C-04-扩展模型.png

S/4HANA Cloud 扩展模型

S4D426 课程 assets

C-05-ABAP公有云API.png

ABAP 公有云 API 分类

S4D426 课程 assets

S4-01-会话变量对照表.png

六个会话变量 ↔ ABAP 系统字段对照

S4D430 06-02 配图 Session_Variables_001.png

S4-02-输入参数缺省值注解.png

输入参数缺省值注解 ↔ ABAP 系统字段

S4D430 06-03 配图 Default_Value_for_Parameters_in_Open_SQL_002.png

S4-03-访问控制注解取值.png

@AccessControl.authorizationCheck 五个取值

S4D430 07-01 配图 05AnnotationAccessControl_001.png

S4-04-视图头注解含义.png

视图头注解(dataMaintenance / viewEnhancementCategory 等)

S4D430 04-02 配图 ABAP_Annos4Views_002a.png

S4-05-新建元数据扩展.png

ADT 右键 → New → Metadata Extension,模板 Annotate View

S4D430 07-04 配图 05MetadataExtensionCreation_001.png

S4-06-元数据扩展层级.png

@Metadata.layer 五个层级与优先级

S4D430 07-04 配图 Metadata_Extensions_002.png

S4-07-新建访问控制.png

ADT 右键 → New → Access Control

S4D430 07-01 配图 Create_a_new_Access_Control_001.png

S4-08-访问控制模板.png

New Access Control 模板选择(PFCG Aspect 等)

S4D430 07-01 配图 Create_Access_Control_003.png

S4-09-访问控制示例.png

DCL 结构:define role + grant select + pfcg_auth

S4D430 07-01 配图 CDSAccessControlExample.png

图片均从项目内原始材料提取,未从互联网下载。Day4 截图由 Day4_..._练习脚本.docx 内嵌媒体解包得到; S4-* 配图取自 docs/SAP官方开发培训课程/assets/S4D430-.../(课程原图,未改图)。

C.4 使用这套资料时的三个已知陷阱

  1. 中译课件会篡改枚举值。例如 @AccessControl.authorizationCheck 的 #CHECK 被译成 #检查、 #MANDATORY 被译成 #必选;@Metadata.layer 的 #INDUSTRY 被译成 #行业; @Environment.systemField 的 #CLIENT 被译成 #客户端#。 凡是被译成中文的枚举值,一律不能直接抄进代码,要回 SAP 官方 ABAP 关键字文档核对英文原值。

  2. 课件正文只是讲义,不是手册。DDL/DCL 的完整可运行代码大量藏在 assets/ 的截图里, 正文 md 的代码块多是练习中间态(用 Z##_ 占位、分步增量给出),单块不能直接编译。

  3. 本套课件不覆盖:HAVING 子句、decimal_shift()、unit_conversion()、 A2X/X2A/A4X/X4A 四种 API 契约分类的定义、List Report 的导出配置与多表模式写法。 需要这些时查 SAP Help Portal,别凭记忆写。


附录 D — 复核记录(v1.0 → v1.2 改了什么)

第二遍复核以"每个字段名都必须能在已编译的线上代码里找到出处"为标准,逐条回源码验证。 发现并修正了 2 处实质错误、1 处结论反转、1 处未量化风险:

#

位置

初稿写法

问题

修正

1

Step 1.4 主视图

LEFT JOIN I_SDDocumentReasonText ON SDDocumentReason = Item.SalesDocumentRjcnReason

字段域不匹配。I_SDDocumentReasonText 是抬头"订单原因"的文本视图,SalesDocumentRjcnReason 是行项目拒绝原因,两者毫无关系。能编译,结果是错的——最危险的一类错

拆成两个候选字段;文本视图只连到 Header.SDDocumentReason(项目已验证的连接,zcl_query_sd002 L656-658)。新增 §1.6 说明 + V8 验证脚本

2

Step 2.2 DDLX

引用 SalesDocumentRjcnReasonText

该字段在任何视图里都不存在(是 #1 的连带产物),DDLX 会编译失败

改为 SDDocumentReasonText;三层字段名已用脚本交叉验证一致

3

§1.4 / 字段映射表第 15 行

「SKU(客户)」= 自定义字段 YY1_SKU_PRD

结论反转:复核发现标准字段 Item.MaterialByCustomer 才是正解。证据:建单接口、ZZCL_JOB_SD004、ZR_QUERY_SD001_I 都在用它;上线问题清单第 195 条客户原话是"客户物料编码(SKU)";审批接口 ZZS_SDI009_ITEM_IN 也带这个字段

改用 MaterialByCustomer,保留 YY1_SKU_PRD 作为注释备选。新增 §1.7 + V9 比对脚本

4

§1.4

「审批状态被 YY1_ZREWORK_SDH 覆盖」——只说了现象,没说清这个字段是什么

读者无法判断该不该沿用

查清并写入:它是返工标记,OA 传 2(返工)时由 ZZCL_API_SD009 置 'D'。附代码原文,标记为已确认、无需再验

同时确认无误的部分(复核后未改动):

  • 全部 31 列的字段名(SalesDocumentTypeName、CustomerName、SalesOrganizationName、 ProductGroupName、StorageLocationName、SalesDocApprovalStatusDesc 等)—— 逐个在 zcl_query_sd002.clas.abap 的 SELECT 列表里找到原文;

  • 开票的 K/L 与 J/T 双路径连接条件(L847-856);

  • 交货数量聚合写法与退货取负(L752-756、L1159-1168);

  • 订单数量/金额的 CASE 取负口径(L517-522、L434-450);

  • 报价单类型码 AG(L316);

  • 服务定义/绑定的 V4 + C1 契约(对齐 zui_query_sd004_o4);

  • IAM App 类型 External App 与权限对象 V_VBAK_VKO(对齐 zzsd002_ext.sia6.xml)。

仍然不确定、需要上系统验证的(已全部写进附录 B):

  • 拒绝原因口径(V8)——本文档只能给出两个候选和判据,最终必须问业务;

  • SKU 两套字段的实际值(V9);

  • 客户品名的自定义字段落点(V3);

  • 物料长文本的视图名 I_ProductDescription 是否发布(V4);

  • DCL 三字段 pfcg_auth 的位置对应(V6)。

复核过程中额外解决的两个语法疑点(不再是待确认项):

疑点

结论

依据

CDS 里能否用 IS NOT INITIAL

不能照抄 ABAP 写法,改用 = '' / = ' '

项目 57 个 .asddls 中 IS [NOT] INITIAL 出现 0 次;= ''/<> '' 有已激活实例

= '' 空值比较是否可用

可用

zr_vh_zjsph.ddls.asddls L15、zc_materialdocumentheader_tims.ddls.asddls L19(均已激活上线)

本教程所有代码均未在系统上编译过。 复核提升的是"字段名正确性", 不能替代在 D 租户的实编译。按项目纪律,连系统前需先征得同意。

v1.2 补录:把「引用了却没嵌」的 9 张配图补进正文

v1.1 稿有一个明显缺陷:§1.4、§2.1、§2.2、§3.2 的正文里出现了「配图 ABAP_Annos4Views_002a.png 的中文标注」「对照表见配图 `Default_Value_..."」这类句子,但页面里根本没有那张图——只写了文件名,等于让读者去猜。本次逐条补齐:

#

新图号

位置

原图

1

图 6

§Step 1.4 会话变量

Session_Variables_001.png

2

图 7

§Step 1.4 输入参数缺省值

Default_Value_for_Parameters_in_Open_SQL_002.png

3

图 8

§2.1 authorizationCheck 取值

05AnnotationAccessControl_001.png

4

图 9

§2.1 视图头注解

ABAP_Annos4Views_002a.png

5

图 10

§2.2 新建元数据扩展

05MetadataExtensionCreation_001.png

6

图 11

§2.2 @Metadata.layer 层级

Metadata_Extensions_002.png

7

图 12

§3.2 新建 DCL

Create_a_new_Access_Control_001.png

8

图 13

§3.2 DCL 模板选择

Create_Access_Control_003.png

9

图 14

§3.2 DCL 示例

CDSAccessControlExample.png

其中 6 张是 v1.1 正文已经引用到的(图 6–图 9、图 11、图 14),另外 3 张是按同一操作补的「新建」步骤截图(图 10、图 12、图 13)。原图 6–11 顺延为图 15–20。


文档版本 v1.2(配图补录) | 基于本地离线代码与课件分析编写,编写过程中未连接任何 SAP 系统。 v1.2 把 6 张「正文引用了但未内嵌」的 S4D430 配图补进正文,另补 3 张新建步骤截图;v1.1 修订了 2 处会导致错误结果的代码、反转了 1 处字段结论、补齐了 1 处业务语义。 所有代码片段需在 D 租户(my201458)实编译验证后方可用于开发。