sap-cli-skill/docs/dev/batch-design.md

---
title: 批量同步设计 — 项目清单驱动
created: 2026-05-25
updated: 2026-05-25
tags:
  - SAP
  - ADT
  - design
parent: "[[sap-cli/doc/sap-cli使用指南|sap-cli使用指南]]"
related:
  - "[[sap-cli/doc/技术说明|技术说明]]"
  - "[[sap-cli/doc/sap-cli使用指南#4.3 源代码同步激活 (`sync`)|sync 命令]]"
---

# 批量同步设计 — 项目清单驱动

> [!abstract] 概述
> 为 sap-cli 工具增加**项目清单**机制，支持批量源代码同步。核心思路：在源代码目录下维护 `manifest.json` 清单文件，记录每个开发对象在 SAP 系统中的状态，后续操作基于清单驱动，避免重复查询。

> [!info] 设计动机
> 现有 `sync` 命令只支持单对象操作，缺少以下能力：
> - 批量扫描本地文件并识别对象
> - 预查询 SAP 系统状态，制定执行计划
> - 按依赖关系排序，批量执行同步
> - 缓存对象状态，避免每次重复查询

## 1. 目录约定

### 1.1 项目目录结构

项目根目录下按对象类型组织子目录，`manifest.json` 位于根目录：

```
project/                        ← --path 指向这里（项目根目录）
├── manifest.json               ← 状态清单（init 自动生成）
├── reports/
│   └── {对象名小写}.abap
├── classes/
│   └── {对象名小写}.abap
├── interfaces/
│   └── {对象名小写}.abap
├── functions/
│   └── {函数组名小写}/
│       └── {函数模块名小写}.abap
├── domains/
│   └── {对象名小写}.abap
├── dataelements/
│   └── {对象名小写}.abap
├── tables/
│   └── {对象名小写}.abap
└── tabletypes/
    └── {对象名小写}.abap
```

### 1.2 目录名 → 类型映射

`init` 扫描时按以下映射表从目录名推断对象类型：

| 目录名 | 对象类型 | 文件 → 对象名规则 |
|--------|---------|------------------|
| `reports/` | `report` | `zmy_report.abap` → `ZMY_REPORT` |
| `classes/` | `class` | `zcl_my_class.abap` → `ZCL_MY_CLASS` |
| `interfaces/` | `interface` | `zif_my_interface.abap` → `ZIF_MY_INTERFACE` |
| `functions/` | `function` | `zgroup/z_my_func.abap` → `ZGROUP/Z_MY_FUNC` |
| `domains/` | `domain` | `z_status.abap` → `Z_STATUS` |
| `dataelements/` | `dataelement` | `z_status.abap` → `Z_STATUS` |
| `tables/` | `table` | `zmy_table.abap` → `ZMY_TABLE` |
| `tabletypes/` | `tabletype` | `zty_table.abap` → `ZTY_TABLE` |

> [!note] 文件名 → 对象名规则
> - 文件名去掉 `.abap` 后缀后转为大写即为对象名
> - `functions/` 下的子目录名作为函数组名，子目录内的文件名作为函数模块名
> - 对象名为 `函数组名大写/函数模块名大写` 格式

## 2. 清单文件 (`manifest.json`)

### 2.1 结构定义

```json
{
  "version": 1,
  "last_init": "2026-05-25T10:00:00",
  "last_refresh": "2026-05-25T14:00:00",
  "objects": {
    "<对象名>": {
      "type": "<对象类型>",
      "file": "<相对文件路径>",
      "system_status": "<状态>",
      "corr_nr": "<传输请求号或null>",
      "depends_on": ["<依赖对象名>"],
      "last_sync": "<ISO时间戳或null>",
      "last_sync_result": "<结果>"
    }
  }
}
```

