sap-report-automation-workflow

End-to-end SAP ABAP 开发对象自动化——通过 node-rfc 直连 SADT_REST_RFC_ENDPOINT 调用 RFC ADT API。支持 REPORT/CLAS/FUGR/INTF/Include 全部对象类型。FS 规范化→DDIC 元数据→技术文档→按模板写 ABAP→激活循环。S0 探测 ABAP 版本并约束后续代码可用语法；SAP 查询统一走 `scripts/rfc_client.js`；部署按对象类型走 `deploy_report.js`/`deploy_report_include.js`/`deploy_fugr.js`/`deploy_clas.js`/`deploy_intf.js`。语法速查 [abap-syntax-quickref.md](abap-syntax-quickref.md)，卡点速查 [troubleshooting.md](troubleshooting.md)。

Ir a la instalación

Repositorio: AsToHot/sap-report-automation-workflow
Última actividad en el origen: 24 de julio de 2026 a las 06:18
Idioma detectado de SKILL.md: chino
Estrellas: 7
Forks: 2

Opciones de instalación

De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.

Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.

Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.

npx skills add https://github.com/AsToHot/sap-report-automation-workflow --skill sap-report-automation-workflow

El comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.

¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.

Revisa los archivos de origen

Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.

Explorador de archivos

8 archivos

SKILL.md

Instrucciones de origen · Vista previa de solo lectura

Volver a la búsqueda Volver a la instalación

Explorador de archivos

8 archivos

SKILL.md

Instrucciones de origen · Vista previa de solo lectura

name

sap-report-automation-workflow

description

SAP ABAP 开发对象自动化工作流（FS → 元数据 → 设计文档 → 代码 → 激活）

支持对象类型（S2 确认）：REPORT、CLAS、FUGR（含 Function Module）、INTF、PROG/I（Include）。

连接架构

# 查询链路
AI Agent → Bash → node scripts/rfc_client.js → node-rfc → SADT_REST_RFC_ENDPOINT → SAP

# 部署链路（按对象类型分发）
AI Agent → Bash → node scripts/deploy_report.js           → node-rfc → SADT_REST_RFC_ENDPOINT → SAP
                     node scripts/deploy_report_include.js
                     node scripts/deploy_fugr.js
                     node scripts/deploy_clas.js
                     node scripts/deploy_intf.js

所有 SAP 操作通过统一 RFC 客户端 scripts/rfc_client.js（通用查询）和 5 个类型专用部署脚本直连。deploy_rfc.js 保留为兼容入口。不再使用 MCP/HTTP 代理中间层。

阶段间强引用（元数据驱动；禁止凭语感写 Open SQL）

后续阶段必须显式引用前序产物，禁止凭记忆拼字段名/表名/JOIN 条件：

消费方	必须参照的输入	规则
`docs/tech-design.md`	`spec/functional-spec-ai.md` + `metadata/tables/*.json`	每个物理字段须在元数据中可核对
ABAP（Open SQL、内表）	`docs/tech-design.md` 的「字段契约」+ `metadata/tables/*.json`	SELECT/JOIN/WHERE 字段名必须来自契约或元数据
ALV 列 / 内表组件	同上	列名与契约一致，计算列在契约中写清公式

字段契约（S6 技术文档中必写）：docs/tech-design.md 中至少包含：

逻辑项	表名	字段名	元数据文件
…	BKPF	BUKRS	output//metadata/tables/BKPF.json

代理自主执行协议

代理在同一任务内按阶段 0→1→2→3→4→5→6→7→8→9→10→11 顺序自动跑完，仅在缺关键输入、SAP 不可达、或达重试上限时停顿。

硬门禁（除非用户明确说跳过）： 0. test_rfc.js 未通过 → 禁止进入 S1。代理必须指导用户完成 NW RFC SDK 安装和 .env 配置。

无 functional-spec-ai.md → 禁止写 ABAP、禁止部署。
S2 对象名未确认（或已存在未覆盖授权） → 禁止进入 S3。
无 metadata JSON 落盘 → 禁止进入 S4。
fs-ddic-verification.md 有语义偏差未修正 → 禁止进入 S6。
无 tech-design.md（含字段契约+选择屏幕角色分析）→ 禁止进入 S9。
deployment-config.md 未生成（包/请求号/模板未明确） → 禁止进入 S10。 9-10. 必须实际调用 SAP，失败时自动修错循环直至成功或达上限。

Preflight Gate：任何 SAP 写操作前，必须确认 stage-gate.md 中 S0→S8 全部为 yes。禁止在门禁未通过时调用任何部署脚本或写操作。

受阻时先查 troubleshooting.md，按"预判→预防→应对"处理。

S0：RFC 环境验证与连接

代理自动执行诊断，仅凭据和系统级依赖缺时打断用户。

0.1 环境探测

node scripts/test_rfc.js

通过 → 继续。失败 → 按输出分类诊断（DLL 缺失 / 环境变量 / 网络不通），指导用户修复。

唯一允许打断用户的：Node.js 安装、NW RFC SDK 安装、SAP 连接凭据。

0.2 `.env` 配置（6 个字段）

字段	必需	说明
`SAP_URL`	是	SAP 主机地址，如 `http://<host>:<port>`
`SAP_CLIENT`	是	客户端号（如 `200`）
`SAP_SYSNR`	是	RFC 实例号——不可依赖端口推导
`SAP_USERNAME`	是	开发账号
`SAP_PASSWORD`	是	密码
`SAP_ROUTER`	否	Router 字符串（内网穿透）

双系统配置：开发系统 .env，数据系统 .env.data。二者 SAP_SYSNR 通常相同，但 SAP_CLIENT 不同。

代理写入配置文件后不启动任何后台进程——rfc_client.js 每次执行时自动连接、执行、断开。

0.3 连通验证

# 一键双系统检测
node scripts/rfc_dual_check.js

两个系统都 "ok": true → 已就绪。任一失败 → 按 troubleshooting.md §4 排查。记录到 stage-gate.md 的 S0=connection-ok。

0.4 双系统架构（硬约束）

配置文件	用途	SAP_CLIENT
`.env`	开发：创建/修改/激活/语法检查	由用户指定（如 200）
`.env.data`	数据：runQuery/tableContents	由用户指定（如 300）

三条死线：

禁止用开发系统查业务表数据 → 开发机可能无数据
禁止把 .env 客户端改成数据系统客户端 → 部署会落到数据机
禁止因查不到数据而反复重写代码 → 先用 --env=.env.data 确认数据存在

0.5 权限前置探测

# 开发权限探针
node scripts/rfc_client.js --sql "SELECT COUNT(*) AS CNT FROM TADIR WHERE PGMID EQ 'R3TR' AND OBJECT EQ 'PROG'" --table TADIR

# 包权限探针（用户提供包名后）
node scripts/rfc_client.js --search "<包名>" --type DEVC

记录到 stage-gate.md 的 S0=permission-check。

0.6 ABAP 版本探测（写代码前强制）

在 S9 写 ABAP 之前，必须知道目标开发系统的 ABAP release，否则无法判断内联声明、VALUE、CORRESPONDING 等新语法是否可用。

# 默认读取 .env
node scripts/detect_abap_version.js

# 数据系统（如需要）
node scripts/detect_abap_version.js --env=.env.data

输出示例：

{
  "status": "success",
  "system": {
    "sysid": "DEV",
    "database": "HDB",
    "sapReleaseRaw": "7400",
    "sapRelease": 740
  },
  "versionTier": "s4hana_early",
  "allowedSyntax": ["🔵", "🟢"],
  "notes": "ECC 6.0 EHP7/EHP8（ABAP 7.40）：仅可用 🔵 与 🟢 语法"
}

处理规则：

sapRelease 为 null 或 < 700 → 按最严格 ecc_legacy 处理，只允许 🔵 语法
allowedSyntax 写入 stage-gate.md 的 S0=abap-version
S9 写代码时，只准使用 allowedSyntax 内图标标注的语法；遇到新语法需求必须先确认版本

记录到 stage-gate.md 的 S0=abap-version。

0.7 切换 SAP 系统

用户说「换系统/切客户端/改密码」→ 更新对应 .env 文件 → 重新执行 0.3 连通验证。无需重启任何进程。

S1：获取 FS → 规范化为 AI 可读的功能文件

1.0 获取 FS

代理一次性询问 FS 来源：A.粘贴文本 / B.提供文件路径(.docx/.txt/.md) / C.文件夹 / D.口头描述。

若用户提供 .docx 文件，用 extract-docx.js 提取文本：

node scripts/extract-docx.js "<路径>"

1.1 规范化 FS

套用 templates/functional-spec-ai.md，必须包含：业务目标与对象类型、选择条件（REPORT）/方法签名（CLASS/INTF/FUGR）、输出列与来源表字段、透明表清单、权限/性能/变式约束。表名一律大写。

S1 门禁：FS 中每个表名可在 DDIC 中查到；SPRAS 字段标注为 LANG(1) 不得写 'ZH'；输出列无 TBD。

S2：对象名确认与 SAP 存在性检查

确定对象名与类型

对象类型	ADT 码	命名约定	示例
可执行报表	`PROG/P`	`ZSAP_xxx` / `ZFI_xxx`	`ZSAP_FI086`
Include	`PROG/I`	`ZSAP_xxxT01` / `ZSAP_xxxF01`	`ZSAP_FI086T01`
全局类	`CLAS`	`ZCL_xxx`	`ZCL_FI_UTILITY`
函数组	`FUGR`	`ZFG_xxx`	`ZFG_FI_TOOLS`
接口	`INTF`	`ZIF_xxx`	`ZIF_FI_DATA_ACCESS`

