09 · 公司开发规范与六大模式(需求进来先对照本卡)

依据:docs/ZZSD项目代码记录.md、docs/MM-PP-FI代码记录.md、docs/SAP公有云开发现状认知.md(三份为我司代码通读结论),以及四个包的 abapGit 导出源码(docs/顾问开发的代码--现有线上代码/)。 适用:在 ZZSD/ZZMM/ZZPP/FI 四个包内做二开与新增;新人上岗第一周精读。 关联:模式 A 的完整教学见 04 章,模式 B 见 07 章,模式 C/D 见 05 章,模式 E 见 06 章。


0. 30 秒决策:这个需求该用哪个模式?

改标准流程/校验? ── 有 released 扩展点 ──→ F 标准增强(简单逻辑也可门① Custom Logic)
读数据出报表?   ── 简单清单 ──→ 门① Analytical Query / Custom CDS
                   复杂(分桶/多源拼装/参数联动/算价)──→ B 查询报表
新建业务对象?   ── 轻量维护 ──→ 门① CBO
                   正式维护 App(草稿/按钮/权限/传输)──→ A 维护类应用
把数据推出 SAP? ── 新接口 ──→ C 出站接口(优先通信场景版)
                   定时/批量 ──→ E 定时任务(内部再调 C)
被外部调用/过账? ──→ D 入站/编排(HTTP Service、EML、金税)

口诀:A 管页面、B 管报表、C 管出去、D 管进来、E 管定时、F 管增强。一个需求通常是一个主模式 + 若干辅助模式,先定主模式再拆对象。


1. 六大模式总卡

模式

形态

对象链(从底到顶)

工作量量级

抄谁

A 维护类应用

带草稿的表格维护 Fiori App

表→ZR_→ZC_+ddlx→BDEF(managed+draft)→ZBP_→srvd/srvb(O4)→smbc→IAM 链

2–5 天/应用

zr_table_ztsd018(SD)、zr_ztmm003(MM)

B 查询报表

只读列表+按钮(发 WMS/导 Excel)

custom entity→投影 BDEF(unmanaged)→ZBP_→ZZCL_QUERY_xNN(if_rap_query_provider)→ZUI_QUERY_xNN_O4

1–3 天/报表

zzcl_query_mm004(MM)、zzcl_query_fi026(FI)

C 出站接口

推外部/回环调标准 API

ZZS_xNN_REQ/RESP→ZZFM_API_xNN(壳)→ZZFM_PUB_xNN(实现)→ZZT_REST_SYSID 配置→CSRF+JSON→ZZS_REST_OUT→结果表

1–2 天/接口

zzfm_pub_sdtodn(SD)

D 入站/编排

被外部调或调标准 BO

HTTP Service / 自建 OData / RFM;凭证走 EML i_journalentrytp 或生成代理;金税 HMAC 签名

1–3 天/接口

zzcl_api_fi001(FI)、zzcl_api_sd003/012(SD)

E 定时任务

Application Job 增量推送

ZZCL_JOB_xNN(if_apj_*)→ZAJT 模板→ZZ_BC_JOB_* 目录→ZTJOB_LOG 增量

0.5–1 天/作业

zzcl_job_mm002(MM)、zzcl_job_fi010/011(FI)

F 标准增强

BAdI 实现类

扩展点(enho)→实现类(只实现 released)

0.5–2 天/增强

zcl_bd_mmpur_final_check_po


2. 模式 A:维护类应用(最高频,标准样板)

对象链(按此顺序建,缺一不可):

#

对象

命名示例

验收

1

数据库表 + 草稿表(_D)

ZZTSD018 / ZDT SD018

表激活、字段与草稿表同步

2

CDS 根视图(ZR_)

ZR_TABLE_ZTSD018

Data Preview 有数、关联正确

3

CDS 消费视图 ZC_ + 元数据扩展 ddlx

ZC_TABLE_ZTSD018

@UI 注解激活、列表/明细字段齐全

4

BDEF(managed + with draft + early numbering)

