sap-object-documenter

SAP Object Documenter

为自定义 ABAP 对象生成稳定的、限定于程序包范围的文档——按风格（Classic / Modern / Mixed）分类，概述用途和依赖项，并输出适用于代码仓库 Wiki 或入职文档的 Markdown。

此技能与 explain-abap-code 互为补充，后者以交互方式解释单个对象。需要一次为多个对象编写文档时，请使用此技能——例如，在入职期间为 docs/ 目录创建初始文档，或在团队交接前生成知识传递材料。

智能默认值（静默应用，切勿询问）

设置	默认值	理由
包含范围	Z*、Y*、客户命名空间	仅包含客户代码
深度	1（仅直接依赖项）	保持文档易读，避免被传递依赖图淹没
风格分类	是	可免费获得参考信息——只需调用 SAPLint
每个对象的章节长度	约 30–60 行 Markdown	内容足够实用，又不会长到无人阅读
输出格式	Markdown 文件	可移植，适用于任何 Wiki

输入

用户提供以下其中一项：

• 程序包（例如 Z_SALES_EXTENSIONS）——记录其中每个自定义对象
• 对象列表——逗号分隔（例如 ZCL_SALES_HANDLER, ZR_POSTING_JOB）
• 类型 + 前缀——例如“记录所有 Z* 类”→运行 SAPSearch(query="Z*", objectType="CLAS")

还可选提供：

• 输出路径——默认：docs/custom-code/<package_or_group>.md
• 单个文件或每个对象一个文件——默认：一个文件，包含各对象的章节；若对象超过 30 个，则每个对象单独一个文件

如果范围会产生超过 100 个对象，请停止并要求用户缩小范围——没人阅读的文档比没有文档更糟。

步骤 1：枚举范围

1a. 程序包路径

SAPRead(type="DEVC", name="<package>")

1b. 对象列表路径

解析每个对象：

SAPSearch(query="<name>")

筛选值得记录的类型：CLAS, INTF, FUGR, PROG, DDLS, BDEF, SRVD, TABL。跳过生成的代理、传输对象和测试 include 类。

步骤 2：读取每个对象的源代码和元数据

对每个对象并行运行以下操作：

SAPRead(type="<type>", name="<name>")             # Source
SAPContext(type="<type>", name="<name>", depth=1) # Dependencies (CLAS/INTF/PROG/FUNC/DDLS only; BTP: CLAS/INTF/DDLS)

对于 SAPContext 不支持的对象类型（FUGR、BDEF、SRVD、TABL、DOMA、DTEL），跳过依赖项调用，并通过正则表达式扫描源代码，将 CL_*、IF_*、SAP* 和 CALL FUNCTION '...' 列为“明显”的调用方/依赖项。在“依赖项”章节中注明置信度有所降低。

对于类，还要：

SAPRead(type="CLAS", name="<name>", method="*")   # Method listing with signatures

对于 CDS 视图，还要：

SAPRead(type="DDLS", name="<name>", include="elements")  # Field list

步骤 3：分类 ABAP 风格（仅限类和程序）

SAPLint(action="lint", name="<name>")

（如果源代码已在内存中，可传入 source=<source> 代替 name，以避免再次获取。）

解读 lint 结果：

Modern ABAP 的特征	Classic ABAP 的特征
使用 CDS、RAP、内联声明、NEW、REDUCE、CORRESPONDING	使用 FORM/ENDFORM、TABLES 语句、OCCURS
不使用 SELECT *，包含 ORDER BY，使用批量操作	在循环中逐行执行 SELECT SINGLE，使用 SELECT *
类包含测试类，使用接口进行 DI	使用具有全局状态的函数模块
不使用 MOVE-CORRESPONDING，使用 CORRESPONDING OF	大量使用 PERFORM 链

分类为：

• Modern——主要采用现代模式，风格适合云环境
• Classic——主要采用经典模式，给人 7.40 之前的感觉
• Mixed——两种模式兼有（常见情况：现代封装器搭配经典核心代码）

如果 SAPLint 失败，或对象无法进行 lint 检查（例如 CDS 视图、表），则跳过此章节。

步骤 4：（可选）通过 mcp-sap-docs 查询业务上下文

对于名称或结构中引用 SAP 应用组件（FI、SD、MM 等）的对象，可补充组件上下文：

search("<component_code> application component")

示例：ZCL_FI_GL_POSTING → 搜索 "FI-GL general ledger"，获取用于文档标题的 SAP 应用组件说明。

如果对象名称没有提供线索，则跳过此步骤。

步骤 5：编写 Markdown