2.2 SAP 存在性检查

# 查主对象 + 所有 Include
node scripts/rfc_client.js --search "ZSAP_FI086"
node scripts/rfc_client.js --search "ZSAP_FI086T01"

已存在 → 立即停止，报告对象名/类型，让用户重新提供或书面确认覆盖。禁止代理擅自改对象名或跳过。均不存在 → [OK]，继续 S3。

S2 门禁：全部对象名在 SAP 中均不存在，或用户已书面确认覆盖。

S3：透明表 DDIC 元数据

Z 表也必须拉 DDIC

首选封装脚本（一键完成取数 + JSON 落盘）：

node scripts/rfc_fetch_ddic.js --env=.env.data <TABNAME> output/<program>/metadata/tables/

备选手工路径（脚本不可用时）：

node scripts/rfc_client.js --env=.env.data --rows=2000 \
  --sql "SELECT FIELDNAME, POSITION, KEYFLAG, ROLLNAME, DATATYPE, LENG, DECIMALS FROM DD03L WHERE TABNAME EQ '<T>' ORDER BY POSITION" \
  --table DD03L

每表串行拉取
fetched_count 为 0 时自动重试最多 3 次
每表独立落盘 metadata/tables/<TABNAME>.json
失败切备选路径（--source → 兜底 RFC），三种均尝试完毕才记入 _errors.md

S4：FS → DDIC 字段交叉验证（强制）

硬约束：业务人员写 FS 时可能写错字段名或误解字段语义。metadata JSON 落盘后必须立即逐字段对照验证，禁止盲目信任 FS。

4.1 验证内容

对 functional-spec-ai.md 中引用的每个 表.字段：

存在性：字段在 DD03L 中确实存在
类型：数据类型匹配预期使用方式
语义：字段的实际含义与 FS 描述一致（重点：SELECT-OPTIONS 的字段是真正的过滤字段还是参考字段）
字面值陷阱：SPRAS=LANG(1) 强制 '1' 非 'ZH'；DATS 格式 'YYYYMMDD'
符号约定（新增）：金额列需逐列确认 FS 中定义的是绝对值还是带符号值——SAP 中 DRCRK='H' 的金额通常存为负数，若 FS 按绝对值描述则代码需额外处理。验证方法：取一行真实数据，检查 DRCRK='S' vs 'H' 的实际符号，与 FS 描述对照，在 tech-design.md 字段契约中标注每列的符号来源

4.2 验证输出

落盘 spec/fs-ddic-verification.md：每表每字段一行，标注存在性+类型+语义审查结果。不通过项标注为 TBD，等用户澄清后再进入 S6。

S4 门禁：全部 FS 引用字段在 DDIC 中存在；语义偏差已标注并修正（或用户确认）；fs-ddic-verification.md 已落盘。

S5：性能预估

对主驱动表执行 COUNT：

node scripts/rfc_client.js --env=.env.data \
  --sql "SELECT COUNT(*) AS CNT FROM <主表> WHERE <最严格条件>" --table <主表>

< 10,000 → 全量 ALV
10,000 ~ 1,000,000 → 建议分页
> 1,000,000 → 必须后台执行

结果写入 performance-estimate.md。

S5 门禁：每张表有 metadata JSON 且 matched=true；performance-estimate.md 已生成；多期金额表已通过数据系统取一行真实数据确认分布方式。

S6：技术文档 `docs/tech-design.md`

必须包含：字段契约（FS 列/表.字段/metadata 溯源）、表清单、关联路径、取数逻辑、选择屏幕字段角色分析（四角色分类）、ALV 布局、性能设计（内表类型/嵌套 LOOP 替代/WHERE 排列/数据量预估）。

选择屏幕字段角色分析（强制）

硬约束：每个选择屏幕字段必须先确定为四角色之一再决定使用方式，禁止默认全部塞入 WHERE。

角色	说明	示例	使用方式
WHERE 过滤	直接过滤主表行	P_RYEAR、S_RACCT	放入 FAGLFLEXT SELECT 的 WHERE 子句
映射键	需经中间表转换	P_BUKRS	先查 ZSAP_BUKRS 得到 RBUKRS，再用于 WHERE
计算参数	不过滤行，决定聚合范围	S_RPMAX	不出现于 WHERE；决定 HSL{start}~HSL{end} 索引范围
显示控制	不影响取数，控制输出	P_FORCUR	控制 ALV 列 visible/technical

S6 门禁：tech-design.md 含字段契约 + 选择屏幕字段角色分析表；fs-coverage.md 覆盖全部输出列；template-mapping.md 列出新旧 INCLUDE 对应；deployment-config.md 已生成。

S7：FS 对齐审查 `docs/fs-coverage.md`

FS 逻辑项	输出字段	契约字段（表.字段）	元数据文件	代码落点	状态

FS 中每个输出列/选择条件都必须出现一行。S10 前做反查：从最终代码回填确认无遗漏。

S8：部署配置 `docs/deployment-config.md`

确认三项并落盘：

开发包：用户提供或默认 $TMP（本地包无需传输请求）
传输请求：仅非 $TMP 时需要
模板选择：优先 templates/reference/<对象名>/，其次默认模板，无模板用 quickref 骨架

必须按如下固定格式写入（部署脚本通过正则解析）：

| 程序名 | ZTESTXXX |
| 目标包 | $TMP |
| 传输请求 | — |
| 程序描述 | <程序功能描述> |

