hangshuo652/cobol-java-v3

Fork 0

Files

T

tmm621 8bfd8dd854 docs: 更新 run.py 黑盒全流程说明与运行时注意要点

2026-09-13 16:36:43 +08:00

15 KiB

Raw Blame History

COBOL → Java/Spark 迁移验证平台 v3

项目性质：新规（新开发，非升级）

AI辅助的COBOL程序迁移验证工具，通过白盒+黑盒双管道自动生成测试数据，验证COBOL程序向Java/Spark迁移的正确性。

白盒管道：静态解析COBOL源码，基于分支覆盖自动生成测试数据
黑盒管道：解析詳細設計書/COPY句定義書/DB定義書，LLM生成JSON/SQL测试数据

支持 非 DB（flat file I-O）和 DB（EXEC SQL → gixsql + SQLite）两条平行管道。

项目概述

业务场景

大型企业在进行COBOL向Java/Spark迁移时，面临以下核心挑战：

挑战	说明
验证成本高	人工逐行比对COBOL与Java输出，耗时数周
覆盖不全	手工测试难以覆盖所有分支路径，遗漏边界条件
回归风险大	修改后无法快速验证功能一致性

核心功能

本平台通过AI辅助自动化测试，实现：

功能	说明
白盒分析	静态解析COBOL源码，自动识别分支路径，生成覆盖全路径的测试数据
黑盒生成	解析設計書自动识别程序模式（16种PGMパターン），LLM生成テストデータ
双管道验证	白盒+黑盒并行运行，分别验证COBOL和Java/Spark输出
覆盖率分析	静态分支覆盖 + 动态gcov覆盖，生成中文HTML报告
多KEY测试	自动验证复合KEY的比较正确性

技术特点

非阻塞路径枚举: O(N) 算法替代 O(2^N) 爆炸
MC/DC 条件覆盖: 支持 AND/OR/NOT 复合条件
DB 种子键一致性: WHERE 宿主变量 MOVE 链解析
中文 HTML 报告: 全中文覆盖率报告
多KEY测试: 自动验证复合KEY的比较正确性
PGMパターン匹配: 16种程序模式自动识别和规则匹配

价值量化

指标	传统方式	本平台	提升
单程序验证时间	2-3天	10分钟	99%+
分支覆盖率	30-50%	75%+	50%+
回归测试时间	1-2周	1小时	99%+

双管道验证

白盒管道（cobol_testgen）

基于静态分析的测试数据生成：

COBOL源码 → 预处理 → 分支树构建 → 路径枚举 → 约束求解 → 测试数据生成

步骤	说明
源码解析	Lark Earley parser 解析 COBOL 语法
分支树构建	识别 IF/EVALUATE/PERFORM/SEARCH 等分支结构
路径枚举	O(N) MC/DC 算法生成覆盖路径
约束求解	为每条路径生成满足条件的输入数据
数据输出	JSON（flat file）或 SQL（DB）格式

黑盒管道（black-box-data-create）

基于詳細設計書的LLM数据生成：

詳細設計書 + COPY句定義書 + DB定義書 + COBOL源码
    ↓
InputParser → RuleLoader → PromptBuilder → DeepSeek API → OutputWriter
    ↓
output/{プログラムID}/g{N}/{プログラムID}_g{N}.json
output/{プログラムID}/g{N}/{プログラムID}_g{N}.sql

步骤	说明
設計書解析	解析詳細設計書中的入出力定義、処理内容
COPYBOOK解析	解析COPY句定義書中的レコード構造
DB定義解析	解析DB定義書中的テーブル構造
パターン匹配	按PGMパターン（マッチング/DB更新/振り分け等）选择规则
LLM生成	DeepSeek API生成テストデータ
多KEY测试	生成各KEY変化的追加データ，验证KEY比較正确性

验证流程