### 2.2 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `version` | int | 清单格式版本号，当前为 `1` |
| `last_init` | string | 最近一次 `init` 的时间戳 |
| `last_refresh` | string | 最近一次 `refresh` 的时间戳 |
| `objects` | object | 以对象名为 key 的字典 |
| `objects.<name>.type` | string | 对象类型（report/class/interface/...） |
| `objects.<name>.file` | string | 相对于项目根目录的文件路径 |
| `objects.<name>.system_status` | string | `active` / `inactive` / `not_exists` |
| `objects.<name>.corr_nr` | string\|null | 传输请求号，`null` 表示本地对象 `$TMP` |
| `objects.<name>.depends_on` | string[] | 依赖的对象名列表 |
| `objects.<name>.last_sync` | string\|null | 最近一次成功同步的时间 |
| `objects.<name>.last_sync_result` | string | `success` / `failed` / `pending` |

### 2.3 示例

```json
{
  "version": 1,
  "last_init": "2026-05-25T10:00:00",
  "last_refresh": null,
  "objects": {
    "Z_STATUS": {
      "type": "domain",
      "file": "domains/z_status.abap",
      "system_status": "active",
      "corr_nr": "DEVK901362",
      "depends_on": [],
      "last_sync": "2026-05-25T10:30:00",
      "last_sync_result": "success"
    },
    "ZIF_MY_INTERFACE": {
      "type": "interface",
      "file": "interfaces/zif_my_interface.abap",
      "system_status": "active",
      "corr_nr": "DEVK901362",
      "depends_on": [],
      "last_sync": "2026-05-25T10:30:00",
      "last_sync_result": "success"
    },
    "ZCL_MY_CLASS": {
      "type": "class",
      "file": "classes/zcl_my_class.abap",
      "system_status": "active",
      "corr_nr": "DEVK901362",
      "depends_on": ["ZIF_MY_INTERFACE"],
      "last_sync": "2026-05-25T11:00:00",
      "last_sync_result": "success"
    },
    "ZMY_REPORT": {
      "type": "report",
      "file": "reports/zmy_report.abap",
      "system_status": "inactive",
      "corr_nr": null,
      "depends_on": ["ZCL_MY_CLASS"],
      "last_sync": null,
      "last_sync_result": "pending"
    },
    "ZGROUP/Z_MY_FUNC": {
      "type": "function",
      "file": "functions/zgroup/z_my_func.abap",
      "system_status": "active",
      "corr_nr": "DEVK901362",
      "depends_on": [],
      "last_sync": "2026-05-25T10:00:00",
      "last_sync_result": "success"
    }
  }
}
```

## 3. 命令变更一览

| 命令 | 变更类型 | 说明 |
|------|---------|------|
| `init` | **新增** | 扫描项目目录 → 查询 SAP → 生成 `manifest.json` |
| `create` | **变更** | 新增 `--path` 参数；创建成功后自动写入清单 |
| `sync` | **变更** | 新增 `--all` 批量模式；单对象模式操作后更新清单 |
| `delete` | **变更** | 新增 `--path` 参数；删除成功后从清单移除 |
| `refresh` | **新增** | 重新查询清单中所有对象的 SAP 状态 |

## 4. 命令详细设计

### 4.1 `init` — 项目初始化（新增）

#### 命令格式

```bash
python main.py init --path <项目根目录>
```

#### 执行流程

```
扫描项目目录
  ├─ 按目录映射表识别文件 → 生成 {对象名, 类型, 文件路径} 列表
  ├─ 输出: "扫描到 N 个本地文件"
  └─ 忽略非 .abap 文件和隐藏文件

逐个查询 SAP 系统
  ├─ 对象存在 → 查询 info → 获取 system_status + corr_nr
  ├─ 对象不存在 → 标记 system_status: "not_exists"
  └─ 查询失败 → 标记 system_status: "unknown"

应用类型默认优先级生成初始 depends_on
  （init 时只设置类型层面的默认依赖，用户可后续手动编辑）
  domain/dataelement/table → 无依赖
  tabletype → 依赖同项目中的 table
  interface → 无依赖
  class → 依赖同项目中被引用的 interface
  function → 无显式依赖
  report → 无显式依赖

写入 manifest.json
输出汇总报告
```

#### 输出示例