部署脚本用 | 目标包 | ([^|]+) | 正则提取包名。不用此格式会报 Package name not found。`

S8 门禁：deployment-config.md 已生成，包/请求号/模板状态明确。

S9：按类型生成代码

语法硬约束：以 abap-syntax-quickref.md 为参考，禁止凭记忆写语法。

对象类型分发

类型	代码文件	部署脚本	参考模板
REPORT	主程序 + T01/SEL/F01 分层	`deploy_report_include.js`	`templates/reference/<模板程序名>/`
REPORT（无 INCLUDE）	主程序单个文件	`deploy_report.js`	quickref §1–6
CLAS	`<名>.clas.abap`（单文件）	`deploy_clas.js`	quickref §11
INTF	`<名>.intf.abap`	`deploy_intf.js`	quickref §12
FUGR	`<FM名>.fm.abap`（每 FM 一个文件）	`deploy_fugr.js`	quickref §13

REPORT 生成

强制先读模板：打开 templates/reference/report/ 下全部 4 个文件，逐行理解其结构后再写代码。禁止跳过后直接写。
打开 tech-design.md → metadata/tables/*.json → abap-syntax-quickref.md
INCLUDE 分层强约束：主程序 + T01/SEL/F01 保持模板结构
生成前先写 template-mapping.md
反模式自检通过（见 S9 通用反模式自检）

GUI Status 强制规则（CL_SALV_TABLE 专用，已激活旧对象可能用sy-repid+S1000，不要模仿）：

CL_SALV_TABLE 的 set_screen_status 必须用 report = 'SAPLKKBL'，绝不能是 sy-repid
必须在 display() 前调用，带 pfstatus = 'STANDARD' 和 set_functions = gr_alv->c_functions_all

pfstatus 'STANDARD' 是 SAPLKKBL 自带的 GUI 状态；不要使用自定义 'S1000'，它仅适用于 sy-repid 自定义状态。

禁止参考 output/ 下旧对象：已有项目可能使用旧版单文件结构，不是本技能规定的标准。必须严格按模板 templates/reference/report/ 分层结构生成。

CLASS/INTF/FUGR 生成

1、按 quickref §11–13 骨架。FM 参数用 ABAP 原生语法（FUNCTION ... IMPORTING/EXPORTING ... ENDFUNCTION），禁止 *"*" 注释块格式。 2、参考模板templates/reference/class/、templates/reference/function/、templates/reference/interface/

通用反模式自检（6 轮，强制）

代码写入后、部署前，逐轮检查（详见 abap-syntax-quickref.md §14）：

第负一轮 — ASSIGN COMPONENT：扫描每个 ASSIGN COMPONENT，对照 metadata JSON 确认拼接变量 DATATYPE/LENG；NUMC 类型确认字段名长度匹配；每个后有 sy-subrc 检查。

第零轮 — DDIC 字面值：扫描所有字面值对照 metadata LENG。重点陷阱：SPRAS(LANG, LENG=1) 必须用 '1' 非 'ZH'。

第零轮(2) — 模板代码风格对齐：逐项对照 templates/reference/report/(其他程序类型，对应不同文件夹) 检查：

✅ GUI Status：report = 'SAPLKKBL'（不是 sy-repid），pfstatus = 'STANDARD'（不是 'S1000'），在 display() 前调用
✅ INCLUDE 分层：主程序仅 REPORT+INCLUDE+事件块，FORM 在 F01 中
✅ 列格式化：用 set_column 辅助 FORM（非内联 CAST cl_salv_column_table）
✅ FIELD-SYMBOLS 不同 FORM 不同名
✅ 主程序不含除 REPORT/INCLUDE/事件块以外的代码

第一~五轮：DB → WHERE → 内表 → 控制流 → 其他规范（无 Hard Coding/有 AUTHORITY-CHECK）。

任一轮未通过 → 修正源码后再继续。

S9 门禁：ASSIGN COMPONENT 字段名对齐 + 7 轮自检通过（含模板代码风格对齐） + 源码结构与 template-mapping.md 一致 + 选择屏幕文本已设置 + GUI Status 用 'SAPLKKBL'。

选择屏幕文本元素处理

选择屏幕参数/选择项的中文标签通过以下两种运行时方法设置，无需 SE32 文本元素。

方法一：直接赋值（单参数，最简单）

AT SELECTION-SCREEN OUTPUT.
  %_p_param_%_app_%-text = '参数标签'.
  %_s_selopt_%_app_%-text = '选择项标签'.

格式：%_<名>_%_app_%-text，其中 <名> 为 PARAMETERS 或 SELECT-OPTIONS 的名称（大写）。

方法二：SELECTION_TEXTS_MODIFY FM（多参数，推荐）

FORM modify_sel_texts.
  DATA lt_sel TYPE TABLE OF rsseltexts.
  DATA ls_sel TYPE rsseltexts.

  ls_sel-name = 'P_BUKRS'.
  ls_sel-kind = 'P'.           " P=PARAMETERS, S=SELECT-OPTIONS
  ls_sel-text = '公司代码'.
  APPEND ls_sel TO lt_sel[].

  CALL FUNCTION 'SELECTION_TEXTS_MODIFY'
    EXPORTING
      program                     = sy-repid
    TABLES
      seltexts                    = lt_sel
    EXCEPTIONS
      program_not_found           = 1
      program_cannot_be_generated = 2
      OTHERS                      = 3.
  IF sy-subrc <> 0.
    MESSAGE ID sy-msgid TYPE sy-msgty NUMBER sy-msgno
            WITH sy-msgv1 sy-msgv2 sy-msgv3 sy-msgv4.
  ENDIF.
ENDFORM.

调用（在主程序的 AT SELECTION-SCREEN OUTPUT 中）：

AT SELECTION-SCREEN OUTPUT.
  PERFORM modify_sel_texts.

约束

ls_sel-name 必须与 PARAMETERS / SELECT-OPTIONS 声明名大写完全一致
ls_sel-kind：'P' = PARAMETERS，'S' = SELECT-OPTIONS
ADT 部署优先用方法一（%_xxx_%_app_%-text）：方法二将 FORM 放在 INCLUDE 中，更新部署时 ADT 激活可能因 INCLUDE 解析先后顺序找不到 FORM。方法一直接在主程序 AT SELECTION-SCREEN OUTPUT 中赋值，无此问题
SELECTION-SCREEN BLOCK 的 TITLE TEXT-xxx 不适用上述两种方法；用 WITH FRAME 不加 TITLE 即可

阶段门禁产物验证

每阶段完成落盘 stage-gate.md：

S0=connection-ok: yes/no
S0=permission-check: yes/no
S0=abap-version: yes/no
S1=functional-spec-ready: yes/no
S2=object-name-confirmed: yes/no
S3=metadata-ready: yes/no
S4=fs-ddic-verified: yes/no
S5=performance-estimate-ready: yes/no
S6=tech-design-ready: yes/no
S7=fs-coverage-ready: yes/no
S8=deployment-config-ready: yes/no
S9=code-generated: yes/no
S10=activated: yes/no
S11=smoke-test-passed: yes/no

门禁通过后由用户决定是否 git add + git commit，格式建议：[SAP-WF] 阶段X: 简述产物。代理不自动执行 git 提交。

S10：部署与激活

2026-07 重构：部署脚本按对象类型拆分为 5 个独立脚本，每个有可重复的入参出参示例。deploy_rfc.js 保留为兼容入口（REPORT + 固定 INCLUDE 结构）。

部署脚本选型（按对象类型分发）

对象类型	脚本	源码文件约定
REPORT（无 INCLUDE）	`node scripts/deploy_report.js <名>`	`output/<名>/abap/<名>.abap`
REPORT + INCLUDE	`node scripts/deploy_report_include.js <名>`	主程序 + 从源码自动发现 INCLUDE 名
FUGR + FM	`node scripts/deploy_fugr.js <名>`	`output/<名>/abap/<FM名>.fm.abap`
CLAS	`node scripts/deploy_clas.js <名>`	`output/<名>/abap/<名>.clas.abap`
INTF	`node scripts/deploy_intf.js <名>`	`output/<名>/abap/<名>.intf.abap`
REPORT（固定 T01/SEL/F01/O01）	`node scripts/deploy_rfc.js <名>`	兼容旧模板

部署前复核

S2 的 --search 结果已记录，程序名一致
stage-gate.md 中 S8=yes
deployment-config.md 已按固定表格格式生成

标准流程（所有脚本通用）

每个脚本内部执行：创建对象 → Lock → 上传源码 → Unlock → 激活 → 验证版本。

关键行为规则（2026-07 实战验证）：

规则	说明
INCLUDE 自动发现	`deploy_report_include.js` 从主程序源码 `INCLUDE xxx.` 指令提取 INCLUDE 名，不限死 T01/SEL/F01
FM 必须入激活列表	只激活 FUGR 不会激活其 FM。`deploy_fugr.js` 自动把 FUGR + 所有 FM 放入一个 activation 请求
CLAS/INTF 走 OO URI	CLAS 激活 URI 是 `/oo/classes/`，INTF 是 `/oo/interfaces/`，不能用 `activateObjects()` 的 programs URI
已存在 = 405 或 409	此系统"已存在"返回 405，不是标准 409。所有新脚本兼容两种
激活响应体可能为空	HTTP 200 + 空 body = 激活成功（此系统行为）
Syntax check 405	此系统不支持独立语法检查，激活时验证语法

部署后验证（所有脚本自动执行）

每个脚本激活后自动 GET 对象元数据，提取 adtcore:version 字段确认 active。结果以 JSON 输出：

{"status":"success","objects":[{"name":"ZTEST006","type":"PROG/P","version":"active"},...],"errors":[]}

锁管理

Lock Handle 持久化到 .locks/<name>.json。残留锁用 scripts/release_locks.js 清理。

S10 门禁：部署成功，所有对象 version=active。

S11：冒烟测试（激活后强制，不可跳过）

执行范式强制参照：smoke-test-procedure.md——含入参矩阵、手工计算步骤、逐字段比对脚本模板。

硬门禁（代理不得自行跳过）

禁止在 ZREPORT_EXEC_VERIFY FM 不存在或不返回 EV_SUCCESS='X' 时标记 S11=yes
禁止仅跑一次 verify_report.js 看返回码即通过
禁止 smoke-test.md 的数值来源于推测/人工伪造——所有数必须来自 verify_report.js 真实返回的 EV_DATA_JSON；伪造数据是严重违规，发现后必须重写并道歉
禁止源表数据全零时不标注"数据全零，计算逻辑待补充验证"即通过
禁止仅比对金额列；描述列（TXT50/ZFZHS/ZFZTX/ZYJKM）也必须逐列比对
必须≥2 个不同公司代码、≥3 组参数组合、≥8 个金额列逐列 0.01 容差匹配
smoke-test.md 落盘路径为 output/<程序>/smoke-test.md（非 docs/ 子目录）

数据抽样（fetch_table.js 统一入口——DDIC 端点，WHERE 可靠）

# 通用取数（走 DDIC 端点 /sap/bc/adt/datapreview/ddic，WHERE 可靠过滤）
node scripts/fetch_table.js --table=FAGLFLEXT \
  --fields=RYEAR,RBUKRS,RACCT,RPMAX,DRCRK,HSLVT,HSL01,HSL02,HSL03,HSL04 \
  --where="RYEAR = '2026' AND RBUKRS = '80K0' AND RACCT = '1002000001'" \
  --rows=50

# data_sampler.js 已重构为 fetch_table.js 的薄包装，参数格式兼容
node scripts/data_sampler.js "--table=FAGLFLEXT" "--where=RYEAR = '2026'" "--fields=RACCT,DRCRK" "--rows=50"

入参：--table / --where / --fields / --rows / --env 出参：JSON { table, where, rowCount, columns, rows, _validation: { passed, failures[] } }

硬约束：取数后必须检查 _validation.passed，任意字段不匹配 WHERE 条件则立即阻断。禁止在取数失败/过滤错误时继续后续步骤。

关键维度选择（如适用）

若报表涉及公司代码（BUKRS）等维度，需先确定有效值：

# 1. 找有数据的关键维度值
node scripts/data_sampler.js "--table=FAGLFLEXT" "--where=RYEAR = '2026'" "--rows=5"
# 2. 查映射表（如 ZSAP_BUKRS 的 ZFGS/ZZGS）
node scripts/data_sampler.js "--table=ZSAP_BUKRS" "--fields=BUKRS,ZFGS,ZZGS" "--rows=100"
# 3. 确定有效值（ZFGS=''→BUKRS; ZFGS≠''→ZZGS）
# 4. 验证有效值在主表中有数据

报表执行校验

node scripts/verify_report.js <程序名> P_xxx=<值> "S_xxx=低-高,低-高"

前提：ZREPORT_EXEC_VERIFY FM 已在 SAP 开发系统部署。 verify_report.js 调用 FM → SUBMIT 报表 → 捕获 SALV 数据 → 返回 JSON。

11.4 verify_report.js 失败排查（实战教训）

verify_report.js 失败时，不要先怀疑连接——同一个 SAP 实例（同一 ashost+sysnr）下的不同客户端必定同时连通或同时不通。错误 "An exception has occurred that was not caught" 是报表程序本身的 ABAP 异常（dump 或 TYPE E 消息），而非 RFC 连接问题。

症状	最可能根因	检查方法
`An exception has occurred that was not caught`	报表内部 ABAP dump：AUTHORITY-CHECK 用错字段、消息 TYPE 'E'、数据转换错	检查 F01 逻辑，特别是 authority_check 是否传了正确字段
`Fill all required fields` / 参数类 404	ZREPORT_EXEC_VERIFY 的 IT_RSPARAMS 结构不对	直接 node-rfc 传参测试（跳过 verify_report.js 参数解析层）
`ZREPORT_EXEC_VERIFY` FM 404	FM 未部署	检查 docs/ 下部署记录
RFCEXEC 相关错误	网络/路由/NW-RFC-SDK	先跑 `node scripts/test_rfc.js` 确认客户端连通，再跑 `node scripts/test_rfc.js .env.data` 确认数据系统连通

关键原则：先最小化——用直接 node-rfc 调用 FM 排除脚本层问题，再逐层向上排查。

逐字段比对（例子：8 金额列 + 5 描述列）

金额列: ZQCJF, ZQCDF, ZBQJF, ZBQDF, ZBNJF, ZBNDF, ZQMJF, ZQMDF (×外币列 if P_FORCUR=X)
描述列: ZYJKM, RACCT, TXT50, ZFZHS, ZFZTX

每列必须：
  - 金额列: |程序值 - 源表手工计算值| < 0.01
  - 描述列: 程序值 = 单独查 SKAT/SKA1/TFKBT 的值

ALV 列核对

静态分析源码，确认列名/列数与 fs-coverage.md 一致。外部币列受 P_FORCUR 控制。

S11 门禁：

三步不可跳过（源表采样 → 手工预期 → verify_report.js 多组比对）
≥2 单选、≥3 多选参数组合 SUCCESS
8 金额列 + 5 描述列逐列比对通过
全零数据必须检查是否程序出问题
output/<程序>/smoke-test.md 已按 smoke-test-procedure.md 模板生成

全工作流 SAP 操作速查

阶段	操作	命令
S0	环境诊断	`node scripts/test_rfc.js`
S0	双系统连通	`node scripts/rfc_dual_check.js`
S0	权限探测	`node scripts/rfc_client.js --sql "SELECT COUNT(*) AS CNT FROM TADIR WHERE PGMID EQ 'R3TR'" --table TADIR`
S0	ABAP 版本探测	`node scripts/detect_abap_version.js [--env=.env.data]`
S1	提取 DOCX	`node scripts/extract-docx.js "<路径>"`
S2	查对象名	`node scripts/rfc_client.js --search "<对象名>"`
S3	拉 DD03L	`node scripts/rfc_fetch_ddic.js --env=.env.data <TABNAME> output/<prog>/metadata/tables/`
S4	主表 COUNT	`node scripts/rfc_client.js --env=.env.data --sql "SELECT COUNT(*) AS CNT FROM <主表>" --table <主表>`
S8	验证包	`node scripts/rfc_client.js --search "<包名>" --type DEVC`
S10	部署 REPORT（单文件）	`node scripts/deploy_report.js <程序名>`
S10	部署 REPORT+INCLUDE	`node scripts/deploy_report_include.js <程序名>`
S10	部署 FUGR+FM	`node scripts/deploy_fugr.js <函数组名>`
S10	部署 CLAS	`node scripts/deploy_clas.js <类名>`
S10	部署 INTF	`node scripts/deploy_intf.js <接口名>`
S10	部署（兼容旧模板）	`node scripts/deploy_rfc.js <程序名>`
S11	取数（DDIC 端点）	`node scripts/fetch_table.js --table=<T> --where="<cond>" --fields=<f> --rows=<n>`
S11	数据采样（兼容）	`node scripts/data_sampler.js "--table=<T>" "--where=<cond>" "--rows=100"`

增量更新机制

FS 变更时禁止默认全量重跑。按变更类型选择恢复起点：

变更类型	恢复起点	需重新执行
纯输出列调整	S7	7, 9, 10, 11
新增/替换透明表	S3	3, 4, 5, 6, 7, 9, 10, 11
选择屏条件变更	S6	6, 5(重估), 7, 9, 10, 11
模板/INCLUDE 结构调整	S9	9, 10, 11

规则：已有 metadata JSON 不得删除重建；先拉基线再应用变更；增量更新后在 stage-gate.md 追加版本号。

执行检查清单

- [ ] S0: test_rfc.js 通过，双系统 --discovery 通过，权限前置探测通过，ABAP 版本已探测并记录 allowedSyntax
- [ ] S1: functional-spec-ai.md 结构完整，表名大写
- [ ] S2: --search 确认全部对象名在 SAP 中不存在（或用户书面确认覆盖）
- [ ] S3: 每张表有 metadata JSON (matched=true)，_errors.md 完整
- [ ] S4: fs-ddic-verification.md 已生成，全部字段存在+语义审查通过
- [ ] S5: performance-estimate.md 已生成
- [ ] S5: 多期金额表已通过数据系统取真实数据确认分布
- [ ] S6: tech-design.md 含字段契约 + 性能设计
- [ ] S7: fs-coverage.md 覆盖 FS 全量字段
- [ ] S8: deployment-config.md 已生成（包/请求号/模板明确）
- [ ] S9: ASSIGN COMPONENT 字段名对齐 + sy-subrc 检查 + 反模式自检通过 + 选择屏幕文本已设置
- [ ] S9: 源码结构与 template-mapping.md 一致
- [ ] S10: 对应类型部署脚本成功，激活无错误
- [ ] S11: ZREPORT_EXEC_VERIFY FM 已确认存在
- [ ] S11: 关键维度数据已验证存在（如公司代码等）
- [ ] S11: 源表手工聚合 vs verify_report.js 输出逐列比对通过
- [ ] S11: ≥3 组参数组合 SUCCESS
- [ ] S11: output/<程序>/smoke-test.md 按 smoke-test-procedure.md 模板生成
- [ ] 每阶段 gate 通过后 git commit（推荐）

附录：关键 RFC ADT 端点与故障排查

常用端点

操作	方法	URI
Discovery	GET	`/sap/bc/adt/discovery`
搜索对象	GET	`/sap/bc/adt/repository/informationsystem/search?operation=quickSearch&query=<q>&maxResults=<n>`
SQL 查询（指定表）	POST	`/sap/bc/adt/datapreview/ddic?rowNumber=<n>&ddicEntityName=<T>`
SQL 查询（自由）	POST	`/sap/bc/adt/datapreview/freestyle?rowNumber=<n>`
读取源码	GET	`/sap/bc/adt/programs/programs/{name}/source/main`
创建程序	POST	`/sap/bc/adt/programs/programs`
创建 Include	POST	`/sap/bc/adt/programs/includes`
创建类	POST	`/sap/bc/adt/oo/classes`
创建接口	POST	`/sap/bc/adt/oo/interfaces`
创建函数组	POST	`/sap/bc/adt/functions/groups`
创建 FM	POST	`.../fmodules`（命名空间 `fmodules`，非 `groups`）
Lock	POST	`{objectUri}?_action=LOCK&accessMode=MODIFY`
激活	POST	`/sap/bc/adt/activation?method=activate&preauditRequested=false`

对象类型映射

ADT 码	URI 前缀	命名约定
`PROG/P`	`/sap/bc/adt/programs/programs/`	`ZSAP_xxx`
`PROG/I`	`/sap/bc/adt/programs/includes/`	`ZSAP_xxxT01`
`CLAS`	`/sap/bc/adt/oo/classes/`	`ZCL_xxx`
`INTF`	`/sap/bc/adt/oo/interfaces/`	`ZIF_xxx`
`FUGR`	`/sap/bc/adt/functions/groups/`	`ZFG_xxx`

故障排查速查

症状	根因	解决
`test_rfc.js` DLL 加载失败	SAPNWRFC_HOME/PATH 未设	设置 Windows 系统环境变量，完全重启终端
RFC 连接超时	Router/防火墙/端口	检查 VPN，核对 SAP_ROUTER
创建报 409	程序已存在	必须问用户，禁止自动跳过
创建报 405（非 409）	此系统"已存在"返回 405 而非 409	脚本兼容处理：405+body 含 AlreadyExists
激活 HTTP 200 但空 body	此系统激活成功不返回 XML	正常行为。部署后 GET 元数据确认 `version="active"`
激活 HTTP 200 但 FM 仍 inactive	只激活了 FUGR 没激活 FM	FM 必须放入同一个 activation 请求
CLAS/INTF 激活报 Internal error 8	用了 programs URI 而非 OO URI	`deploy_clas.js`/`deploy_intf.js` 使用正确的 `/oo/classes/` `/oo/interfaces/` URI
FM 创建报 400 "期望的是元素 fmodules"	命名空间错误（用了 `groups` 而非 `fmodules`）	FM XML 必须用 `http://www.sap.com/adt/functions/fmodules`
激活报错对象名为 "unknown"	错误解析器无法从响应中提取对象名	查看完整 XML 响应中的 `objDescr`/`objName` 属性
Syntax check 报 405	此系统不支持独立语法检查	依赖激活时验证语法
`freestyle` 返回 400	系统不支持该端点	改用 `--table <T>` 走 `ddic` 端点

