# COBOL 测试数据生成 Agent 设计文档

## 背景

旧 COBOL 项目通过 Java 重写。需要基于 Python 新建一个测试数据生成 Agent，根据详细设计书自动生成 COBOL 程序的测试数据（JSON/SQL），通过 DeepSeek v4 Flash API 由 AI 生成具体数据内容。

---

## 架构概览

采用**线性管道架构**，模块化设计，便于后续追加规则和维护：

```
InputParser → RuleLoader → PromptBuilder → APIClient → OutputWriter
```

- **Python 侧**：负责解析结构化信息、建立映射关系、组装 prompt
- **AI 侧**：接收 prompt，根据规则生成具体的测试数据 JSON/SQL

---

## 目录结构

```
D:\jcl-cobol-data-create/
├── agent/
│   ├── __init__.py
│   ├── input_parser.py      # 输入解析器
│   ├── rule_loader.py       # 规则加载器
│   ├── prompt_builder.py    # Prompt 构建器
│   ├── api_client.py        # API 客户端（DeepSeek）
│   └── output_writer.py     # 输出写入器
├── rules/
│   ├── pgm_pattern/         # PGM模式规则 .md
│   │   ├── マッチング(1-1).md
│   │   ├── マッチング(1-N).md
│   │   └── ...（后续追加，无需改代码）
│   └── special_feature/     # 特殊功能规则 .md
│       └── 条件分支.md
├── layout/                  # 文档模板（参考用）
│   └── JSON格式说明v2.0.md
├── output/                  # 生成输出（运行时自动创建）
│   └── {プログラムID}/
│       ├── g1/
│       └── g2/
├── main.py                  # CLI 入口 + generate() 库函数
├── requirements.txt
└── README.md
```

---

## 模块详细设计

### 1. InputParser（输入解析器）

**职责**：解析所有输入文件，提取结构化数据。

**输入**：
- `a` 詳細設計書 .md
- `b` ソース .cbl 文本文件
- `c` 文件/DB 构造 .md（文件定義書 + COPY句定義書）
- `d` COPY 存放路径
- `e` DB 结构 .md

**输出**：结构化的程序元数据对象，包含：

#### 1.1 基本情報
- プログラムID, プログラム名, PGMタイプ（メイン/サブ）, PGMパターン
- 解析方法：定位 `# 行` 列 = `PGMパターン` 的行，取 `内容` 列的值

#### 1.2 使用ファイル一覧
- 每个文件的：識別子, DD名, I/O, COPY群, 媒体（PS=文件, DB=DB）
- 判定输入类型：遍历 I/O="I" 的行，根据 `媒体` 列判定
  - 全是 PS → 文件输入
  - 包含 DB → DB 输入
  - 都有 → 混合输入

#### 1.3 COPYBOOK 解析 + REPLACING 映射
- 从 .cbl 源码的 FD 块中提取 `COPY xxx REPLACING ==(A)== BY ==識別子==`
- 建立映射：`識別子(R01) → COPY名(ZAN01REC) → 替换前缀(R01-)`
- 读取 COPYBOOK 文件，应用 `(A)` → 前缀替换，得到实际字段名和 PIC 定义
- 输出示例：`R01-APPL-ID | X(8) | 8`

#### 1.4 キー項目一覧
- 排序条件、匹配键信息

#### 1.5 処理詳細
- 完整原文（不做解析，保留原样）

#### 1.6 出力レコード定義
- 输出文件的项目定义和设定元信息

#### 1.7 DB 定义（如涉及）
- 从 DB 定义书 .md 中提取表的字段定义、类型、PK 信息

---

### 2. RuleLoader（规则加载器）

**职责**：根据程序特征匹配对应的数据生成规则。

#### 2.1 PGM 模式规则匹配
PGMパターン 值到规则文件名的映射：

| PGMパターン | 规则文件 |
|------------|---------|
| マッチング(1:1) | マッチング(1-1).md |
| マッチング(1:N) | マッチング(1-N).md |
| マッチング(M:N) | （待添加） |
| レイアウト編集のみ(GETPUT) | （待添加） |
| 項目チェック | （待添加） |
| 振り分け | （待添加） |
| キーブレイク | （待添加） |
| キーブレイク(集計、集約) | （待添加） |
| DB更新 | （待添加） |

- 未找到对应规则 → 报错并列出缺失的模式名
- 读取匹配到的 .md 全文
- 从规则中解析：组数、每组用途、每组的数据生成方法

#### 2.2 特殊功能检测
扫描 `処理詳細` 文本，根据预设关键词自动检测：

| 特殊功能 | 检测关键词 | 规则文件 |
|---------|-----------|---------|
| 条件分支 | `場合`, `EVALUATE`, `IF` | 条件分支.md |

- 扩展方式：在检测表中追加行，同时在 `rules/special_feature/` 下添加对应 .md

---

### 3. PromptBuilder（Prompt 构建器）

**职责**：将前两个模块的所有信息组装成结构化 API prompt。

**Prompt 结构**：