```
============================================================
  sap-cli 项目初始化
============================================================
  项目路径: ./project
  扫描到 5 个本地文件

  → 正在查询 SAP 系统状态...
  ✓ Z_STATUS           (domain)     active   corr: DEVK901362
  ✓ ZIF_MY_INTERFACE   (interface)  active   corr: DEVK901362
  ✓ ZCL_MY_CLASS       (class)      active   corr: DEVK901362
  ⚠ ZMY_REPORT         (report)     inactive corr: 本地对象
  ✗ ZCL_NEW_CLASS      (class)      不存在

  ✓ 清单已生成: ./project/manifest.json
     5 个对象: 3 已激活, 1 未激活, 1 不存在
```

> [!tip] 清单可手动编辑
> `manifest.json` 生成后，用户可以手动编辑 `depends_on` 字段来补充对象间的显式依赖关系。
> `init` 只设置类型层面的默认依赖，具体的引用关系（如某个 class 实现了哪个 interface）需要用户自行标注。

---

### 4.2 `sync --all` — 批量同步（新增）

#### 命令格式

```bash
python main.py sync --all --path <项目根目录> [--corr_nr <传输请求号>] [--fail-fast] [--dry-run]
```

| 参数 | 必需 | 说明 |
|------|------|------|
| `--all` | 是 | 启用批量模式 |
| `--path` | 是 | 项目根目录（包含 `manifest.json`） |
| `--corr_nr` | 否 | 统一传输请求号（跳过交互选择，所有对象共用） |
| `--fail-fast` | 否 | 遇到失败立即停止（默认：跳过并继续） |
| `--dry-run` | 否 | 仅输出执行计划，不实际操作 |

#### 执行流程

```
读取 manifest.json
  ├─ 不存在 → 报错: "请先执行 init"
  └─ 存在 → 继续

扫描本地文件 vs 清单差异
  ├─ 本地有但清单没有的文件 → 提示: "N 个未纳入清单的文件，建议先 create"
  └─ 清单有但本地被删的文件 → 警告，跳过

过滤待处理对象
  ├─ system_status == "active" && last_sync_result == "success" → 跳过（已同步）
  ├─ system_status == "not_exists" → 标记为 [create + sync]
  └─ 其他 → 标记为 [sync]

拓扑排序
  ├─ 按 depends_on 建有向图
  ├─ 无显式依赖的按类型默认优先级排序
  └─ 检测循环依赖 → 报错退出

--dry-run 模式:
  输出执行计划，不实际操作

传输请求预选择（一次性交互）:
  ├─ 扫描待处理对象，统计需要传输请求号的数量
  ├─ 指定了 --corr_nr → 直接使用，无交互
  ├─ 全部对象已绑定请求号或为本地对象 → 无交互
  └─ 有对象需要请求号 → 弹出一次选择，选定后全局复用:
       ├─ 选择已有请求号 → 后续所有需要请求号的对象都使用此请求号
       ├─ 新建请求号 → 同上
       └─ 不使用请求号 → 所需对象都作为本地对象处理

执行阶段（按排序顺序逐个处理，使用预选的传输请求号）:
  对每个对象:
    ├─ 本地文件不存在 → 跳过，警告
    ├─ system_status == "not_exists" → 先执行 create（使用预选请求号）
    ├─ 执行 sync 逻辑（使用预选请求号，跳过逐对象交互）:
    │     ├─ 对象已绑定请求号 → 使用对象自身绑定的请求号
    │     ├─ 本地对象（$TMP）→ 无需请求号
    │     └─ 未绑定 → 使用预选的统一请求号（不再弹出交互）
    ├─ 成功 → 更新 manifest:
    │     system_status: "active"
    │     corr_nr: 实际使用的请求号
    │     last_sync: 当前时间
    │     last_sync_result: "success"
    └─ 失败 →
         ├─ --fail-fast → 停止，输出已处理和未处理的对象
         └─ 默认 → 标记 last_sync_result: "failed"，跳过，继续下一个
                     后续依赖此对象的对象也自动跳过（标记 skipped）

输出汇总报告
```

#### dry-run 输出示例