run.py
  ├── 步骤1: black-box-data-create（黑盒）
  │     ├── 解析設計書 + COPY + DB定義
  │     ├── LLM 生成 JSON/SQL
  │     └── 输出到 output/{程序ID}/black_box/g{N}/
  │
  └── 步骤2: cobol_testgen（白盒 + 黑盒比对）
        ├── 静态分析 + 白盒测试数据生成
        ├── 编译运行 COBOL + Java 比对（白盒组）
        ├── 读取黑盒 JSON → 编译运行 + Java 比对（黑盒组）
        ├── gcov 覆盖率收集（仅白盒）
        └── 合并报告 output/{程序ID}/{程序ID}_测试报告.md

成果摘要

开发成果

指标	数量
核心代码	cobol_testgen 18 个模块，~13,700 行
黑盒模块	black-box-data-create 22 个模块，~2,300 行
测试文件	96 个测试文件，885 个测试用例
基准程序	40 个基准目录，83 个 COBOL 源程序
对应PGMパターン	16 种
修复数量	19 个关键 bug 修复
设计文档	10 个 V3 详细设计文档

覆盖率

类型	覆盖率
分支覆盖率	75%
条件覆盖率	75%
测试通过率	820 通过 / 0 失败（885 收集，65 跳过）

技术亮点

Lark 语法解析: 使用 Earley parser 解析 COBOL 语法
MC/DC 条件覆盖: 支持复合条件的最小条件覆盖
双管道架构: 白盒（静态分析）+ 黑盒（LLM生成）并行运行
多KEY测试: 自动验证复合KEY的比较正确性
PGMパターン匹配: 16种程序模式自动识别和规则匹配
AI 辅助: DeepSeek LLM 驱动的程序分类和测试策略

团队分工

AI 辅助 (DeepSeek)

任务	负责内容
代码开发	核心引擎、测试用例、文档编写
测试执行	运行测试套件、收集覆盖率数据
文档生成	详细设计文档、测试报告、README
代码审查	自动触发 code-review skill

人工审查

任务	负责内容
需求确认	验证功能符合竞赛要求
代码审查	审查 AI 生成的代码质量
验收测试	执行端到端验证
最终提交	推送到主分支、提交成果物

技术难度

难点分析

难点	说明	解决方案
COBOL 语法复杂性	支持 33+ 种语句类型	Lark Earley parser + 状态机
路径爆炸	复合条件导致路径指数增长	O(N) MC/DC 算法
DB 管道一致性	种子键与运行时查询键不一致	MOVE 链解析 + 列名归一化
覆盖率标记	复合条件分支标记错误	条件树 + evaluate_tree
設計書解析	詳細設計書格式多样，表格解析困难	Markdown表格解析 + 正则匹配
PGMパターン匹配	24种程序模式自动识别	规则文件 + 关键词匹配
多KEY测试	复合KEY的变形数据生成	自动识别KEY项目 + 变形生成
LLM输出稳定性	API返回格式不稳定	3回重试 + JSON容错解析

已知限制

限制	影响	状态
条件覆盖率 75%	`_FUNC_MOD` 合成函数不可匹配	待优化
无 Java 比对管道	仅验证 COBOL 输出	规划中
DB 管道需 gixsql	依赖外部工具	已 vendored
黑盒依赖 DeepSeek API	需要网络连接和 API Key	已实现重试机制
黑盒仅支持日语設計書	中文設計書需适配	待优化

快速开始

环境要求

组件	版本	说明
Python	3.12+	主要开发语言
GnuCOBOL	3.2.0	COBOL 编译器（可选，用于编译运行）
pip	最新版	Python 包管理器

安装步骤

# 1. 克隆仓库
git clone https://gittea.dev/<your-account>/2026Technology-Competition.git
cd 2026Technology-Competition

# 2. 安装 Python 依赖（完整）
pip install lark pathlib pyyaml fastapi uvicorn httpx

# 3. 安装测试依赖（可选）
pip install pytest playwright

# 4. 安装 Playwright 浏览器驱动（可选，用于 E2E 测试）
playwright install chromium

# 5. 验证安装
python -c "from cobol_testgen import extract_structure; print('安装成功')"

