14 KiB
14 KiB
V3系统总体设计
版本: v1.1 | 日期: 2026-08-24 本文档描述COBOL迁移验证平台V3的总体架构和模块设计。
一、系统概述
1.1 系统定位
COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验证COBOL程序向Java/Spark迁移的正确性。通过白盒+黑盒双管道自动生成测试数据，实现全分支路径覆盖验证。
1.2 核心能力
| 能力 | 说明 |
|---|---|
| 白盒分析 | 静态解析COBOL源码，自动识别分支路径，生成覆盖全路径的测试数据 |
| 黑盒生成 | 解析設計書自动识别程序模式（16种PGMパターン），LLM生成テストデータ |
| 双管道验证 | 白盒+黑盒并行运行，分别验证COBOL和Java/Spark输出 |
| 覆盖率分析 | 静态分支覆盖 + 动态gcov覆盖 |
| 多KEY测试 | 自动验证复合KEY的比较正确性 |
1.3 技术栈
| 组件 | 技术 |
|---|---|
| 语言 | Python 3.12+ |
| 解析器 | Lark (Earley parser) |
| COBOL编译 | GnuCOBOL 3.2.0 |
| DB管道 | gixsql + SQLite |
| AI模型 | DeepSeek |
| 测试框架 | pytest |
二、系统架构
2.1 架构图
┌─────────────────────────────────────────────────────────────────┐
│ V3系统架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 统一入口 (run.py) │ │
│ │ 白盒 cobol_testgen → 黑盒 black-box-data-create │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────┴────────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ 白盒管道 │ │ 黑盒管道 │ │
│ │ cobol_testgen │ │ black-box-data-create │ │
│ │ (静态分析+测试数据) │ │ (設計書解析+LLM生成) │ │
│ └──────────────────────────┘ └──────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ 编排层 │ │ 规则层 │ │
│ │ orchestrator_db.py │ │ rules/pgm_pattern/ │ │
│ └──────────────────────────┘ └──────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ 运行引擎 │ │ LLM引擎 │ │
│ │ runners/gixsql_runner │ │ DeepSeek API │ │
│ └──────────────────────────┘ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
2.2 分层架构
| 层级 | 模块 | 职责 |
|---|---|---|
| L1 数据层 | data/ | 共享数据模型 |
| L2 核心层 | cobol_testgen/, config/ | COBOL解析、配置管理 |
| L3 业务层 | hina/, agents/, comparator/, black-box-data-create/ | 分类、AI代理、比对、黑盒生成 |
| L4 编排层 | orchestrator*, runners/ | 流程编排、执行 |
| L5 接口层 | main.py, run.py, web/, __init__.py | 用户接口 |
二-B、黑盒模块设计
2B.1 模块概述
black-box-data-create 是基于詳細設計書的LLM数据生成模块，通过解析設計書/COPY句定義書/DB定義書，自动生成テストデータ。
2B.2 处理流程
詳細設計書 + COPY句定義書 + DB定義書 + COBOL源码
│
▼
InputParser: 解析設計書中的入出力定義、処理内容
│
▼
RuleLoader: 按PGMパターン匹配规则文件
│
▼
PromptBuilder: 组装DeepSeek API提示词
│
▼
APIClient: 调用DeepSeek API生成テストデータ
│
▼
OutputWriter: 输出JSON/SQL文件
2B.3 PGMパターン
| パターン | 说明 | 对应程序 |
|---|---|---|
| マッチング(1:1) | 1对1匹配 | KIN01INP, KIN02UPD |
| マッチング(1:N) | 1对多匹配 | KIN03EXP |
| マッチング(N:1) | 多对1匹配 | KIN04CHK |
| DB更新 | 数据库更新 | KIN08DBU |
| 振り分け(IF) | IF条件分支 | KIN05MAT |
| 振り分け(EVALUATE) | EVALUATE分支 | KIN07DAI |
| 項目チェック | 字段校验 | ZAN01CHK, ZAN02CHK |
| キーブレイク(集計) | KEY-break汇总 | SHA01SIF |
| キーブレイク(集約) | KEY-break聚合 | SHA02MNC |
| SELECT処理 | SELECT查询 | KYU04CAL |
| MERGE | 合并处理 | KIN06CLD |
| CSV→FB変換 | CSV转flat file | KIN09CSV |
2B.4 多KEY测试
对于复合KEY程序（如 A001+A002+A003），自动生成各KEY变形的追加データ：
| 变形类型 | 说明 |
|---|---|
| KEY1変更 | 仅改变KEY1，验证KEY1比较正确性 |
| KEY2変更 | 仅改变KEY2，验证KEY2比较正确性 |
| KEY3変更 | 仅改变KEY3，验证KEY3比较正确性 |
2B.5 模块文件
| 文件 | 职责 |
|---|---|
| agent/__init__.py | generate() 入口 |
| agent/models.py | 数据クラス定義 |
| agent/input_parser.py | 設計書 + COPYBOOK + DB定義解析 |
| agent/rule_loader.py | PGMパターン→ルール匹配 |
| agent/prompt_builder.py | API提示词组装 |
| agent/api_client.py | DeepSeek API调用（3回重试） |
| agent/output_writer.py | JSON/SQL文件输出 |
| main.py | CLI入口 |
三、模块清单
3.1 核心模块
| 模块 | 文件数 | 行数 | 职责 |
|---|---|---|---|
| cobol_testgen/ | 22 | ~8000 | COBOL解析、白盒测试数据生成 |
| black-box-data-create/ | 8 | ~5000 | 設計書解析、黑盒LLM数据生成 |
| orchestrator_db.py | 1 | 1334 | DB管道6步编排 |
| runners/ | 8 | ~600 | 编译运行引擎 |
| hina/ | 11 | ~2000 | HINA程序分类 |
| agents/ | 6 | ~800 | LLM代理 |
| comparator/ | 6 | ~400 | 字段比对 |
| config/ | 5 | ~300 | 配置管理 |
| report/ | 1 | ~200 | 报告生成 |
| run.py | 1 | 86 | 全流程统一入口 |
3.2 模块依赖关系
models.py (零依赖)
│
├── read.py (lark)
├── cond.py (stdlib)
├── core.py (cond)
├── design.py (models, cond, core)
├── coverage.py (models, cond)
├── output.py (file_io)
├── to_sql.py (stdlib)
├── runner.py (file_io)
├── flatfile.py (read, file_io)
│
└── __init__.py (所有上层模块)
black-box-data-create/
│
├── models.py (零依赖)
├── markdown_utils.py (stdlib)
├── input_parser.py (models, markdown_utils)
├── rule_loader.py (models)
├── prompt_builder.py (models)
├── api_client.py (requests)
├── output_writer.py (models)
│
└── __init__.py (所有上层模块)
四、数据流
4.1 非DB管道数据流
COBOL源码
│
▼
read.py: preprocess() + parse_data_division()
│
▼
core.py: build_branch_tree()
│
▼
design.py: enum_paths() + generate_records()
│
▼
output.py: output_json() + output_input_files()
│
▼
runners/cobol_runner.py: compile() + run()
│
▼
comparator/: compare_field()
│
▼
report/generator.py: generate_report()
4.2 DB管道数据流
COBOL源码 (含EXEC SQL)
│
▼
gixsql_runner.py: preprocess() + compile()
│
▼
orchestrator_db.py: step2_generate_inputs()
│
├── cobol_testgen: extract_structure + generate_data
├── to_sql.py: build_db_input()
└── flatfile.py: write_all_files()
│
▼
orchestrator_db.py: step3_run_cobol()
│
▼
orchestrator_db.py: step4_extract_intermediate()
│
▼
orchestrator_db.py: step5_run_java() (可选)
│
▼
orchestrator_db.py: step6_verify()
4.3 黑盒管道数据流
詳細設計書.md
│
▼
input_parser.py: 解析設計書 + COPY句定義書 + DB定義書
│
▼
rule_loader.py: PGMパターン匹配 → 选择规则文件
│
▼
prompt_builder.py: 组装API提示词
│
▼
api_client.py: DeepSeek API调用（3回重试）
│
▼
output_writer.py: 输出JSON/SQL文件
│
▼
output/{プログラムID}/g{N}/{プログラムID}_g{N}.json
output/{プログラムID}/g{N}/{プログラムID}_g{N}.sql
4.4 全流程数据流（run.py）
run.py
│
├── 步骤1: cobol_testgen（白盒）
│ ├── 静态分析 + 测试数据生成
│ ├── 编译运行 COBOL 程序
│ └── gcov 覆盖率收集
│
└── 步骤2: black-box-data-create（黑盒）
├── 解析設計書 + COPY + DB定義
├── LLM 生成 JSON/SQL
└── 输出到 output/{程序ID}/g{N}/
五、接口设计
5.1 公开API
# cobol_testgen/__init__.py
def extract_structure(
cobol_source: str,
copybook_dirs: list[str] = None
) -> dict:
"""解析COBOL源码，返回结构信息"""
pass
def generate_data(
cobol_source: str,
structure: dict,
copybook_dirs: list[str] = None
) -> list[dict]:
"""生成分支覆盖测试数据"""
pass
def main():
"""CLI入口"""
pass
# black-box-data-create/agent/__init__.py
def generate(
design_md: str,
source_cbl: str,
file_db_md: str,
cpy_dir: str,
db_md: str,
output_dir: str = "output",
api_key: str = None,
model: str = None,
rules_dir: str = None,
) -> dict:
"""黑盒数据生成入口"""
pass
5.2 配置接口
# config/__init__.py
@dataclass
class Config:
"""全局配置"""
project_name: str
copybook_paths: list[str]
dialect: str
llm_model: str
gcov_enabled: bool
# ... 更多字段
六、错误处理
6.1 错误分类
| 类别 | 示例 | 处理策略 |
|---|---|---|
| 解析错误 | COBOL语法不合法 | 抛出异常，返回错误信息 |
| 编译错误 | cobc编译失败 | 记录日志，跳过该程序 |
| 运行错误 | 程序执行异常 | 捕获异常，标记失败 |
| 超时错误 | 执行超时 | 强制终止，记录超时 |
| API错误 | DeepSeek API调用失败 | 3回重试，失败后跳过 |
| 設計書解析错误 | 設計書格式不正确 | 记录警告，使用默认值 |
6.2 容错机制
- 解析器超时：pipeline_bridge 3秒超时回退
- LLM失败：回退到规则引擎
- gcov失败：跳过覆盖率收集
- DB连接失败：重试或跳过
- API重试：DeepSeek API 3回重试机制
- JSON解析容错：支持非标准JSON格式
七、性能设计
7.1 性能指标
| 指标 | 目标 |
|---|---|
| 单程序解析 | < 5秒 |
| 测试数据生成 | < 30秒 |
| 编译运行 | < 60秒 |
| 覆盖率报告 | < 10秒 |
| 黑盒数据生成 | < 120秒（含API调用） |
7.2 优化策略
- 路径枚举：O(N)线性算法替代O(2^N)
- 并行执行：多场景gcov并行收集
- 缓存机制：LLM结果缓存
- 增量补充：质量门循环最多4次
- API重试：3回重试机制，避免单次失败
八、安全设计
8.1 输入验证
- COBOL源码：长度限制、编码检查
- 配置文件：YAML schema验证
- 文件路径：路径遍历防护
- 設計書：格式验证、大小写检查
8.2 资源限制
- LLM调用：最大成本限制
- 执行时间：超时强制终止
- 内存使用：大文件分块处理
- API限流：避免超过API配额
九、测试策略
9.1 测试层次
| 层次 | 覆盖率目标 | 工具 |
|---|---|---|
| 单元测试 | ≥ 90% | pytest |
| 集成测试 | ≥ 80% | pytest |
| 端到端测试 | 100%通过 | 自定义脚本 |
9.2 测试数据
- 43个COBOL基准程序
- 33+2种程序类型
- 58个电信测试程序
- 16种PGMパターン
- 24个黑盒测试程序
十、部署设计
10.1 运行环境
| 组件 | 要求 |
|---|---|
| OS | Windows 10/11 |
| Python | 3.12+ |
| GnuCOBOL | 3.2.0 |
| 磁盘 | ≥ 500MB |
10.2 安装步骤
# 1. 安装Python依赖
pip install lark pathlib pyyaml requests
# 2. 安装GnuCOBOL
# 下载GC32-BDB-SP1，添加到PATH
# 3. 验证安装
python -c "from cobol_testgen import extract_structure; print('OK')"
python -c "from blackbox.agent import generate; print('OK')"