迁移到其他环境

复制 Skill 目录到目标仓库的 .opencode/skills/sap-report-automation-workflow/。首次触发时代理按 S0 自动验证 RFC 环境、引导用户创建 .env。需用户安装 Node.js ≥ 18 + NW RFC SDK。

INCLUDE 部署缺陷与 FUGR/FM 支持

→ docs/rfc-adt-bridge.md

name

sap-report-automation-workflow

description

SAP ABAP 开发对象自动化工作流（FS → 元数据 → 设计文档 → 代码 → 激活）

支持对象类型（S2 确认）：REPORT、CLAS、FUGR（含 Function Module）、INTF、PROG/I（Include）。

连接架构

# 查询链路
AI Agent → Bash → node scripts/rfc_client.js → node-rfc → SADT_REST_RFC_ENDPOINT → SAP

# 部署链路（按对象类型分发）
AI Agent → Bash → node scripts/deploy_report.js           → node-rfc → SADT_REST_RFC_ENDPOINT → SAP
                     node scripts/deploy_report_include.js
                     node scripts/deploy_fugr.js
                     node scripts/deploy_clas.js
                     node scripts/deploy_intf.js

阶段间强引用（元数据驱动；禁止凭语感写 Open SQL）

后续阶段必须显式引用前序产物，禁止凭记忆拼字段名/表名/JOIN 条件：

