sap-cli-skill/docs/dev/extension-plan.md

# sap-cli 功能扩展分析报告

> **项目**: sap-cli — 用你喜欢的编辑器写 ABAP  
> **版本**: 当前 (v1.0)  
> **编制日期**: 2026-06-09  
> **定位**: 基于 SAP ADT REST API 的命令行 ABAP 开发工具

---

## 一、现有功能全景

### 1.1 已实现的 7 个命令

| 命令 | 功能 | 适用对象 |
|:-----|:-----|:---------|
| `download` | 从 SAP 下载源码到本地 .abap 文件 | report / class / interface / function / domain / dataelement / table / structure |
| `sync` | 本地代码 → SAP（锁定→写入→解锁→语法检查→激活） | 同上 |
| `create` | 在 SAP 创建开发对象（支持模板和 JSON 定义） | 10 种类型（含 functiongroup、tabletype） |
| `info` | 查询对象元数据（名称/类型/状态/负责人/修改时间等） | 10 种类型 |
| `delete` | 从 SAP 系统删除对象（需确认） | 10 种类型 |
| `init` | 扫描本地目录 → 查询 SAP → 生成 manifest.json | 批量 |
| `refresh` | 刷新清单中对象的 SAP 状态 | 批量 |

### 1.2 已支持的对象类型

**ABAP 程序对象（5 种）**：report、class、interface、function、functiongroup

**ABAP 字典对象（5 种）**：domain、dataelement、table、structure、tabletype

### 1.3 核心能力

- ✅ 单对象 CRUD 全生命周期
- ✅ 批量同步（基于 manifest.json + 拓扑排序）
- ✅ 传输请求管理（list / create / select）
- ✅ DDIC 对象通过 JSON 定义文件创建
- ✅ 锁定-编辑-解锁-激活完整工作流
- ✅ 语法检查集成

---

## 二、功能扩展方向

### 🔵 方向一：对象类型扩展

#### 2.1.1 ADT 已支持但工具未覆盖的对象类型

| 优先级 | 对象类型 | ADT 端点 | 使用场景 | 实现难度 |
|:------:|:---------|:---------|:---------|:--------:|
| ⭐⭐⭐ | **CDS View (DDL)** | `/sap/bc/adt/ddic/ddlsources` | S/4HANA 核心开发，CDS View 是现代 ABAP 开发的基础 | 中 |
| ⭐⭐⭐ | **CDS Access Control (DCL)** | `/sap/bc/adt/authorization/dclsources` | CDS 角色权限控制，与 CDS View 配套 | 中 |
| ⭐⭐⭐ | **Include 程序** | `/sap/bc/adt/programs/programs` | 大型报表拆分，复用代码片段 | 低 |
| ⭐⭐ | **消息类 (Message Class)** | `/sap/bc/adt/messageclasses` | MESSAGE 语句依赖，项目必备 | 低 |
| ⭐⭐ | **数据库视图 (View)** | `/sap/bc/adt/ddic/views` | 数据建模，查询优化 | 中 |
| ⭐⭐ | **搜索帮助 (Search Help)** | `/sap/bc/adt/ddic/searchhelps` | ALV 屏幕、F4 帮助 | 中 |
| ⭐⭐ | **锁对象 (Lock Object)** | `/sap/bc/adt/ddic/lockobjects` | 并发控制，多用户数据一致性 | 中 |
| ⭐ | **类型组 (Type Pool)** | `/sap/bc/adt/programs/programs` | 常量/类型定义集中管理 | 低 |
| ⭐ | **AMDP 类** | 复用 class 端点 | HANA 数据库过程调用 | 低 |
| ⭐ | **Web Dynpro 组件** | 专用端点 | 传统 Web UI（逐渐淘汰） | 高 |

**实现建议**：
- 第一批优先：**Include 程序**（改动最小，复用现有 report 逻辑）+ **CDS View**（战略价值最高）
- CDS View 需要新增 `cdsview` 类型，源码是 DDL 语法（非 ABAP），激活流程与 DDIC 类似

#### 2.1.2 tabletype 的完整支持

当前 `tabletype` 使用 VIT 端点，不支持 download/sync/delete。可以探索：
- 通过 DDIC 专用端点（`/sap/bc/adt/ddic/tabletypes`）的源码读写接口
- 或使用 VIT 的 PUT 操作实现间接源码写入

