# 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，会在启动时弹出一次传输请求选择，后续自动复用
```

## 命令速查

```bash
# 单对象操作
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`