消费方	必须参照的输入	规则
`docs/tech-design.md`	`spec/functional-spec-ai.md` + `metadata/tables/*.json`	每个物理字段须在元数据中可核对
ABAP（Open SQL、内表）	`docs/tech-design.md` 的「字段契约」+ `metadata/tables/*.json`	SELECT/JOIN/WHERE 字段名必须来自契约或元数据
ALV 列 / 内表组件	同上	列名与契约一致，计算列在契约中写清公式

字段契约（S6 技术文档中必写）：docs/tech-design.md 中至少包含：

逻辑项	表名	字段名	元数据文件
…	BKPF	BUKRS	output//metadata/tables/BKPF.json

代理自主执行协议

代理在同一任务内按阶段 0→1→2→3→4→5→6→7→8→9→10→11 顺序自动跑完，仅在缺关键输入、SAP 不可达、或达重试上限时停顿。

硬门禁（除非用户明确说跳过）： 0. test_rfc.js 未通过 → 禁止进入 S1。代理必须指导用户完成 NW RFC SDK 安装和 .env 配置。

无 functional-spec-ai.md → 禁止写 ABAP、禁止部署。
S2 对象名未确认（或已存在未覆盖授权） → 禁止进入 S3。
无 metadata JSON 落盘 → 禁止进入 S4。
fs-ddic-verification.md 有语义偏差未修正 → 禁止进入 S6。
无 tech-design.md（含字段契约+选择屏幕角色分析）→ 禁止进入 S9。
deployment-config.md 未生成（包/请求号/模板未明确） → 禁止进入 S10。 9-10. 必须实际调用 SAP，失败时自动修错循环直至成功或达上限。

Preflight Gate：任何 SAP 写操作前，必须确认 stage-gate.md 中 S0→S8 全部为 yes。禁止在门禁未通过时调用任何部署脚本或写操作。

受阻时先查 troubleshooting.md，按"预判→预防→应对"处理。

S0：RFC 环境验证与连接

代理自动执行诊断，仅凭据和系统级依赖缺时打断用户。

0.1 环境探测

node scripts/test_rfc.js

通过 → 继续。失败 → 按输出分类诊断（DLL 缺失 / 环境变量 / 网络不通），指导用户修复。

唯一允许打断用户的：Node.js 安装、NW RFC SDK 安装、SAP 连接凭据。

0.2 `.env` 配置（6 个字段）

字段	必需	说明
`SAP_URL`	是	SAP 主机地址，如 `http://<host>:<port>`
`SAP_CLIENT`	是	客户端号（如 `200`）
`SAP_SYSNR`	是	RFC 实例号——不可依赖端口推导
`SAP_USERNAME`	是	开发账号
`SAP_PASSWORD`	是	密码
`SAP_ROUTER`	否	Router 字符串（内网穿透）

双系统配置：开发系统 .env，数据系统 .env.data。二者 SAP_SYSNR 通常相同，但 SAP_CLIENT 不同。

代理写入配置文件后不启动任何后台进程——rfc_client.js 每次执行时自动连接、执行、断开。

0.3 连通验证

# 一键双系统检测
node scripts/rfc_dual_check.js

两个系统都 "ok": true → 已就绪。任一失败 → 按 troubleshooting.md §4 排查。记录到 stage-gate.md 的 S0=connection-ok。

0.4 双系统架构（硬约束）

配置文件	用途	SAP_CLIENT
`.env`	开发：创建/修改/激活/语法检查	由用户指定（如 200）
`.env.data`	数据：runQuery/tableContents	由用户指定（如 300）

三条死线：

禁止用开发系统查业务表数据 → 开发机可能无数据
禁止把 .env 客户端改成数据系统客户端 → 部署会落到数据机
禁止因查不到数据而反复重写代码 → 先用 --env=.env.data 确认数据存在

0.5 权限前置探测

# 开发权限探针
node scripts/rfc_client.js --sql "SELECT COUNT(*) AS CNT FROM TADIR WHERE PGMID EQ 'R3TR' AND OBJECT EQ 'PROG'" --table TADIR

# 包权限探针（用户提供包名后）
node scripts/rfc_client.js --search "<包名>" --type DEVC

记录到 stage-gate.md 的 S0=permission-check。

0.6 ABAP 版本探测（写代码前强制）

在 S9 写 ABAP 之前，必须知道目标开发系统的 ABAP release，否则无法判断内联声明、VALUE、CORRESPONDING 等新语法是否可用。

# 默认读取 .env
node scripts/detect_abap_version.js

# 数据系统（如需要）
node scripts/detect_abap_version.js --env=.env.data

输出示例：

{
  "status": "success",
  "system": {
    "sysid": "DEV",
    "database": "HDB",
    "sapReleaseRaw": "7400",
    "sapRelease": 740
  },
  "versionTier": "s4hana_early",
  "allowedSyntax": ["🔵", "🟢"],
  "notes": "ECC 6.0 EHP7/EHP8（ABAP 7.40）：仅可用 🔵 与 🟢 语法"
}

处理规则：

sapRelease 为 null 或 < 700 → 按最严格 ecc_legacy 处理，只允许 🔵 语法
allowedSyntax 写入 stage-gate.md 的 S0=abap-version
S9 写代码时，只准使用 allowedSyntax 内图标标注的语法；遇到新语法需求必须先确认版本

记录到 stage-gate.md 的 S0=abap-version。

0.7 切换 SAP 系统

用户说「换系统/切客户端/改密码」→ 更新对应 .env 文件 → 重新执行 0.3 连通验证。无需重启任何进程。

S1：获取 FS → 规范化为 AI 可读的功能文件

1.0 获取 FS

代理一次性询问 FS 来源：A.粘贴文本 / B.提供文件路径(.docx/.txt/.md) / C.文件夹 / D.口头描述。

若用户提供 .docx 文件，用 extract-docx.js 提取文本：

node scripts/extract-docx.js "<路径>"

1.1 规范化 FS

S1 门禁：FS 中每个表名可在 DDIC 中查到；SPRAS 字段标注为 LANG(1) 不得写 'ZH'；输出列无 TBD。

S2：对象名确认与 SAP 存在性检查

确定对象名与类型

对象类型	ADT 码	命名约定	示例
可执行报表	`PROG/P`	`ZSAP_xxx` / `ZFI_xxx`	`ZSAP_FI086`
Include	`PROG/I`	`ZSAP_xxxT01` / `ZSAP_xxxF01`	`ZSAP_FI086T01`
全局类	`CLAS`	`ZCL_xxx`	`ZCL_FI_UTILITY`
函数组	`FUGR`	`ZFG_xxx`	`ZFG_FI_TOOLS`
接口	`INTF`	`ZIF_xxx`	`ZIF_FI_DATA_ACCESS`

2.2 SAP 存在性检查

# 查主对象 + 所有 Include
node scripts/rfc_client.js --search "ZSAP_FI086"
node scripts/rfc_client.js --search "ZSAP_FI086T01"

已存在 → 立即停止，报告对象名/类型，让用户重新提供或书面确认覆盖。禁止代理擅自改对象名或跳过。均不存在 → [OK]，继续 S3。

S2 门禁：全部对象名在 SAP 中均不存在，或用户已书面确认覆盖。

S3：透明表 DDIC 元数据

Z 表也必须拉 DDIC

首选封装脚本（一键完成取数 + JSON 落盘）：

node scripts/rfc_fetch_ddic.js --env=.env.data <TABNAME> output/<program>/metadata/tables/

备选手工路径（脚本不可用时）：

node scripts/rfc_client.js --env=.env.data --rows=2000 \
  --sql "SELECT FIELDNAME, POSITION, KEYFLAG, ROLLNAME, DATATYPE, LENG, DECIMALS FROM DD03L WHERE TABNAME EQ '<T>' ORDER BY POSITION" \
  --table DD03L

每表串行拉取
fetched_count 为 0 时自动重试最多 3 次
每表独立落盘 metadata/tables/<TABNAME>.json
失败切备选路径（--source → 兜底 RFC），三种均尝试完毕才记入 _errors.md

S4：FS → DDIC 字段交叉验证（强制）

硬约束：业务人员写 FS 时可能写错字段名或误解字段语义。metadata JSON 落盘后必须立即逐字段对照验证，禁止盲目信任 FS。

