v1.0
This commit is contained in:
@@ -0,0 +1,319 @@
|
||||
# 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 代码（添加映射条目）
|
||||
Reference in New Issue
Block a user