```
============================================================
  sap-cli 批量同步 (dry-run)
============================================================
  项目路径: ./project
  清单对象: 5

  执行计划（按依赖排序）:
    1. Z_STATUS           (domain)     → sync [inactive → active]
    2. ZIF_MY_INTERFACE   (interface)  → 跳过 [已是最新]
    3. ZCL_MY_CLASS       (class)      → sync [依赖: ZIF_MY_INTERFACE ✓]
    4. ZMY_REPORT         (report)     → sync [依赖: ZCL_MY_CLASS]
    5. ZGROUP/Z_MY_FUNC   (function)   → 跳过 [已是最新]

  待处理: 3 个 | 跳过: 2 个
```

#### 执行输出示例

```
============================================================
  sap-cli 批量同步
============================================================
  项目路径: ./project
  待处理: 3 个对象

  → 预检传输请求需求...
     2 个对象已绑定请求号: Z_STATUS(DEVK901362), ZCL_MY_CLASS(DEVK901362)
     1 个对象需要传输请求: ZMY_REPORT

  → 查询可用的传输请求...
  找到 2 个可修改的传输请求:

    1. DEVK901362  Implement sales validation  (所有者: ADMIN2)
    2. DEVK901365  Bugfix for invoice printing  (所有者: ADMIN2)
    3. 新建传输请求
    0. 不使用传输请求（本地对象）

  请选择 [0-3]: 1
  ✓ 统一传输请求: DEVK901362（后续所有对象共用此请求号）

  ── [1/3] Z_STATUS (domain) ──
  ✓ 锁定成功（对象已绑定传输请求: DEVK901362）
  ✓ 源代码写入成功
  ✓ 解锁成功
  ✓ 语法检查通过
  ✓ 激活成功

  ── [2/3] ZCL_MY_CLASS (class) ──
  ✓ 锁定成功（对象已绑定传输请求: DEVK901362）
  ✓ 源代码写入成功
  ✓ 解锁成功
  ✓ 语法检查通过
  ✓ 激活成功

  ── [3/3] ZMY_REPORT (report) ──
  ✓ 锁定成功（使用统一传输请求: DEVK901362）
  ✓ 源代码写入成功
  ✓ 解锁成功
  ✗ 语法检查未通过! 1 个错误
     [错误] 行 10: Field "XXX" is unknown
  ⊘ 跳过（标记为 failed）

  ============================================================
  批量同步完成
  ============================================================
    ✓ 成功:  Z_STATUS, ZCL_MY_CLASS
    ✗ 失败:  ZMY_REPORT (语法错误，行 10)
    ⊘ 跳过:  (无)
    清单已更新: ./project/manifest.json
```

> [!tip] 指定 `--corr_nr` 跳过交互
> 如果已知传输请求号，使用 `--corr_nr` 参数可以直接跳过交互选择：
> ```bash
> python main.py sync --all --path ./project --corr_nr DEVK901362
> ```
> 此时所有未绑定请求号的对象都会使用指定的请求号，**全程零交互**。

---

### 4.3 `refresh` — 刷新清单状态（新增）

#### 命令格式

```bash
python main.py refresh --path <项目根目录>
```

#### 执行流程

```
读取 manifest.json
逐个重新查询 SAP info
更新每个对象的 system_status 和 corr_nr
（不修改 last_sync 和 last_sync_result）
输出变更摘要
```

#### 使用场景

- 其他人修改了 SAP 端的对象
- 传输请求状态发生变化（释放、导入等）
- 需要确认当前系统状态但不想执行同步

#### 输出示例

```
============================================================
  sap-cli 清单刷新
============================================================
  项目路径: ./project
  清单对象: 5

  → 正在查询 SAP 系统状态...
  ✓ Z_STATUS           (domain)     active   corr: DEVK901362 (未变化)
  ✓ ZIF_MY_INTERFACE   (interface)  active   corr: DEVK901362 (未变化)
  ~ ZCL_MY_CLASS       (class)      inactive corr: DEVK901362 (状态变更: active → inactive)
  ✓ ZMY_REPORT         (report)     inactive corr: null       (未变化)
  ✓ ZGROUP/Z_MY_FUNC   (function)   active   corr: DEVK901362 (未变化)

  ✓ 刷新完成
     变更: 1 个 | 未变化: 4 个
```

---

### 4.4 `create` — 变更：自动写入清单

#### 变更内容