4.1 验证内容

对 functional-spec-ai.md 中引用的每个 表.字段：

存在性：字段在 DD03L 中确实存在
类型：数据类型匹配预期使用方式
语义：字段的实际含义与 FS 描述一致（重点：SELECT-OPTIONS 的字段是真正的过滤字段还是参考字段）
字面值陷阱：SPRAS=LANG(1) 强制 '1' 非 'ZH'；DATS 格式 'YYYYMMDD'
符号约定（新增）：金额列需逐列确认 FS 中定义的是绝对值还是带符号值——SAP 中 DRCRK='H' 的金额通常存为负数，若 FS 按绝对值描述则代码需额外处理。验证方法：取一行真实数据，检查 DRCRK='S' vs 'H' 的实际符号，与 FS 描述对照，在 tech-design.md 字段契约中标注每列的符号来源

4.2 验证输出

落盘 spec/fs-ddic-verification.md：每表每字段一行，标注存在性+类型+语义审查结果。不通过项标注为 TBD，等用户澄清后再进入 S6。

S4 门禁：全部 FS 引用字段在 DDIC 中存在；语义偏差已标注并修正（或用户确认）；fs-ddic-verification.md 已落盘。

S5：性能预估

对主驱动表执行 COUNT：

node scripts/rfc_client.js --env=.env.data \
  --sql "SELECT COUNT(*) AS CNT FROM <主表> WHERE <最严格条件>" --table <主表>

< 10,000 → 全量 ALV
10,000 ~ 1,000,000 → 建议分页
> 1,000,000 → 必须后台执行

结果写入 performance-estimate.md。

S5 门禁：每张表有 metadata JSON 且 matched=true；performance-estimate.md 已生成；多期金额表已通过数据系统取一行真实数据确认分布方式。

S6：技术文档 `docs/tech-design.md`

选择屏幕字段角色分析（强制）

硬约束：每个选择屏幕字段必须先确定为四角色之一再决定使用方式，禁止默认全部塞入 WHERE。

角色	说明	示例	使用方式
WHERE 过滤	直接过滤主表行	P_RYEAR、S_RACCT	放入 FAGLFLEXT SELECT 的 WHERE 子句
映射键	需经中间表转换	P_BUKRS	先查 ZSAP_BUKRS 得到 RBUKRS，再用于 WHERE
计算参数	不过滤行，决定聚合范围	S_RPMAX	不出现于 WHERE；决定 HSL{start}~HSL{end} 索引范围
显示控制	不影响取数，控制输出	P_FORCUR	控制 ALV 列 visible/technical

S7：FS 对齐审查 `docs/fs-coverage.md`

FS 逻辑项	输出字段	契约字段（表.字段）	元数据文件	代码落点	状态

FS 中每个输出列/选择条件都必须出现一行。S10 前做反查：从最终代码回填确认无遗漏。

S8：部署配置 `docs/deployment-config.md`

确认三项并落盘：

开发包：用户提供或默认 $TMP（本地包无需传输请求）
传输请求：仅非 $TMP 时需要
模板选择：优先 templates/reference/<对象名>/，其次默认模板，无模板用 quickref 骨架

必须按如下固定格式写入（部署脚本通过正则解析）：

| 程序名 | ZTESTXXX |
| 目标包 | $TMP |
| 传输请求 | — |
| 程序描述 | <程序功能描述> |