注意：

核心功能只需 lark pathlib pyyaml

Web 服务需要 fastapi uvicorn

E2E 测试需要 playwright + 浏览器驱动

DB 管道需要 gixsql（已 vendored 在 gixsql/ 目录）

运行测试

# 运行所有单元测试
python -m pytest tests/ -v

# 运行核心引擎测试
python -m pytest tests/cobol_testgen/ -v

# 运行非 DB 回归测试
python test-data/s15_coverage_verification.py

# 运行 DB 端到端测试（需设置环境变量，见 SETUP.md）
python test-data/s30_db_e2e.py

# 运行 Web E2E 测试（需安装 playwright）
python -m pytest tests/test_web_e2e.py -v

# 运行业务逻辑 E2E 测试（需安装 playwright + WSL）
python -m pytest tests/test_biz_e2e.py -v

测试说明：

部分测试依赖外部数据（jcl-cobol-git 目录），会自动跳过

E2E 测试需要安装 playwright 和浏览器驱动

Web E2E 测试需要启动 Web 服务：python -m uvicorn web.api:app --host 127.0.0.1 --port 8000

使用示例

# 使用 sample 目录中的示例数据运行
python -m cobol_testgen sample/simple.cbl

# 生成测试数据
python -c "
from cobol_testgen import extract_structure, generate_data
src = open('sample/simple.cbl', encoding='utf-8').read()
st = extract_structure(src)
recs = generate_data(src, st)
print(f'生成 {len(recs)} 条测试记录')
"

全流程数据生成（run.py）

黑盒 LLM 数据生成 + 白盒/黑盒运行比对一键执行（先黑盒 → 再白盒+黑盒）：

# 使用环境变量指定路径（推荐）
export COBOL_TNA_ROOT=/path/to/cobol-tna-system  # Linux/macOS
# set COBOL_TNA_ROOT=D:\cobol-tna-system          # Windows

python run.py \
    --design "$COBOL_TNA_ROOT/詳細設計書/詳細設計書_ZAN04MAT.md" \
    --source "$COBOL_TNA_ROOT/src/ZAN04MAT.cbl" \
    --file-db-md "$COBOL_TNA_ROOT/詳細設計書/COPY句定義書.md" \
    --cpy "$COBOL_TNA_ROOT/cpy" \
    --db-md "$COBOL_TNA_ROOT/詳細設計書/DB定義書.md" \
    --output "./output"

参数	必需	说明
`--design`	✓	詳細設計書 .md パス
`--source`	✓	COBOL ソース .cbl パス
`--file-db-md`	✓	COPY句定義書 .md パス
`--cpy`	✓	COPYBOOK 格納ディレクトリ
`--db-md`	✓	DB定義書 .md パス
`--output`		出力ディレクトリ（デフォルト: output）
`--api-key`		DeepSeek API Key（未指定则读环境变量/配置文件）
`--model`		モデル名（デフォルト: deepseek-v4-flash）
`--no-black-box`		跳过黑盒生成，仅跑白盒 cobol_testgen
`--dry-run`		只打印要执行的命令，不实际执行

运行时注意要点