5a. 单文件结构（≤30 个对象）

# <Package or group name> — Custom Code Documentation

_Generated <date> via sap-object-documenter skill on system <SID>._

## Overview

| Object | Type | Style | Purpose (1 line) |
|---|---|---|---|
| ZCL_SALES_HANDLER | CLAS | Modern | Behavior implementation for sales order RAP service |
| ZR_OLD_POSTING | PROG | Classic | Nightly batch for legacy FI posting |
| ...

## Objects

### ZCL_SALES_HANDLER

- **Type:** CLAS
- **Package:** Z_SALES_EXTENSIONS
- **Style:** Modern (uses RAP, inline decls, no SELECT *)
- **Purpose:** Handle validations and determinations for the Sales Order RAP business object.

**Public API**
- `validate_credit_limit( i_order )` — checks customer credit limit before save
- `determine_currency( c_order )` — defaults currency from sales org

**Dependencies**
- ZI_SALESORDER (CDS — root entity)
- CL_SALV_TABLE (A — released ALV class)
- ZCL_CREDIT_SERVICE (Z — custom credit service wrapper)

**Notes**
- No direct DB access; routes everything through the RAP entity.
- Tests: `ZCL_SALES_HANDLER_UT` (present, 8 test methods).

---

### ZR_OLD_POSTING
...

5b. 每个对象一个文件的结构（>30 个对象）

创建 docs/custom-code/<package>/README.md，其中包含概览表（链接到每个文件），并为每个对象创建一个 <object_name>.md，包含与上文相同的各个部分。

5c. 每个对象的标题（规范字段）

- **Type:** <TADIR type>
- **Package:** <package>
- **Style:** Modern | Classic | Mixed | n/a
- **Purpose:** <one-sentence summary>
- **Last change:** <SAPRead VERSIONS — most recent timestamp + user>
- **Current transport:** <SAPTransport action="history" — current lock request, or "unlocked"; candidates are assignment choices, not history>

“Last change”和“Current transport”行取自 ARC-1 的修订和当前分配 API。 旧版 history 操作无法提供完整的传输历史记录。

步骤 6：写入磁盘并报告

使用本地文件系统（Write 工具）生成 Markdown 文件。返回简短摘要：

Wrote 42 object docs to docs/custom-code/Z_SALES_EXTENSIONS/
  12 Modern | 18 Classic | 8 Mixed | 4 n/a (CDS/tables)

Longest objects (may need deeper docs):
  ZCL_SALES_HANDLER   (847 lines, 14 methods)
  ZR_OLD_POSTING      (1,204 lines)
  ...

后续选项

• “想把其中任何一项扩展为更深入的说明吗？”（→ explain-abap-code）
• “想检查此软件包是否符合 clean-core 要求吗？”（→ sap-clean-core-atc）
• “想先清理无用对象吗？”（→ sap-unused-code）
• “想将文档、用法、ATC 和评审卡片打包成迁移档案吗？”（→ sap-migration-dossier）

错误处理

错误	原因	修复方法
找不到对象	名称错误或对象已删除	记录并跳过；继续处理其余对象
SAPContext 失败	不支持的类型	使用正则表达式扫描源代码，手动列出导入项
SAPLint 失败	没有源代码（表、CDS）、语法不受支持	跳过该对象的风格分类
源代码为空	生成的代理或存根	在文档中注明“没有可用源代码”，仍输出其他元数据
输出路径已存在	文件冲突	添加时间戳后缀或询问用户
范围内对象超过 100 个	文档将难以阅读	停止并请用户缩小范围

注意事项

此技能不做什么

• 不生成代码——仅进行读取和总结。
• 不翻译业务逻辑——“Purpose”行根据命名、类头注释和测试类名称生成。如果这些信息缺失，则会如实说明。
• 不能替代优质代码注释——输出质量取决于源代码的命名质量。
• 不整合跨对象信息——每个对象单独记录。软件包级架构说明不在范围内。

何时使用此技能

• 帮助新开发者熟悉自定义代码软件包
• 咨询项目交接前——将组织知识记录为文档
• 迁移前文档编制（重写前快照记录现有内容）
• 合规性 / 审计跟踪（部分组织要求逐个对象编写文档）
• 用于构建知识库 / 仓库 Wiki

何时不要使用此技能

• 仅针对单个对象时——使用 explain-abap-code，速度更快且支持交互。
• 针对 SAP 随附代码时——此技能仅适用于 Z/Y 对象；对于 SAP 对象，请直接使用 mcp-sap-docs。
• 目标是分析代码质量时——使用 migrate-custom-code。