sap-cli-skill/docs/dev/CLAUDE.md

sap-cli — AI 协作指南

[!danger] 核心约束：文档优先，禁止擅自读取源代码 本项目提供了完整的技术文档体系，AI 在协作时必须优先阅读文档获取所需信息，严禁未经许可直接读取 Python 源代码文件（sapcli/ 包内的 .py 文件、main.py、test/ 目录）。

如果发现文档描述与实际行为不一致，必须先向用户说明差异并征得同意，才能读取源代码进行校验。

项目简介

sap-cli 是一个命令行工具，通过 SAP ADT REST API 实现 ABAP 开发对象的远程管理（创建、同步、下载、查询、删除），让开发者可以在本地编辑器中编写 ABAP 代码，一行命令同步到 SAP 系统。

文档体系（AI 必读）

[!important] 文档覆盖了项目的全部设计细节，AI 应按需查阅以下文档，而非阅读源代码。

| 文档 | 用途 | 文件路径 |

文档	说明	路径
使用指南	命令详解、参数说明、输出示例	docs/guide.md
技术说明	架构、模块职责、通信流程、异常体系	docs/dev/architecture.md
批量同步设计	manifest 清单、拓扑排序、批量 sync	docs/dev/batch-design.md
测试报告	测试场景覆盖	docs/dev/test-report.md
ADT 学习笔记总览	ADT 原理系列索引	docs/adt/README.md

按需求查阅

需求	文档
了解某个命令怎么用	docs/guide.md
了解模块接口 / API 调用链	docs/dev/architecture.md
了解批量同步 / manifest	docs/dev/batch-design.md
了解 ADT REST API 原理	docs/adt/ 目录下的系列笔记
了解支持哪些对象类型	README.md 功能矩阵

AI 行为规范

1. 文档优先原则

• 所有问题先查文档 — 项目文档完整覆盖了架构、命令、API、模块接口、异常体系等全部信息
• 文档即真相 — 以文档描述为准进行操作，不需要通过读代码"验证"
• 引用文档回答 — 回答用户问题时引用具体文档路径，方便用户追溯

2. 源代码访问限制

[!warning] 以下文件属于源代码，未经用户许可禁止读取：

• main.py — CLI 入口
• sapcli/*.py — 核心包（config / types / client / commands / exceptions / manifest / scanner / sorter）
• test/**/*.py — 测试套件

允许读取的文件：

• *.md — 所有文档文件
• *.abap — ABAP 源代码文件（这是用户要同步到 SAP 的业务代码）
• config.ini — 连接配置（注意不要泄露密码）
• manifest.json — 项目清单文件
• *.drawio / *.png — 架构图等资源文件

3. 源代码校验流程

当文档描述与实际执行效果不一致时：

1. 向用户报告："文档描述 XXX，但实际表现为 YYY，差异点为 ZZZ"
2. 说明需要读取哪些源文件、读取目的是什么
3. 等待用户明确同意后，方可读取源代码
4. 读取后只关注差异点，不要全量阅读无关代码

4. 典型操作流程

帮助用户同步代码到 SAP

1. 确认用户的 ABAP 文件路径和对象信息（名称、类型）
2. 执行: python main.py sync --name <名称> --type <类型> --path <文件路径>
3. 如果成功 → 告知用户
4. 如果语法检查失败 → 展示错误信息，提示用户修改后重试
5. 如果激活失败 → 展示错误信息，提示用户修改后重试

帮助用户创建新对象

1. 确认对象名称、类型、描述
2. 执行: python main.py create --name <名称> --type <类型> --description "<描述>"
3. 创建成功后提示用户下载模板或直接编辑

帮助用户批量同步

1. 确认项目根目录路径
2. 如果没有 manifest.json，先执行: python main.py init --path <项目目录>
3. 预览执行计划: python main.py sync --all --path <项目目录> --dry-run
4. 确认后执行（推荐指定 --corr_nr 避免交互中断）:
   python main.py sync --all --path <项目目录> --corr_nr <传输请求号>
5. 如果不指定 --corr_nr，会在启动时弹出一次传输请求选择，后续自动复用

命令速查

# 单对象操作
python main.py create   --name <名称> --type <类型> [--description <描述>] [--corr_nr <请求号>]
python main.py info     --name <名称> --type <类型>
python main.py download --name <名称> --type <类型> --path <保存目录>
python main.py sync     --name <名称> --type <类型> --path <.abap文件> [--corr_nr <请求号>]
python main.py delete   --name <名称> --type <类型>

# 批量操作（基于 manifest 清单）
python main.py init     --path <项目目录>
python main.py sync     --all --path <项目目录> [--dry-run] [--fail-fast]
python main.py refresh  --path <项目目录>

# 搜索与浏览
python main.py list     --type <类型> [--package <包名>] [--prefix <前缀>]
python main.py whereused --name <名称> --type <类型>
python main.py search   --query <关键词> [--type <类型>]

# 传输管理
python main.py transport list
python main.py transport info --corr_nr <请求号>
python main.py transport release --corr_nr <请求号>
python main.py transport objects --corr_nr <请求号>

# 代码质量
python main.py check    --name <名称> --type <类型>
python main.py format   --name <名称> --type <类型>
python main.py diff     --name <名称> --type <类型> [--path <本地文件>]

# 包管理
python main.py package create --name <包名> [--description <描述>]
python main.py package info --name <包名>
python main.py package list --name <包名>

# CDS View
python main.py cds download --name <CDS名> --path <目录>
python main.py cds sync --name <CDS名> --path <DDL文件>
python main.py cds create --name <CDS名> [--description <描述>]

# 辅助工具
python main.py analyze  --path <项目目录>
python main.py scaffold --name <名称> --template <模板> [--package <包名>]
python main.py config show
python main.py config list-profiles

对象类型速查

类型参数	说明	名称格式
report	程序/报表	直接使用程序名
class	ABAP 类	直接使用类名
interface	ABAP 接口	直接使用接口名
function	函数模块	函数组名/函数模块名
functiongroup	函数组	直接使用函数组名
include	Include 程序	直接使用程序名
domain	域	直接使用域名
dataelement	数据元素	直接使用元素名
table	透明表	直接使用表名
structure	结构	直接使用结构名
tabletype	表类型	直接使用类型名
cdsview	CDS View	直接使用 CDS 名
messageclass	消息类	直接使用消息类名
view	数据库视图	直接使用视图名
searchhelp	搜索帮助	直接使用搜索帮助名
lockobject	锁对象	直接使用锁对象名

依赖排序优先级（批量同步）

domain(10) → dataelement(20) → structure(25) → table(30) → tabletype(40) → view(42) → lockobject(44) → searchhelp(46) → messageclass(48) → interface(50) → class(60) → function(70) → functiongroup(75) → include(78) → cdsview(79) → report(80)

关键技术要点

• 认证: HTTP Basic Auth + CSRF Token
• sync 流程: 检查/创建 → 锁定 → 写入 → 解锁 → 语法检查 → 激活
• 锁定机制: stateful session，自动检测传输请求绑定
• 配置加载优先级: 环境变量 > --config 指定文件 > 工作目录 config.ini > 脚本目录 config.ini
• 唯一第三方依赖: requests