ZR_TABLE_ZTSD018

strict ( 2 )、mapping 全字段、激活无错

5

行为池 ZBP_

ZBP_R_TABLE_ZTSD018

determination/validation/action 全部实现

6

Service Definition/Binding(O4)

ZUI_TABLE_ZTSD018_O4

Publish 成功、Preview 能增删改/草稿

7

IAM App / Catalog / Role

见 08 章

业务用户(非开发者)能打开并保存

关键约定(与 04 章示例的差异):

  • 公司维护类 App 必须带草稿(with draft)和 smbc(Fiori Elements 表格维护配置),否则业务用户不接受;

  • 编号用 early numbering(创建时即显示单号,PP 包注释原话"这样主键值就会在BO创建前显示");

  • 草稿表结构 = 业务表 + 草稿管理字段,必须手建,且与业务表字段同步(漏字段 = 激活报错);

  • 验收必须用业务用户在 Fiori 里走一遍增删改 + 草稿 Activate/Discard,不能只看 Preview。


3. 模式 B:查询报表(custom entity + 三件套)

对象链:

#

对象

命名

要点

1

custom entity(define custom entity)

ZC_QUERY_xNN

@ObjectModel.query.implementedBy: 'ABAP:<类>',带参数 P_ 前缀

2

实现类(if_rap_query_provider)

ZZCL_QUERY_xNN

抄 ZZCL_QUERY_UTILS 三件套:filtering / orderby / paging

3

投影 BDEF(unmanaged,readonly + 业务 action)

ZC_QUERY_xNN

按钮动作在行为池实现

4

Service Definition/Binding(O4)

ZUI_QUERY_xNN_O4

发布后 Preview 验证筛选/排序/分页

5

IAM 链

见 08 章

—

实现类骨架(从 zzcl_query_mm004 提炼):

METHOD if_rap_query_provider~select.
  " 1) 取请求:paging / filter / sort / requested elements / parameters
  DATA(lv_top)  = io_request->get_paging( )->get_page_size( ).
  DATA(lv_skip) = io_request->get_paging( )->get_offset( ).
  DATA(lt_filter) = io_request->get_filter( )->get_as_ranges( ).
  DATA(lt_sort)   = io_request->get_sort_elements( ).

  " 2) 取数(只碰 released I_* 与自表 ZZT_*)
  SELECT ... FROM i_materialstock_2
    WHERE ... INTO TABLE @DATA(lt_data).

  " 3) 业务计算(账龄分桶、价格、金额…)

  " 4) 统一处理排序/分页(勿自己手写 OFFSET 逻辑)
  zzcl_query_utils=>apply_sorting( EXPORTING it_sort = lt_sort CHANGING ct_data = lt_data ).
  zzcl_query_utils=>apply_paging( EXPORTING iv_top = lv_top iv_skip = lv_skip CHANGING ct_data = lt_data ).

  " 5) 回填
  io_response->set_total_number_of_records( lines( lt_data ) ).
  io_response->set_data( lt_data ).
ENDMETHOD.

⚠️ 不要自己写 OFFSET/UP TO 拼字符串;分页交给三件套。筛选值必须从 get_filter( ) 解析,不要假设前端一定传值。


4. 模式 C:出站接口(配置表 + CSRF + 结果表)

对象链:领号 → REQ/RESP 结构(ZZS_<模块>I<NNN>_REQ/RESP)→ FM 壳(ZZFM_API_xNN)→ 实现(ZZFM_PUB_xNN)→ ZZT_REST_SYSID 配目标系统 → ZZS_REST_OUT 回消息 → 结果表落库(补推/审计)。

实现要点(从 zzfm_pub_sdtodn 提炼,完整代码见 05 章):

" 1) 读目标系统配置(不要硬编码 URL)
SELECT SINGLE * FROM zzt_rest_sysid
  WHERE zztsysid = @self_sysid
  INTO @DATA(ls_sys).