部署脚本用 | 目标包 | ([^|]+) | 正则提取包名。不用此格式会报 Package name not found。`

S8 门禁：deployment-config.md 已生成，包/请求号/模板状态明确。

S9：按类型生成代码

语法硬约束：以 abap-syntax-quickref.md 为参考，禁止凭记忆写语法。

对象类型分发

类型	代码文件	部署脚本	参考模板
REPORT	主程序 + T01/SEL/F01 分层	`deploy_report_include.js`	`templates/reference/<模板程序名>/`
REPORT（无 INCLUDE）	主程序单个文件	`deploy_report.js`	quickref §1–6
CLAS	`<名>.clas.abap`（单文件）	`deploy_clas.js`	quickref §11
INTF	`<名>.intf.abap`	`deploy_intf.js`	quickref §12
FUGR	`<FM名>.fm.abap`（每 FM 一个文件）	`deploy_fugr.js`	quickref §13

REPORT 生成

强制先读模板：打开 templates/reference/report/ 下全部 4 个文件，逐行理解其结构后再写代码。禁止跳过后直接写。
打开 tech-design.md → metadata/tables/*.json → abap-syntax-quickref.md
INCLUDE 分层强约束：主程序 + T01/SEL/F01 保持模板结构
生成前先写 template-mapping.md
反模式自检通过（见 S9 通用反模式自检）

GUI Status 强制规则（CL_SALV_TABLE 专用，已激活旧对象可能用sy-repid+S1000，不要模仿）：

CL_SALV_TABLE 的 set_screen_status 必须用 report = 'SAPLKKBL'，绝不能是 sy-repid
必须在 display() 前调用，带 pfstatus = 'STANDARD' 和 set_functions = gr_alv->c_functions_all

pfstatus 'STANDARD' 是 SAPLKKBL 自带的 GUI 状态；不要使用自定义 'S1000'，它仅适用于 sy-repid 自定义状态。

禁止参考 output/ 下旧对象：已有项目可能使用旧版单文件结构，不是本技能规定的标准。必须严格按模板 templates/reference/report/ 分层结构生成。

CLASS/INTF/FUGR 生成

通用反模式自检（6 轮，强制）

代码写入后、部署前，逐轮检查（详见 abap-syntax-quickref.md §14）：

第零轮 — DDIC 字面值：扫描所有字面值对照 metadata LENG。重点陷阱：SPRAS(LANG, LENG=1) 必须用 '1' 非 'ZH'。

第零轮(2) — 模板代码风格对齐：逐项对照 templates/reference/report/(其他程序类型，对应不同文件夹) 检查：

✅ GUI Status：report = 'SAPLKKBL'（不是 sy-repid），pfstatus = 'STANDARD'（不是 'S1000'），在 display() 前调用
✅ INCLUDE 分层：主程序仅 REPORT+INCLUDE+事件块，FORM 在 F01 中
✅ 列格式化：用 set_column 辅助 FORM（非内联 CAST cl_salv_column_table）
✅ FIELD-SYMBOLS 不同 FORM 不同名
✅ 主程序不含除 REPORT/INCLUDE/事件块以外的代码

第一~五轮：DB → WHERE → 内表 → 控制流 → 其他规范（无 Hard Coding/有 AUTHORITY-CHECK）。

任一轮未通过 → 修正源码后再继续。

选择屏幕文本元素处理

选择屏幕参数/选择项的中文标签通过以下两种运行时方法设置，无需 SE32 文本元素。

方法一：直接赋值（单参数，最简单）

AT SELECTION-SCREEN OUTPUT.
  %_p_param_%_app_%-text = '参数标签'.
  %_s_selopt_%_app_%-text = '选择项标签'.

格式：%_<名>_%_app_%-text，其中 <名> 为 PARAMETERS 或 SELECT-OPTIONS 的名称（大写）。

方法二：SELECTION_TEXTS_MODIFY FM（多参数，推荐）

FORM modify_sel_texts.
  DATA lt_sel TYPE TABLE OF rsseltexts.
  DATA ls_sel TYPE rsseltexts.

  ls_sel-name = 'P_BUKRS'.
  ls_sel-kind = 'P'.           " P=PARAMETERS, S=SELECT-OPTIONS
  ls_sel-text = '公司代码'.
  APPEND ls_sel TO lt_sel[].

  CALL FUNCTION 'SELECTION_TEXTS_MODIFY'
    EXPORTING
      program                     = sy-repid
    TABLES
      seltexts                    = lt_sel
    EXCEPTIONS
      program_not_found           = 1
      program_cannot_be_generated = 2
      OTHERS                      = 3.
  IF sy-subrc <> 0.
    MESSAGE ID sy-msgid TYPE sy-msgty NUMBER sy-msgno
            WITH sy-msgv1 sy-msgv2 sy-msgv3 sy-msgv4.
  ENDIF.
ENDFORM.

调用（在主程序的 AT SELECTION-SCREEN OUTPUT 中）：

AT SELECTION-SCREEN OUTPUT.
  PERFORM modify_sel_texts.

约束

ls_sel-name 必须与 PARAMETERS / SELECT-OPTIONS 声明名大写完全一致
ls_sel-kind：'P' = PARAMETERS，'S' = SELECT-OPTIONS
ADT 部署优先用方法一（%_xxx_%_app_%-text）：方法二将 FORM 放在 INCLUDE 中，更新部署时 ADT 激活可能因 INCLUDE 解析先后顺序找不到 FORM。方法一直接在主程序 AT SELECTION-SCREEN OUTPUT 中赋值，无此问题
SELECTION-SCREEN BLOCK 的 TITLE TEXT-xxx 不适用上述两种方法；用 WITH FRAME 不加 TITLE 即可

阶段门禁产物验证

每阶段完成落盘 stage-gate.md：

S0=connection-ok: yes/no
S0=permission-check: yes/no
S0=abap-version: yes/no
S1=functional-spec-ready: yes/no
S2=object-name-confirmed: yes/no
S3=metadata-ready: yes/no
S4=fs-ddic-verified: yes/no
S5=performance-estimate-ready: yes/no
S6=tech-design-ready: yes/no
S7=fs-coverage-ready: yes/no
S8=deployment-config-ready: yes/no
S9=code-generated: yes/no
S10=activated: yes/no
S11=smoke-test-passed: yes/no

门禁通过后由用户决定是否 git add + git commit，格式建议：[SAP-WF] 阶段X: 简述产物。代理不自动执行 git 提交。

S10：部署与激活

2026-07 重构：部署脚本按对象类型拆分为 5 个独立脚本，每个有可重复的入参出参示例。deploy_rfc.js 保留为兼容入口（REPORT + 固定 INCLUDE 结构）。

部署脚本选型（按对象类型分发）

对象类型	脚本	源码文件约定
REPORT（无 INCLUDE）	`node scripts/deploy_report.js <名>`	`output/<名>/abap/<名>.abap`
REPORT + INCLUDE	`node scripts/deploy_report_include.js <名>`	主程序 + 从源码自动发现 INCLUDE 名
FUGR + FM	`node scripts/deploy_fugr.js <名>`	`output/<名>/abap/<FM名>.fm.abap`
CLAS	`node scripts/deploy_clas.js <名>`	`output/<名>/abap/<名>.clas.abap`
INTF	`node scripts/deploy_intf.js <名>`	`output/<名>/abap/<名>.intf.abap`
REPORT（固定 T01/SEL/F01/O01）	`node scripts/deploy_rfc.js <名>`	兼容旧模板

部署前复核

S2 的 --search 结果已记录，程序名一致
stage-gate.md 中 S8=yes
deployment-config.md 已按固定表格格式生成

标准流程（所有脚本通用）

每个脚本内部执行：创建对象 → Lock → 上传源码 → Unlock → 激活 → 验证版本。

关键行为规则（2026-07 实战验证）：

规则	说明
INCLUDE 自动发现	`deploy_report_include.js` 从主程序源码 `INCLUDE xxx.` 指令提取 INCLUDE 名，不限死 T01/SEL/F01
FM 必须入激活列表	只激活 FUGR 不会激活其 FM。`deploy_fugr.js` 自动把 FUGR + 所有 FM 放入一个 activation 请求
CLAS/INTF 走 OO URI	CLAS 激活 URI 是 `/oo/classes/`，INTF 是 `/oo/interfaces/`，不能用 `activateObjects()` 的 programs URI
已存在 = 405 或 409	此系统"已存在"返回 405，不是标准 409。所有新脚本兼容两种
激活响应体可能为空	HTTP 200 + 空 body = 激活成功（此系统行为）
Syntax check 405	此系统不支持独立语法检查，激活时验证语法

部署后验证（所有脚本自动执行）

每个脚本激活后自动 GET 对象元数据，提取 adtcore:version 字段确认 active。结果以 JSON 输出：

{"status":"success","objects":[{"name":"ZTEST006","type":"PROG/P","version":"active"},...],"errors":[]}

锁管理

Lock Handle 持久化到 .locks/<name>.json。残留锁用 scripts/release_locks.js 清理。

S10 门禁：部署成功，所有对象 version=active。

S11：冒烟测试（激活后强制，不可跳过）

执行范式强制参照：smoke-test-procedure.md——含入参矩阵、手工计算步骤、逐字段比对脚本模板。

硬门禁（代理不得自行跳过）

禁止在 ZREPORT_EXEC_VERIFY FM 不存在或不返回 EV_SUCCESS='X' 时标记 S11=yes
禁止仅跑一次 verify_report.js 看返回码即通过
禁止 smoke-test.md 的数值来源于推测/人工伪造——所有数必须来自 verify_report.js 真实返回的 EV_DATA_JSON；伪造数据是严重违规，发现后必须重写并道歉
禁止源表数据全零时不标注"数据全零，计算逻辑待补充验证"即通过
禁止仅比对金额列；描述列（TXT50/ZFZHS/ZFZTX/ZYJKM）也必须逐列比对
必须≥2 个不同公司代码、≥3 组参数组合、≥8 个金额列逐列 0.01 容差匹配
smoke-test.md 落盘路径为 output/<程序>/smoke-test.md（非 docs/ 子目录）

数据抽样（fetch_table.js 统一入口——DDIC 端点，WHERE 可靠）

# 通用取数（走 DDIC 端点 /sap/bc/adt/datapreview/ddic，WHERE 可靠过滤）
node scripts/fetch_table.js --table=FAGLFLEXT \
  --fields=RYEAR,RBUKRS,RACCT,RPMAX,DRCRK,HSLVT,HSL01,HSL02,HSL03,HSL04 \
  --where="RYEAR = '2026' AND RBUKRS = '80K0' AND RACCT = '1002000001'" \
  --rows=50

# data_sampler.js 已重构为 fetch_table.js 的薄包装，参数格式兼容
node scripts/data_sampler.js "--table=FAGLFLEXT" "--where=RYEAR = '2026'" "--fields=RACCT,DRCRK" "--rows=50"

入参：--table / --where / --fields / --rows / --env 出参：JSON { table, where, rowCount, columns, rows, _validation: { passed, failures[] } }

硬约束：取数后必须检查 _validation.passed，任意字段不匹配 WHERE 条件则立即阻断。禁止在取数失败/过滤错误时继续后续步骤。

关键维度选择（如适用）

若报表涉及公司代码（BUKRS）等维度，需先确定有效值：

# 1. 找有数据的关键维度值
node scripts/data_sampler.js "--table=FAGLFLEXT" "--where=RYEAR = '2026'" "--rows=5"
# 2. 查映射表（如 ZSAP_BUKRS 的 ZFGS/ZZGS）
node scripts/data_sampler.js "--table=ZSAP_BUKRS" "--fields=BUKRS,ZFGS,ZZGS" "--rows=100"
# 3. 确定有效值（ZFGS=''→BUKRS; ZFGS≠''→ZZGS）
# 4. 验证有效值在主表中有数据

报表执行校验

node scripts/verify_report.js <程序名> P_xxx=<值> "S_xxx=低-高,低-高"

前提：ZREPORT_EXEC_VERIFY FM 已在 SAP 开发系统部署。 verify_report.js 调用 FM → SUBMIT 报表 → 捕获 SALV 数据 → 返回 JSON。

11.4 verify_report.js 失败排查（实战教训）

症状	最可能根因	检查方法
`An exception has occurred that was not caught`	报表内部 ABAP dump：AUTHORITY-CHECK 用错字段、消息 TYPE 'E'、数据转换错	检查 F01 逻辑，特别是 authority_check 是否传了正确字段
`Fill all required fields` / 参数类 404	ZREPORT_EXEC_VERIFY 的 IT_RSPARAMS 结构不对	直接 node-rfc 传参测试（跳过 verify_report.js 参数解析层）
`ZREPORT_EXEC_VERIFY` FM 404	FM 未部署	检查 docs/ 下部署记录
RFCEXEC 相关错误	网络/路由/NW-RFC-SDK	先跑 `node scripts/test_rfc.js` 确认客户端连通，再跑 `node scripts/test_rfc.js .env.data` 确认数据系统连通

关键原则：先最小化——用直接 node-rfc 调用 FM 排除脚本层问题，再逐层向上排查。

逐字段比对（例子：8 金额列 + 5 描述列）

金额列: ZQCJF, ZQCDF, ZBQJF, ZBQDF, ZBNJF, ZBNDF, ZQMJF, ZQMDF (×外币列 if P_FORCUR=X)
描述列: ZYJKM, RACCT, TXT50, ZFZHS, ZFZTX

每列必须：
  - 金额列: |程序值 - 源表手工计算值| < 0.01
  - 描述列: 程序值 = 单独查 SKAT/SKA1/TFKBT 的值

ALV 列核对

静态分析源码，确认列名/列数与 fs-coverage.md 一致。外部币列受 P_FORCUR 控制。

S11 门禁：

三步不可跳过（源表采样 → 手工预期 → verify_report.js 多组比对）
≥2 单选、≥3 多选参数组合 SUCCESS
8 金额列 + 5 描述列逐列比对通过
全零数据必须检查是否程序出问题
output/<程序>/smoke-test.md 已按 smoke-test-procedure.md 模板生成

全工作流 SAP 操作速查

阶段	操作	命令
S0	环境诊断	`node scripts/test_rfc.js`
S0	双系统连通	`node scripts/rfc_dual_check.js`
S0	权限探测	`node scripts/rfc_client.js --sql "SELECT COUNT(*) AS CNT FROM TADIR WHERE PGMID EQ 'R3TR'" --table TADIR`
S0	ABAP 版本探测	`node scripts/detect_abap_version.js [--env=.env.data]`
S1	提取 DOCX	`node scripts/extract-docx.js "<路径>"`
S2	查对象名	`node scripts/rfc_client.js --search "<对象名>"`
S3	拉 DD03L	`node scripts/rfc_fetch_ddic.js --env=.env.data <TABNAME> output/<prog>/metadata/tables/`
S4	主表 COUNT	`node scripts/rfc_client.js --env=.env.data --sql "SELECT COUNT(*) AS CNT FROM <主表>" --table <主表>`
S8	验证包	`node scripts/rfc_client.js --search "<包名>" --type DEVC`
S10	部署 REPORT（单文件）	`node scripts/deploy_report.js <程序名>`
S10	部署 REPORT+INCLUDE	`node scripts/deploy_report_include.js <程序名>`
S10	部署 FUGR+FM	`node scripts/deploy_fugr.js <函数组名>`
S10	部署 CLAS	`node scripts/deploy_clas.js <类名>`
S10	部署 INTF	`node scripts/deploy_intf.js <接口名>`
S10	部署（兼容旧模板）	`node scripts/deploy_rfc.js <程序名>`
S11	取数（DDIC 端点）	`node scripts/fetch_table.js --table=<T> --where="<cond>" --fields=<f> --rows=<n>`
S11	数据采样（兼容）	`node scripts/data_sampler.js "--table=<T>" "--where=<cond>" "--rows=100"`

增量更新机制

FS 变更时禁止默认全量重跑。按变更类型选择恢复起点：

变更类型	恢复起点	需重新执行
纯输出列调整	S7	7, 9, 10, 11
新增/替换透明表	S3	3, 4, 5, 6, 7, 9, 10, 11
选择屏条件变更	S6	6, 5(重估), 7, 9, 10, 11
模板/INCLUDE 结构调整	S9	9, 10, 11

规则：已有 metadata JSON 不得删除重建；先拉基线再应用变更；增量更新后在 stage-gate.md 追加版本号。

执行检查清单

- [ ] S0: test_rfc.js 通过，双系统 --discovery 通过，权限前置探测通过，ABAP 版本已探测并记录 allowedSyntax
- [ ] S1: functional-spec-ai.md 结构完整，表名大写
- [ ] S2: --search 确认全部对象名在 SAP 中不存在（或用户书面确认覆盖）
- [ ] S3: 每张表有 metadata JSON (matched=true)，_errors.md 完整
- [ ] S4: fs-ddic-verification.md 已生成，全部字段存在+语义审查通过
- [ ] S5: performance-estimate.md 已生成
- [ ] S5: 多期金额表已通过数据系统取真实数据确认分布
- [ ] S6: tech-design.md 含字段契约 + 性能设计
- [ ] S7: fs-coverage.md 覆盖 FS 全量字段
- [ ] S8: deployment-config.md 已生成（包/请求号/模板明确）
- [ ] S9: ASSIGN COMPONENT 字段名对齐 + sy-subrc 检查 + 反模式自检通过 + 选择屏幕文本已设置
- [ ] S9: 源码结构与 template-mapping.md 一致
- [ ] S10: 对应类型部署脚本成功，激活无错误
- [ ] S11: ZREPORT_EXEC_VERIFY FM 已确认存在
- [ ] S11: 关键维度数据已验证存在（如公司代码等）
- [ ] S11: 源表手工聚合 vs verify_report.js 输出逐列比对通过
- [ ] S11: ≥3 组参数组合 SUCCESS
- [ ] S11: output/<程序>/smoke-test.md 按 smoke-test-procedure.md 模板生成
- [ ] 每阶段 gate 通过后 git commit（推荐）

附录：关键 RFC ADT 端点与故障排查

常用端点

操作	方法	URI
Discovery	GET	`/sap/bc/adt/discovery`
搜索对象	GET	`/sap/bc/adt/repository/informationsystem/search?operation=quickSearch&query=<q>&maxResults=<n>`
SQL 查询（指定表）	POST	`/sap/bc/adt/datapreview/ddic?rowNumber=<n>&ddicEntityName=<T>`
SQL 查询（自由）	POST	`/sap/bc/adt/datapreview/freestyle?rowNumber=<n>`
读取源码	GET	`/sap/bc/adt/programs/programs/{name}/source/main`
创建程序	POST	`/sap/bc/adt/programs/programs`
创建 Include	POST	`/sap/bc/adt/programs/includes`
创建类	POST	`/sap/bc/adt/oo/classes`
创建接口	POST	`/sap/bc/adt/oo/interfaces`
创建函数组	POST	`/sap/bc/adt/functions/groups`
创建 FM	POST	`.../fmodules`（命名空间 `fmodules`，非 `groups`）
Lock	POST	`{objectUri}?_action=LOCK&accessMode=MODIFY`
激活	POST	`/sap/bc/adt/activation?method=activate&preauditRequested=false`

对象类型映射

ADT 码	URI 前缀	命名约定
`PROG/P`	`/sap/bc/adt/programs/programs/`	`ZSAP_xxx`
`PROG/I`	`/sap/bc/adt/programs/includes/`	`ZSAP_xxxT01`
`CLAS`	`/sap/bc/adt/oo/classes/`	`ZCL_xxx`
`INTF`	`/sap/bc/adt/oo/interfaces/`	`ZIF_xxx`
`FUGR`	`/sap/bc/adt/functions/groups/`	`ZFG_xxx`

故障排查速查

症状	根因	解决
`test_rfc.js` DLL 加载失败	SAPNWRFC_HOME/PATH 未设	设置 Windows 系统环境变量，完全重启终端
RFC 连接超时	Router/防火墙/端口	检查 VPN，核对 SAP_ROUTER
创建报 409	程序已存在	必须问用户，禁止自动跳过
创建报 405（非 409）	此系统"已存在"返回 405 而非 409	脚本兼容处理：405+body 含 AlreadyExists
激活 HTTP 200 但空 body	此系统激活成功不返回 XML	正常行为。部署后 GET 元数据确认 `version="active"`
激活 HTTP 200 但 FM 仍 inactive	只激活了 FUGR 没激活 FM	FM 必须放入同一个 activation 请求
CLAS/INTF 激活报 Internal error 8	用了 programs URI 而非 OO URI	`deploy_clas.js`/`deploy_intf.js` 使用正确的 `/oo/classes/` `/oo/interfaces/` URI
FM 创建报 400 "期望的是元素 fmodules"	命名空间错误（用了 `groups` 而非 `fmodules`）	FM XML 必须用 `http://www.sap.com/adt/functions/fmodules`
激活报错对象名为 "unknown"	错误解析器无法从响应中提取对象名	查看完整 XML 响应中的 `objDescr`/`objName` 属性
Syntax check 报 405	此系统不支持独立语法检查	依赖激活时验证语法
`freestyle` 返回 400	系统不支持该端点	改用 `--table <T>` 走 `ddic` 端点