---

### 🔵 方向二：代码浏览与搜索

#### 2.2.1 对象列表浏览（`list` 命令）

```
python main.py list --type class --prefix ZCL_* --package ZFINANCE
```

**ADT API**: `GET /sap/bc/adt/repository/informationsystem/search`  
**使用场景**: 
- 浏览某个包下的所有对象
- 按名称前缀模糊搜索
- 按类型/所有者/修改时间筛选

#### 2.2.2 Where-Used 引用查询

```
python main.py whereused --name ZCL_MY_CLASS --type class
```

**ADT API**: `GET /sap/bc/adt/whereused`  
**使用场景**:
- 修改前评估影响范围
- 自动填充 `manifest.json` 的 `depends_on` 字段（替代手动维护）
- 批量同步时自动推导依赖关系

#### 2.2.3 源代码全文搜索

```
python main.py search --query "SELECT * FROM ZMY_TABLE" --type report
```

**ADT API**: `GET /sap/bc/adt/repository/informationsystem/search` (code search)  
**使用场景**: 快速定位引用特定表/函数/变量的代码位置

---

### 🔵 方向三：代码质量与检查

#### 2.3.1 ATC 代码检查集成

```
python main.py check --name ZMY_REPORT --type report --variant SAP_ABA_CHECK
```

**ADT API**: `POST /sap/bc/adt/qualitymanager/ats/checkruns`  
**使用场景**:
- 同步前自动运行 ATC 检查（替代或补充现有语法检查）
- CI/CD 流水线中的质量门禁
- 支持自定义检查变体

#### 2.3.2 代码格式化（ABAP Pretty Printer）

```
python main.py format --name ZMY_REPORT --type report
```

**ADT API**: `POST /sap/bc/adt/prettyprinter`  
**使用场景**: 
- 下载后自动格式化（统一缩进、大小写风格）
- sync 前自动格式化（保持 SAP 端代码风格一致）

#### 2.3.3 代码差异对比

```
python main.py diff --name ZMY_REPORT --type report --path ./src/zmy_report.abap
```

**使用场景**:
- sync 前预览即将上传的改动
- 显示本地文件与 SAP 端源码的差异
- 防止误覆盖他人的修改

---

### 🔵 方向四：传输管理与多系统

#### 2.4.1 传输请求高级管理

```
python main.py transport list --status D    # 查看可修改的传输请求
python main.py transport info DEVK901362     # 查看传输请求详情
python main.py transport release DEVK901362  # 释放传输请求
python main.py transport objects DEVK901362  # 列出传输请求中的所有对象
```

**ADT API**: 
- `GET /sap/bc/adt/cts/transportrequests/{id}` — 详情
- `POST /sap/bc/adt/cts/transportrequests/{id}?method=release` — 释放

**使用场景**: 
- 批量同步后一键释放传输请求
- 在命令行中管理传输请求，无需进入 SAP GUI（SE01/SE09）

#### 2.4.2 多系统配置与跨系统同步

```ini
# config.ini
[DEV]
host = http://dev-sap:8000
client = 100

[QAS]
host = http://qas-sap:8000
client = 200

[PRD]
host = http://prd-sap:8000
client = 300
```

```
python main.py --profile DEV download --name ZMY_REPORT --type report --path ./src
python main.py --profile QAS info --name ZMY_REPORT --type report
```

**使用场景**:
- 开发/测试/生产多环境切换
- 跨系统对象对比（DEV vs QAS 代码差异）
- 一键从 DEV 下载 → 修改 → 推送到 QAS

#### 2.4.3 传输导入监控

```
python main.py transport import DEVK901362 --target QAS
python main.py transport status DEVK901362
```

**使用场景**: 跟踪传输请求在目标系统的导入状态

---

### 🔵 方向五：包管理与项目结构

#### 2.5.1 ABAP 包（Package）操作

```
python main.py package create ZFINANCE --description "财务模块" --superpackage ZBUSINESS
python main.py package list --superpackage ZBUSINESS
python main.py package move --name ZMY_REPORT --type report --package ZFINANCE
```