" 2) 取 CSRF token(回环调用 S/4 自己要带 x-csrf-token)
lo_http_client = cl_web_http_client_manager=>create_by_http_destination( ... ).
lo_http_client->get_http_request( )->set_header_fields( VALUE #( ( name = 'x-csrf-token' value = 'Fetch' ) ) ).
lo_response = lo_http_client->execute( if_web_http_client=>get ).
DATA(lv_token) = lo_response->get_header_field( 'x-csrf-token' ).

" 3) /ui2/cl_json 序列化(name_mappings 集中维护,禁止手拼 JSON)
lv_json = /ui2/cl_json=>serialize( data = ls_req pretty_name = /ui2/cl_json=>pretty_mode-camel_case
                                   name_mappings = lt_name_mapping ).

" 4) POST → 解析 → 落结果表 → 返回 ZZS_REST_OUT(msgty/msgtx/uuid)

易错点:URL 带 https:// 直接填 Hostname(要去协议头);CSRF cookie 忘了带;name_mappings 与结构字段漂移;失败不落结果表导致"不知道哪条没推成功"。


5. 模式 D:入站/编排(HTTP Service、EML、金税)

场景

做法

命名

验收

外部调 SAP(轻量)

ADT 建 HTTP Service + handler 类

Z*_SRV / ZCL_*_SRV

Postman 用通信用户 Basic 调通 200 + JSON

外部调 SAP(标准业务)

通信场景 + 通信安排暴露 released API

标准 API 名

API URL + 通信用户调通

SAP 内部过账/改单

EML 调 released BO(i_journalentrytp 等)

ZZCL_API_*

单据创建/修改成功、结果表有记录

金税/第三方

HMAC 签名 + 代理类

ZZFG_FI_NN

联调环境签名校验通过

红线:不直改标准表;过账/改单必须走 BO/API。接口凭证不得写死在代码里,走通信用户/安全参数。


6. 模式 E:定时任务(Application Job)

对象链:ZZCL_JOB_xNN(实现 if_apj_dt_exec_object + if_apj_rt_exec_object)→ Fiori「Application Jobs」建 Job Template(ZAJT_*)→ 排期 → 业务目录授权 → 成功后更新基线表(ZTJOB_LOG 类)。

增量窗口标准写法(修正旧代码的硬编码时区):

" 时间窗口:用用户时区,不写 +8h
DATA(lv_tz) = cl_abap_context_info=>get_user_time_zone( ).
GET TIME STAMP FIELD DATA(lv_end).

SELECT SINGLE FROM ztjob_log
  FIELDS * WHERE jobname = @c_jobname
  INTO @DATA(ls_log).

IF ls_log IS INITIAL.
  " 首次:按业务定义的初始范围
ELSE.
  CONVERT DATE ls_log-jobdate TIME ls_log-jobtime
    INTO TIME STAMP DATA(lv_start) TIME ZONE lv_tz.
ENDIF.

验收:手动 Schedule 一次 → Instances 成功 → 日志有可读消息 → 基线表更新 → 第二次运行只增量不重复 → 时区/DST 场景不丢数。


7. 模式 F:标准增强(BAdI)

  • 只实现 released BAdI(ADT 里能搜到、语法检查通过才是 released);公有云不提供任意位置增强。

  • 实现类命名 ZCL_<扩展点语义>,一个增强点一个类;逻辑简单优先门① Custom Logic(可运维、无需传输开发对象)。

  • 验收:走一遍真实业务触发扩展点 → 断言新逻辑生效 → 回归原逻辑不受影响。


8. 命名规范(四包统一,新增必须遵守)

类型

规范

例

表/草稿表

ZZT_<模块><NNN>(_D 草稿)

ZZTSD018、zztpp003+zdtpp003

API 结构/表类型

ZZS_<模块>I<NNN>_* / ZZTT_*

ZZS_SDI001_REQ

CDS

ZR_(根)/ZI_(接口/值帮助)/ZC_(消费)

—

行为池

ZBP_R_* / ZBP_C_* / ZBP_I_*

—

服务

定义与绑定 ZUI_*_O4(V4)/_O2(V2)

ZUI_QUERY_SD001_O4

API/Job/Query 类

ZZCL_API_ / ZZCL_JOB_ / ZZCL_QUERY_ + 模块 + NNN

—

函数组/模块

ZZFG_<模块>_API / ZZFM_*;FI 按目标系统拆组

ZZFG_FI_NN(诺诺)

编号对象

模块语义名(ZZPTDH)+ nont 区间

—

IAM

ZIAM_* / ZZC_*_EXT(sia6)、ZBC_* / ZZ_BC_*(sia1)

—

Key User 产物

系统自动 YY1_(禁止手工占用该前缀)

—

模块编号即"接口台账":同编号贯穿 结构/表/FM/类/服务(如 MM005 = 外向交货单推送全家桶)。新接口先领号再建对象。


9. 通用实现规约(代码库提炼,评审逐条打勾)

  1. JSON 一律 /ui2/cl_json + name_mappings(ABAP 蛇形 ↔ JSON 驼峰);映射表集中维护在 FM 头部。

  2. 返回消息统一 ZZS_REST_OUT(msgty/msgtx/uuid),接口结果必落结果表供补推与审计。

  3. 数据读取只碰 released CDS(I_*)与自表 ZZT_*;未发布对象语法即红。

  4. 写自定义表走 RAP/EML 或 FM 内 MODIFY;修改标准单据一律调 API/EML,不直改标准表。

  5. 锁:跨系统幂等用 SD 的 ZZFM_LOCK_DATA/UNLOCK_DATA(表 ZZT_CUST_LOCK)模式。

  6. 时区:新代码用 cl_abap_context_info=>get_user_time_zone( );禁抄旧 Job 的 +8h 硬编码。

  7. BAdI 只实现 released 扩展点;实现类命名 ZCL_<扩展点名语义>。

  8. 代理对象(zzfi001 目录)与 sush 记录禁止手改;IAM 变更走 Fiori 应用。

  9. 每个对象必须挂传输请求;gCTS 提交前"激活 + ATC 检查"。

  10. 错误信息:技术异常进日志(APPL_LOG),业务错误用 REPORTED/返回消息给前端,不向用户抛原始异常文本。


10. 代码评审清单(提 PR / 交接前自查)

检查项

判据

对象命名/编号符合第 8 节

一眼能看出模块与用途

无 SELECT *、无 FOR ALL ENTRIES 空表全量

ATC 无 error、代码评审通过

无硬编码 URL/密码/时区

配置表/通信用户/get_user_time_zone( )

接口有结果表 + 可补推

失败记录能查到并重推

错误消息可读(中文/业务语言)

前端能看到 msgty/msgtx

权限:DCL + BDEF authorization master

业务用户访问符合预期

传输请求对象清单干净、描述含工单号

Release 前核对

文档:05/06/07 对应章节的写法能对上

—


11. 已知风险与债务(改动前必读)

#

事项

影响

动作

1

PP 包导出缺全部 .asddls + 行为池类 + 草稿表 + ZZTPP001/002

PP 二开无参考源码

向顾问索要完整导出

2

公共包未导出:ZZT_REST_SYSID/ZZT_REST_APPEND/ZTJOB_LOG/ZTMM002~005

动出站配置/Job 前拿不到定义

同上

3

ZZT_REST_SYSID-zzpwd 明文

安全审计

新接口走通信安排;存量登记台账逐步迁移

4

Job 时区硬编码 + 基线时机

增量漏数风险

新 Job 按 06 章改进

5

name_mappings 手写漂移

字段变更易漏

改接口时 diff 映射表

6

行为池类缺失导致 BDEF 无法激活

无法交付

用 abapGit 拉完整包再改


12. 与环境相关的三条铁律

  1. 连接审批制:任何对 GQN 生产/开发租户的连接(哪怕测试)先经负责人;

  2. 开发只在 D 租户,练习自建包,不碰他人对象;

  3. 传输:D→TEST→PROD 走 gCTS,勿本地发布越级。


➡️ 下一步