迁移到其他环境

INCLUDE 部署缺陷与 FUGR/FM 支持

→ docs/rfc-adt-bridge.md

sap-report-automation-workflow

Datos de origen

Opciones de instalación

Revisa los archivos de origen

SAP ABAP 开发对象自动化工作流（FS → 元数据 → 设计文档 → 代码 → 激活）

连接架构

阶段间强引用（元数据驱动；禁止凭语感写 Open SQL）

代理自主执行协议

S0：RFC 环境验证与连接

0.1 环境探测

0.2 .env 配置（6 个字段）

0.3 连通验证

0.4 双系统架构（硬约束）

0.5 权限前置探测

0.6 ABAP 版本探测（写代码前强制）

0.7 切换 SAP 系统

S1：获取 FS → 规范化为 AI 可读的功能文件

1.0 获取 FS

1.1 规范化 FS

S2：对象名确认与 SAP 存在性检查

确定对象名与类型

2.2 SAP 存在性检查

S3：透明表 DDIC 元数据

Z 表也必须拉 DDIC

S4：FS → DDIC 字段交叉验证（强制）

4.1 验证内容

4.2 验证输出

S5：性能预估

S6：技术文档 docs/tech-design.md

选择屏幕字段角色分析（强制）

S7：FS 对齐审查 docs/fs-coverage.md

S8：部署配置 docs/deployment-config.md

S9：按类型生成代码

对象类型分发

REPORT 生成

CLASS/INTF/FUGR 生成

通用反模式自检（6 轮，强制）

选择屏幕文本元素处理

方法一：直接赋值（单参数，最简单）

方法二：SELECTION_TEXTS_MODIFY FM（多参数，推荐）

约束

阶段门禁产物验证

S10：部署与激活

部署脚本选型（按对象类型分发）

部署前复核

标准流程（所有脚本通用）

部署后验证（所有脚本自动执行）

锁管理

S11：冒烟测试（激活后强制，不可跳过）

硬门禁（代理不得自行跳过）

数据抽样（fetch_table.js 统一入口——DDIC 端点，WHERE 可靠）

关键维度选择（如适用）

报表执行校验

11.4 verify_report.js 失败排查（实战教训）

逐字段比对（例子：8 金额列 + 5 描述列）

ALV 列核对

全工作流 SAP 操作速查

增量更新机制

执行检查清单

延伸阅读

附录：关键 RFC ADT 端点与故障排查

常用端点

对象类型映射

故障排查速查

迁移到其他环境

INCLUDE 部署缺陷与 FUGR/FM 支持

SAP ABAP 开发对象自动化工作流（FS → 元数据 → 设计文档 → 代码 → 激活）

连接架构

阶段间强引用（元数据驱动；禁止凭语感写 Open SQL）

代理自主执行协议

S0：RFC 环境验证与连接

0.1 环境探测

0.2 .env 配置（6 个字段）

0.3 连通验证

0.4 双系统架构（硬约束）

0.5 权限前置探测

0.6 ABAP 版本探测（写代码前强制）

0.7 切换 SAP 系统

S1：获取 FS → 规范化为 AI 可读的功能文件

1.0 获取 FS

0.2 `.env` 配置（6 个字段）

S6：技术文档 `docs/tech-design.md`

S7：FS 对齐审查 `docs/fs-coverage.md`

S8：部署配置 `docs/deployment-config.md`

0.2 `.env` 配置（6 个字段）

S6：技术文档 `docs/tech-design.md`

S7：FS 对齐审查 `docs/fs-coverage.md`

S8：部署配置 `docs/deployment-config.md`