refactor: 本仓升为唯一源（原 sap-cli 源码仓归档）

方向反转：此前 SKILL.md 是「模板渲染产物」、sap-cli 是源；现 sap-cli 归档， sap-cli-skill 承接开发与分发，SKILL.md 回归手工维护的正本。迁移（来自 sap-cli，共 104 文件）： - tests/ 692 例测试（15 个文件的内联 sys.path 改指 assets/） - openspec/ SDD 规格与归档变更（42 文件） - docs/ 开发文档与 ADT 原理（含 dev/CLAUDE.md、AGENTS.md） - .claude/ rules 副本 + settings.json（供 Claude Code） - .github/ .hermes/ .pre-commit-config.yaml .editorconfig CLAUDE.md - scripts/ 保持仅 setup.py（pack_skill.py 已随旧仓归档，不迁）修复（迁移暴露的真实缺陷）： - assets/pyproject.toml 的 build-backend 写作 `setuptools.backends._legacy:_Backend`，该模块在 setuptools 中不存在 → `pip install -e` 从来装不上。改为 build_meta。实测：临时 venv 安装成功，sap-cli --help 正常列出 31 个命令 - pyproject readme 指向不存在的 assets/README.md（editable 安装会失败）→ 改内联文本 - pyproject urls 改指 sap-cli-skill 机制调整： - .github/workflows/ci.yml 适配 assets/ 布局；顶部注明该工作流仅 GitHub 执行，本仓在 Gitee 不会自动跑 - pre-commit 增本地测试门禁（Gitee 上真正生效的那道） - .gitignore 合并旧仓完整规则（保留 log/ 下 md 知识库入库，只忽略运行日志） - 大文件上限 100KB→1MB（架构图 512KB）守卫测试 tests/unit/test_repo_guards.py（10 → 18 例）： - SKILL.md 须记录 parser 全部 CLI 命令 / 铁律 1-5 须为真实小节标题 / 示例不得违反铁律 5 - references/ 规则齐备；.claude/rules 与 references 必须一致（实测抓到一次真实漂移） - VERSION == sapcli.__version__ == README 版本 - 仓内不得再出现 pack_skill.py / skill-src（防废弃流程回潮） 698 tests OK；editable 安装与 CLI 入口经临时 venv 实测通过。 docs/RELEASING.md 重写为单源开发流程。
2026-09-11 00:40:15 +08:00
parent e786742bcb
commit c5905a5b1e
104 changed files with 20744 additions and 10 deletions
@@ -0,0 +1,530 @@
+# 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              → 智能化开发
+```
+
+这个路径从 **"能用的工具"** 逐步演进到 **"不可替代的开发平台"**，每一步都有明确的用户价值。