**ADT API**: `/sap/bc/adt/packages/{name}`  
**使用场景**: 
- 项目初始化时自动创建包结构
- 将 $TMP 本地对象迁移到正式包中

#### 2.5.2 项目模板（Scaffolding）

```
python main.py scaffold --name ZSALES_ORDER --template "ALV Report" --package ZSALES
```

预置模板：
- **ALV 报表** — 包含 ALV GRID、字段目录、布局管理
- **BAPI 封装** — 函数组 + 函数模块 + 异常处理
- **接口类** — 接口 + 实现类 + 工厂方法
- **数据模型** — domain + dataelement + table + tabletype + CDS View
- **增强实现** — BAdI 定义 + 实现（如果 ADT 支持）

**使用场景**: 快速创建符合项目规范的标准代码骨架

#### 2.5.3 依赖自动分析

```
python main.py analyze --path ./project
```

**功能**:
- 解析本地 .abap 文件中的 `TYPE REF TO`、`CALL METHOD`、`PERFORM` 等语句
- 自动生成 `depends_on` 关系
- 替代当前手动维护 manifest.json 依赖的方式
- 结合 Where-Used API 交叉验证

---

### 🔵 方向六：Git 集成与 DevOps

#### 2.6.1 Git Hooks 集成

```bash
# pre-commit hook: sync 前自动语法检查
# post-pull hook: 自动 download 远端最新代码
```

**使用场景**: 
- `git commit` 前自动触发 ATC 检查
- `git pull` 后自动拉取 SAP 端最新代码
- `git push` 后自动触发 CI/CD

#### 2.6.2 CI/CD Pipeline 集成

```yaml
# .gitlab-ci.yml 示例
abap-sync:
  stage: deploy
  script:
    - python main.py sync --all --path ./src --corr_nr $TR_NUMBER --fail-fast
    - python main.py check --all --path ./src
```

**使用场景**: 
- Git 提交后自动同步到 SAP 开发系统
- ATC 检查作为质量门禁
- 传输请求自动创建和释放

#### 2.6.3 代码版本对比（SAP 版本管理集成）

```
python main.py history --name ZMY_REPORT --type report
python main.py version --name ZMY_REPORT --type report --version 1.2
```

**ADT API**: `/sap/bc/adt/programs/programs/{name}/versions`  
**使用场景**: 
- 查看 SAP 端的版本历史
- 对比不同版本之间的代码差异
- 回滚到之前的版本

---

### 🔵 方向七：交互体验优化

#### 2.7.1 交互式终端 UI（TUI）

```
python main.py tui
```