- 新增 `--path` 参数：指向项目根目录
- 创建成功后：自动在 `manifest.json` 中新增一条记录

#### 新增的清单记录

```json
{
  "ZCL_NEW_CLASS": {
    "type": "class",
    "file": "classes/zcl_new_class.abap",
    "system_status": "active",
    "corr_nr": "DEVK901362",
    "depends_on": [],
    "last_sync": "2026-05-25T14:00:00",
    "last_sync_result": "success"
  }
}
```

#### 向后兼容

- 如果未指定 `--path`，或指定目录下没有 `manifest.json`：仅创建对象，不写清单
- 现有不含 `--path` 的用法不受影响

---

### 4.5 `delete` — 变更：从清单移除

#### 变更内容

- 新增 `--path` 参数：指向项目根目录
- 删除成功后：从 `manifest.json` 中移除该对象记录

#### 向后兼容

- 如果未指定 `--path`，或指定目录下没有 `manifest.json`：仅删除对象，不更新清单

---

### 4.6 `sync`（单对象） — 变更：操作后更新清单

#### 变更内容

- 新增 `--path` 参数：指向项目根目录（可选）
- sync 成功或失败后：更新 `manifest.json` 中对应对象的记录

#### 向后兼容

- 如果未指定 `--path`，或指定目录下没有 `manifest.json`：行为与现有完全一致

## 5. 依赖排序策略

### 5.1 类型默认优先级

无显式 `depends_on` 时，按类型优先级排序：

| 优先级 | 数值 | 类型 | 说明 |
|--------|------|------|------|
| 1 | 10 | `domain` | 基础域定义 |
| 2 | 20 | `dataelement` | 依赖 domain |
| 3 | 30 | `table` | 依赖 dataelement |
| 4 | 40 | `tabletype` | 依赖 table |
| 5 | 50 | `interface` | 接口定义 |
| 6 | 60 | `class` | 可能实现 interface |
| 7 | 70 | `function` | 函数模块 |
| 8 | 80 | `report` | 程序，可能引用以上所有 |

### 5.2 排序算法

采用拓扑排序（Kahn 算法）：

```
1. 以 manifest 中所有对象为节点
2. 建立有向边:
   - 显式依赖: depends_on 中列出的对象 → 当前对象
   - 类型默认优先级: 仅当两个对象之间没有显式依赖时作为 tie-breaker
3. 执行 Kahn 拓扑排序
4. 检测循环依赖 → 若存在未入队的节点则报错，输出循环链
```

### 5.3 依赖失败传播

批量 `sync` 时，若对象 A 依赖对象 B，而 B 同步失败：

```
A.depends_on = ["B"]
B.last_sync_result = "failed"

→ A 自动跳过，标记 last_sync_result: "skipped"
→ 依赖 A 的对象同样跳过（级联跳过）
```

## 6. 边界情况处理

| 场景 | 处理方式 |
|------|---------|
| 本地新增了 .abap 文件但清单中没有 | `sync --all` 时提示: "N 个未纳入清单的文件"，建议先执行 `create` |
| 清单中有对象但本地文件被删了 | `sync --all` 时警告并跳过该对象 |
| `manifest.json` 不存在 | `sync --all` 报错，提示先执行 `init` |
| 依赖对象 sync 失败 | 跳过所有依赖它的对象（级联标记 skipped） |
| 循环依赖 | 检测到后报错，输出循环链中的对象名 |
| 非项目目录（无子目录结构） | `init` 时只扫描当前目录下的 `.abap` 文件 |
| SAP 连接中断 | 标记已处理的对象，输出中断位置，下次可从断点继续 |
| `manifest.json` 版本不匹配 | 提示版本不兼容，建议重新 `init` |
| 部分对象已绑定请求号，部分未绑定 | 已绑定的使用自身请求号，未绑定的使用预选的统一请求号 |
| 全部对象都是本地对象（$TMP） | 无需传输请求，直接执行，零交互 |
| 指定了 `--corr_nr` 但部分对象已绑定其他请求号 | 已绑定的使用自身请求号（不受 `--corr_nr` 覆盖） |

## 7. 项目生命周期