```
## 程序基本情報
- 程序ID: ZAN04MAT
- 程序名: 取消マッチング処理
- PGMパターン: マッチング(1:1)
- 输入类型: 文件

## 処理詳細
（詳細設計書の処理詳細全文）

## 入力ファイル/DB 構造
### 文件R01 (DD名: ZAN04R01, COPY: ZAN01REC)
| 字段名 | PIC | 字节数 |
| R01-APPL-ID | X(8) | 8 |
| R01-EMP-ID | X(8) | 8 |
...

## DBテーブル構造（如有）
### 表名: LEAVE_RECORDS
| 字段名 | 类型 | 最大长 | KEY |
...
- 主键: APPLICATION_ID

## 出力レコード定義
（詳細設計書の出力レコード定義全文）

## データ生成ルール
（匹配到的PGM模式规则 .md 全文）

## 特殊機能ルール（如有）
（条件分支.md 全文）

## 出力形式
- 文件输入类型 → JSON格式（遵循以下规则）
- DB输入类型 → SQL INSERT语句

### 字段值规则（PIC → JSON表示）
| PIC | JSON表示 | 例 |
|-----|---------|-----|
| PIC X(n) | 左对齐 + 空格填充 | "A0000001" |
| PIC 9(n) | 右对齐 + 前补零 | "00000101" |
| PIC S9(n) COMP-3 | 十进制数字 | "1234" |
| PIC S9(n) COMP | 十进制数字 | "300" |
| FILLER(纯保留) | 有辨识性模式 | "D000...001" |
| FILLER(业务保留) | 全空格或全零 | |

- COMP/COMP-3 类型字段输出**普通十进制数字符串**，不做特殊转换
- 字段名含语义关键词时（如 DATE="日期"、NAME="姓名"）生成符合实际含义的值

## 生成指示
- 需要生成的グループ数: 3
- 各グループの内容:
  - g1: 两端不匹配
  - g2: 反向两端不匹配
  - g3: 中间不匹配
- 出力: JSON（文件输入）
```

---

### 4. APIClient（API 客户端）

**职责**：调用 DeepSeek API，含重试逻辑。

**API 配置**：
- 地址：https://api.deepseek.com/chat/completions
- 模型：`deepseek-v4-flash`
- API Key：`sk-6156cccdc9c14d949cf5bfc5afc67a03`
- timeout：120 秒

**请求结构**：
```json
{
  "model": "deepseek-v4-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是COBOL程序测试数据生成专家。请严格按照规则生成测试数据。输出必须是可直接解析的JSON，不要包在markdown代码块中。"
    },
    {
      "role": "user",
      "content": "<PromptBuilder生成的完整prompt>"
    }
  ],
  "temperature": 0.3,
  "max_tokens": 8192
}
```

**重试逻辑**（最多 3 次）：
```
for i in 1..3:
    发送请求
    if 网络错误 || API返回错误:
        continue  # 重试
    if JSON解析失败:
        将错误信息追加到prompt中，重试
    if 成功:
        break
```
- 3 次全部失败 → 报错退出

---

### 5. OutputWriter（输出写入器）

**职责**：将 AI 返回的 JSON/SQL 保存为文件。

**输出规则**：
- 文件输入 → `output/{プログラムID}/g{组号}/{プログラムID}_g{组号}.json`
- DB 输入 → `output/{プログラムID}/g{组号}/{プログラムID}_g{组号}.sql`
- 混合输入 → 同文件夹下同时输出 `.json` 和 `.sql`

**输出格式**：
- JSON：遵循 `JSON格式说明v2.0.md` 规范，每个文件内含 `records` 数组
- SQL：标准 INSERT 语句

```
output/ZAN04MAT/
├── g1/
│   └── ZAN04MAT_g1.json
├── g2/
│   └── ZAN04MAT_g2.json
└── g3/
    └── ZAN04MAT_g3.json
```

**验证**：写入前校验 JSON 合法性，不合法时返回错误给 APIClient 触发重试。

---

### 6. main.py（入口）

**CLI 调用**：
```bash
python main.py \
  --design "詳細設計書_ZAN04MAT.md" \
  --source "src/ZAN04MAT.cbl" \
  --cpy "cpy/" \
  --db-def "DB定義書.md" \
  --output "output/"
```

**库调用**：
```python
from agent import generate

result = generate(
    design_md="詳細設計書_ZAN04MAT.md",
    source_cbl="src/ZAN04MAT.cbl",
    cpy_dir="cpy/",
    db_def_md="DB定義書.md",
    output_dir="output/"
)
```

---

## 依赖

- Python 3.9+
- `requests` — HTTP 客户端
- `openai` 或直接用 `requests` 调用 DeepSeek 兼容 API

```
requests>=2.28.0
```

---

## 扩展指南

### 追加 PGM 模式规则
1. 在 `rules/pgm_pattern/` 下创建新的 .md 文件
2. 文件名与 PGMパターン 值按约定匹配
3. 无需修改 Python 代码

### 追加特殊功能检测
1. 在 RuleLoader 的检测映射表中追加一行 `(关键词列表, 对应规则文件)`
2. 在 `rules/special_feature/` 下创建对应 .md
3. 需要改一行 Python 代码（添加映射条目）