执行顺序：run.py 先跑步骤1黑盒生成，再跑步骤2白盒+黑盒比对。cobol_testgen 的 --black-box 只读取已生成的黑盒 JSON，不会自行生成数据；因此必须先生成黑盒数据。
API Key：步骤1 需要有效的 DeepSeek API Key，优先级为命令行 --api-key > 环境变量 DEEPSEEK_API_KEY > black-box-data-create/config.json。Key 缺失/无效会返回 401 Authorization Required，与模型版本无关。Key 以 sk- 开头，程序会自动加 Bearer 前缀（不要手写 Bearer）。
失败即停：步骤1 失败（如 401、网络错误、JSON 解析失败）会立即返回非 0 退出码，不再执行步骤2。请先解决 Key/网络问题再重跑。
黑盒目录：黑盒 JSON 输出到 output/{程序ID}/black_box/g{N}/{程序ID}_g{N}.json；步骤2 以 --black-box output/{程序ID} 读取，程序会自动在其中查找 black_box/g*/。
覆盖率隔离：黑盒运行不参与 gcov 覆盖率统计，coverage/ 与报告中的覆盖率数字只反映白盒。
目录隔离：黑盒产物只写在 output/{程序ID}/black_box/{组}/...，不会覆盖白盒的 cobol/main、run_skip、coverage。
JDK 可选：未发现对应 JavaSrc/*Main.java 时，Java 比对自动跳过，仅执行 COBOL 并生成报告。
重复执行安全：重复运行会覆盖同名输出；黑盒各组使用独立工作目录，组间数据不会串扰。
cmd 与 PowerShell 差异：cmd 用 ^ 续行、PowerShell 用 `；在 cmd 中误用反引号会被当作参数导致 unrecognized arguments。

输出目录结构

output/
└── ZAN04MAT/
    ├── cobol/main/              # 白盒输出（json / input / output）
    ├── cobol/run_skip/          # Skip 数据集（主 FD 空文件）
    ├── java/main/output/        # 白盒 Java 出力
    ├── black_box/g1/            # 黑盒组1
    │   ├── ZAN04MAT_g1.json     # 黑盒原始数据
    │   ├── cobol/               # 黑盒 COBOL 入力/出力
    │   └── java/output/         # 黑盒 Java 出力
    ├── black_box/g2/            # 黑盒组2（同上）
    ├── coverage/                # 覆盖率 HTML（仅白盒）
    └── ZAN04MAT_测试报告.md      # 白盒组 + 黑盒组合并报告

架构

CLI → orchestrator / orchestrator_db
        │
  ┌─────┼──────┬──────────┬──────────┐
  ▼     ▼      ▼          ▼          ▼
cobol_testgen  runners   comparator  agents
(数据生成)    (编译运行)  (比对验证)  (LLM)

两条管道自动路由：

非 DB：cobc 编译 → flat file 二进制比对
DB：gixpp ESQL 预处理 → cobc -l gixsql 编译 → SQLite 表比对

文档索引

文档	说明
`SETUP.md`	环境搭建、运行指南、检查清单（含 DB 管道）
`DESIGN.md`	场景与价值、开发范式、Agent架构、系统架构
`docs/SCENE_VALUE.md`	业务场景、痛点分析、用户场景、价值量化
`docs/detailed-design/`	V3 详细设计文档（10个）
`docs/development-paradigm.md`	开发范式流程图
`tests/test-report.md`	测试报告
`tests/coverage/`	覆盖率报告
`_AI_USAGE_LOG.md`	AI 使用日志
`AGENTS.md`	项目指令文档
`sample/`	示例数据

核心命令

# 非 DB 全量覆盖率报告
python test-data/s25_per_program_report.py

# DB 端到端测试
python test-data/s30_db_e2e.py

# 带 gcov 覆盖率的单程序运行
python -m cobol_testgen --gcov <cobol_src> output/

# 诊断脚本
python diagnose_db2.py          # DB 全流程
python diagnose_kind8dbrun.py   # DB 编译运行

# 黑盒数据生成（使用环境变量指定路径）
python black-box-data-create/main.py \
    --design "$COBOL_TNA_ROOT/詳細設計書/詳細設計書_xxxx.md" \
    --source "$COBOL_TNA_ROOT/src/xxxx.cbl" \
    --file-db-md "$COBOL_TNA_ROOT/詳細設計書/COPY句定義書.md" \
    --cpy "$COBOL_TNA_ROOT/cpy" \
    --db-md "$COBOL_TNA_ROOT/詳細設計書/DB定義書.md" \
    --output "./output"

依赖

Python 3.12+ + lark, pyyaml
GnuCOBOL 3.2.0 (GC32-BDB-SP1，含 DB2/SQLite 支持)
gixsql (已 vendored 在 gixsql/ 目录)

15 KiB Raw Blame History Unescape Escape