```
┌─────────────────────────────────────────────────────────┐
│                                                         │
│  init ──────────────────────────────────────────────    │
│  │ 扫描本地文件 → 查询 SAP → 生成 manifest.json         │
│  │                                                      │
│  ▼                                                      │
│  create（新增对象时） ────────────────────────────────   │
│  │ 在 SAP 创建 → 自动写入 manifest                      │
│  │                                                      │
│  ▼                                                      │
│  sync --all（日常同步）─────────────────────────────    │
│  │ 读 manifest → 拓扑排序 → 逐个 sync → 更新 manifest  │
│  │                                                      │
│  ▼                                                      │
│  refresh（SAP 端有变化时）────────────────────────────  │
│    重新查询 SAP → 更新 manifest 中的状态字段             │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

> [!tip] 典型工作流
> ```bash
> # 1. 首次使用：初始化项目清单
> python main.py init --path ./my_project
>
> # 2. 日常开发：新增对象
> python main.py create --name ZCL_NEW --type class --path ./my_project --description "新类"
>
> # 3. 日常开发：修改本地 .abap 文件后，批量同步
> python main.py sync --all --path ./my_project
>
> # 4. 如需查看执行计划（不实际操作）
> python main.py sync --all --path ./my_project --dry-run
>
> # 5. 其他人修改了 SAP 端对象后，刷新清单
> python main.py refresh --path ./my_project
> ```

## 8. 模块设计（实现层面）

### 8.1 新增模块

| 模块 | 职责 |
|------|------|
| `sapcli/manifest.py` | 清单文件的读取、写入、查询、更新 |
| `sapcli/scanner.py` | 扫描本地目录，识别对象名和类型 |
| `sapcli/sorter.py` | 拓扑排序，依赖检测 |

### 8.2 清单模块 (`manifest.py`) 接口

```python
@dataclass
class ManifestEntry:
    name: str
    type: str
    file: str
    system_status: str          # "active" / "inactive" / "not_exists"
    corr_nr: str | None
    depends_on: list[str]
    last_sync: str | None       # ISO timestamp
    last_sync_result: str       # "success" / "failed" / "pending"

class Manifest:
    version: int
    last_init: str | None
    last_refresh: str | None
    objects: dict[str, ManifestEntry]

    @classmethod
    def load(cls, project_path: str) -> "Manifest": ...
    def save(self) -> None: ...
    def upsert(self, entry: ManifestEntry) -> None: ...
    def remove(self, name: str) -> None: ...
    def get(self, name: str) -> ManifestEntry | None: ...
    def pending_objects(self) -> list[ManifestEntry]: ...
```

### 8.3 扫描模块 (`scanner.py`) 接口

```python
DIRECTORY_TYPE_MAP = {
    "reports": "report",
    "classes": "class",
    "interfaces": "interface",
    "functions": "function",
    "domains": "domain",
    "dataelements": "dataelement",
    "tables": "table",
    "tabletypes": "tabletype",
}

@dataclass
class ScannedObject:
    name: str           # 大写对象名，function 类型含 /
    type: str           # 对象类型
    file: str           # 相对于项目根目录的路径

def scan_project(project_path: str) -> list[ScannedObject]: ...
```

### 8.4 排序模块 (`sorter.py`) 接口

```python
TYPE_PRIORITY = {
    "domain": 10,
    "dataelement": 20,
    "table": 30,
    "tabletype": 40,
    "interface": 50,
    "class": 60,
    "function": 70,
    "report": 80,
}

class CyclicDependencyError(SapCliError): ...

def topological_sort(
    objects: list[ManifestEntry],
) -> list[ManifestEntry]: ...
# → 按 depends_on + TYPE_PRIORITY 排序
# → 检测循环依赖，抛出 CyclicDependencyError
```

## 9. 相关笔记

- [[sap-cli/doc/sap-cli使用指南|sap-cli 使用指南]] — 现有命令的使用说明
- [[sap-cli/doc/技术说明|技术说明]] — 技术架构与模块设计
- [[sap-cli/doc/ADT/03.修改代码-原理|修改代码原理]] — 锁定/编辑/激活工作流