**功能**: 
- 基于 [Textual](https://github.com/Textualize/textual) 或 [Rich](https://github.com/Textualize/rich) 的终端 UI
- 对象树状浏览器（按类型/包/状态分组）
- 源码差异对比视图
- 批量操作进度条

#### 2.7.2 全局配置与 Profile

```bash
sap-cli config set default_host http://dev-sap:8000
sap-cli config set default_client 100
sap-cli config set auto_format true
sap-cli config set atc_variant SAP_ABA_CHECK
sap-cli config set timeout 30
```

**使用场景**: 
- 替代手动编辑 config.ini
- 按项目/环境保存不同配置
- 设置全局默认参数（超时、格式化、检查变体等）

#### 2.7.3 Shell 自动补全

```bash
eval "$(sap-cli completion bash)"
eval "$(sap-cli completion zsh)"
```

**使用场景**: Tab 键自动补全命令、对象类型、对象名

---

### 🔵 方向八：AI 与智能化

#### 2.8.1 AI 辅助代码生成

```
python main.py generate --type report --description "根据销售订单号查询交货明细的ALV报表" --output ./src/zdelivery_detail.abap
```

**使用场景**: 
- 结合 LLM API（如 Claude/GPT）根据自然语言描述生成 ABAP 代码
- 自动识别所需的表、数据元素、函数模块
- 生成的代码自动通过语法检查

#### 2.8.2 MCP 服务器模式

```
python main.py mcp-server --port 8080
```

**参考**: [erpl-adt](https://github.com/DataZooDE/erpl-adt) 已实现 MCP 服务器  
**使用场景**: 
- 作为 MCP 工具供 AI 助手（如 Claude Desktop）调用
- AI 可以直接浏览 SAP 对象、下载/同步代码
- 实现"用自然语言修改 SAP 系统"的终极目标

#### 2.8.3 智能代码审查

```
python main.py review --name ZMY_REPORT --type report --rules performance,security
```

**使用场景**: 
- 基于规则的静态分析（SQL 注入、性能反模式、命名规范）
- 结合 AI 的代码审查建议
- 自动生成改进建议

---

### 🔵 方向九：安全与运维

#### 2.9.1 密码安全存储

```
python main.py auth login       # 交互式输入密码，存入系统 keyring
python main.py auth status      # 检查登录状态
python main.py auth logout      # 清除凭证
```

**实现方案**: 
- 使用 [keyring](https://github.com/jaraco/keyring) 库
- 支持 Windows Credential Manager / macOS Keychain / Linux Secret Service
- 不再明文存储密码

#### 2.9.2 SSL 证书验证

```ini
[DEV]
host = https://dev-sap:44300
verify_ssl = true
ca_bundle = /path/to/corp-ca.pem
```

**使用场景**: 
- 生产环境安全要求
- 企业内网 CA 证书支持
- 当前硬编码 `verify=False`，存在中间人攻击风险

#### 2.9.3 审计日志

```
python main.py audit --from 2026-06-01 --to 2026-06-09
```

**使用场景**: 
- 记录所有 create/sync/delete 操作的审计日志
- 支持按时间/用户/操作类型查询
- 满足企业合规要求

---

## 三、扩展优先级矩阵

按照 **业务价值 × 实现难度** 排序：

| 优先级 | 扩展方向 | 业务价值 | 实现难度 | 建议版本 |
|:------:|:---------|:--------:|:--------:|:--------:|
| 🔴 P0 | Include 程序支持 | ⭐⭐⭐ | ⭐ | v1.1 |
| 🔴 P0 | 对象列表浏览 (list) | ⭐⭐⭐ | ⭐⭐ | v1.1 |
| 🔴 P0 | 多系统配置 (profile) | ⭐⭐⭐ | ⭐⭐ | v1.2 |
| 🔴 P0 | 密码安全存储 (keyring) | ⭐⭐⭐ | ⭐ | v1.2 |
| 🟠 P1 | CDS View 支持 | ⭐⭐⭐ | ⭐⭐⭐ | v1.3 |
| 🟠 P1 | Where-Used 引用查询 | ⭐⭐⭐ | ⭐⭐ | v1.3 |
| 🟠 P1 | 代码差异对比 (diff) | ⭐⭐⭐ | ⭐⭐ | v1.3 |
| 🟠 P1 | 传输请求高级管理 | ⭐⭐⭐ | ⭐⭐ | v1.4 |
| 🟠 P1 | ABAP 包操作 | ⭐⭐ | ⭐⭐ | v1.4 |
| 🟡 P2 | ATC 代码检查集成 | ⭐⭐ | ⭐⭐⭐ | v2.0 |
| 🟡 P2 | 代码格式化 (Pretty Printer) | ⭐⭐ | ⭐⭐ | v2.0 |
| 🟡 P2 | 依赖自动分析 | ⭐⭐⭐ | ⭐⭐⭐ | v2.0 |
| 🟡 P2 | 项目模板 (Scaffolding) | ⭐⭐ | ⭐⭐ | v2.0 |
| 🟡 P2 | CI/CD Pipeline 集成 | ⭐⭐⭐ | ⭐⭐ | v2.1 |
| 🟢 P3 | 消息类 / 视图 / 搜索帮助 / 锁对象 | ⭐⭐ | ⭐⭐ | v2.x |
| 🟢 P3 | 源代码全文搜索 | ⭐⭐ | ⭐⭐ | v2.x |
| 🟢 P3 | SAP 版本管理集成 | ⭐⭐ | ⭐⭐⭐ | v2.x |
| 🟢 P3 | Shell 自动补全 | ⭐ | ⭐ | v2.x |
| 🔵 P4 | 交互式终端 UI (TUI) | ⭐⭐ | ⭐⭐⭐ | v3.0 |
| 🔵 P4 | AI 辅助代码生成 | ⭐⭐⭐ | ⭐⭐⭐ | v3.0 |
| 🔵 P4 | MCP 服务器模式 | ⭐⭐⭐ | ⭐⭐ | v3.0 |
| 🔵 P4 | 智能代码审查 | ⭐⭐ | ⭐⭐⭐ | v3.0 |

---

## 四、技术架构建议

### 4.1 近期架构优化（支持 v1.x 扩展）

```
sapcli/
├── __init__.py
├── main.py              # CLI 入口（拆分 argparse 到独立模块）
├── cli/                 # 命令注册与解析（新增）
│   ├── parser.py        # argparse 定义
│   ├── completions.py   # Shell 补全
│   └── output.py        # 格式化输出（替代散落各处的 print）
├── client.py            # ADT REST 客户端（保持）
├── commands/            # 按功能拆分命令（新增目录）
│   ├── crud.py          # download / sync / create / delete / info
│   ├── batch.py         # init / refresh / sync-all
│   ├── transport.py     # 传输请求管理（新增）
│   ├── search.py        # list / whereused / search（新增）
│   └── check.py         # syntax-check / atc（新增）
├── types.py             # 对象类型注册（保持）
├── ddic.py              # DDIC 定义（保持）
├── manifest.py          # 清单管理（保持）
├── scanner.py           # 目录扫描（保持）
├── sorter.py            # 拓扑排序（保持）
├── config.py            # 配置管理（增强多 profile）
├── auth.py              # 凭证管理（新增：keyring 集成）
├── exceptions.py        # 异常定义（保持）
└── utils/               # 工具函数（新增）
    ├── xml_utils.py     # XML 安全转义、解析
    ├── diff.py          # 代码差异对比
    └── format.py        # ABAP 格式化
```

### 4.2 新增对象类型的标准流程

每次新增一个对象类型，需要修改的文件：

| 步骤 | 文件 | 内容 |
|:-----|:-----|:-----|
| 1 | `types.py` | 注册 `ObjectTypeConfig`（URI 模板、content-type） |
| 2 | `client.py` | `_build_create_body()` 新增分支（或数据驱动） |
| 3 | `scanner.py` | `DIRECTORY_TYPE_MAP` 新增目录映射 |
| 4 | `commands.py` | 特殊逻辑处理（如有） |
| 5 | `ddic.py` | 如有 XML/DDL 定义需求 |

### 4.3 建议引入的依赖

| 依赖 | 用途 | 时机 |
|:-----|:-----|:-----|
| `keyring` | 安全凭证存储 | v1.2 |
| `rich` | 终端美化输出（进度条、表格、语法高亮） | v1.3 |
| `textual` | 终端 UI 框架 | v3.0（可选） |
| `pydantic` | JSON 定义文件验证 | v2.0 |
| `httpx` | 替代 requests（支持 async、超时、重试） | v2.0 |

---

## 五、竞品参考

| 项目 | 语言 | 特点 | 值得借鉴 |
|:-----|:-----|:-----|:---------|
| [abap-adt-api](https://github.com/marcellourbani/abap-adt-api) | TypeScript | 最全面的 ADT API 封装 | CDS View、AMDP、Where-Used、搜索 |
| [erpl-adt](https://github.com/DataZooDE/erpl-adt) | TypeScript | CLI + MCP 服务器 | MCP 协议、对象浏览、AI 集成 |
| [abapGit](https://github.com/abapGit/abapGit) | ABAP | SAP 端 Git 客户端 | 版本管理思想、serialize/deserialize |

---

## 六、总结

sap-cli 已经建立了一个坚实的核心：
- **10 种对象类型**的完整 CRUD
- **批量同步** + 拓扑排序 + 传输请求管理
- **manifest.json** 状态驱动的项目管理

最自然、最高价值的扩展路径是：

```
v1.1  Include + list + 消息类     → 补齐日常开发必需类型
v1.2  多系统 + keyring            → 企业级安全与多环境
v1.3  CDS View + Where-Used       → S/4HANA 现代化开发
v1.4  传输管理 + 包操作           → 运维与管理能力
v2.0  ATC + diff + 依赖分析       → 代码质量保障
v2.x  CI/CD + 模板 + 搜索         → DevOps 集成
v3.0  TUI + AI + MCP              → 智能化开发
```

这个路径从 **"能用的工具"** 逐步演进到 **"不可替代的开发平台"**，每一步都有明确的用户价值。