cobol-java-v3/README.md

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

项目性质：新规（从零开发的新作品）

---

项目概述

自动解析 COBOL 源码，生成覆盖全分支路径的测试数据，分别运行 COBOL 和 Java/Spark 两个版本，逐字段比对输出，判定迁移正确性。

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

整体功能说明

核心能力

功能模块	说明
COBOL源码解析	自动解析DATA DIVISION和PROCEDURE DIVISION，构建分支树
测试数据生成	基于分支覆盖的测试数据自动生成（规则引擎+LLM）
双管道验证	支持非DB（flat file）和DB（SQLite）两种验证模式
覆盖率分析	静态分支覆盖 + 动态gcov覆盖，生成HTML报告
AI辅助	LLM驱动的程序分类和测试策略生成

工作流程

1. 白盒分析：cobol_testgen 静态解析COBOL，生成测试数据
2. 黑盒生成：black-box-data-create 使用DeepSeek LLM生成测试数据
3. 全流程验证：run.py 组合白盒+黑盒，输出最终测试数据

效果总结（核心指标摘要）

指标	传统方式	本平台	提升
单程序验证时间	2-3天	10分钟	99%+
分支覆盖率	30-50%	75%+	50%+
回归测试时间	1-2周	1小时	99%+
测试数据生成	手工编写	自动生成	100%自动化

团队分工

角色	职责
架构设计	系统架构设计、技术选型、核心算法开发
AI开发	LLM集成、提示词工程、AI辅助测试策略
测试开发	测试框架搭建、测试数据生成、覆盖率分析
文档编写	技术文档、设计文档、用户手册

规模与技术难度自我评估

项目规模

指标	数量
源码行数	~15,000行
测试文件	80+
基准程序	43个COBOL程序
文档页数	200+

技术难度

难度项	等级	说明
COBOL语法解析	⭐⭐⭐⭐	支持固定/自由格式，Lark语法解析
分支路径枚举	⭐⭐⭐⭐⭐	MC/DC条件分析，O(N)线性算法
双管道验证	⭐⭐⭐⭐	非DB+DB两种模式自动路由
AI集成	⭐⭐⭐	DeepSeek LLM驱动测试策略
覆盖率分析	⭐⭐⭐	静态+动态覆盖率，HTML报告生成

---

快速开始

# 安装依赖
pip install lark pathlib pyyaml

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

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

# 单程序运行（自动路由：含 EXEC SQL → DB 管道，否则非 DB）
python -m cobol_testgen ../cobol-tna-system/src/KIN01INP.cbl

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

先跑白盒 cobol_testgen（静态分析 + 测试数据），成功后跑黑盒 black-box-data-create（DeepSeek LLM 生成 JSON/SQL）：

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

# 只查看将执行的命令，不真正运行
python run.py --design ... --output ... --dry-run

• 参数 --design / --source / --file-db-md / --cpy / --db-md / --output 为必需项，--api-key / --model / --rules / --max-tokens 可选透传给黑盒。
• 两步输出到同一 --output 根目录：白盒写 output/<程序ID>/main/...，黑盒写 output/<程序ID>/g{N}/...。
• 任一步失败即停止并返回该步退出码。

架构

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

两条管道自动路由：

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

文档索引

文档	说明
DESIGN.md	设计文档（场景价值、范式图、Agent架构、系统架构）
SETUP.md	环境搭建、运行指南、检查清单（含 DB 管道）
docs/v3-理解文档.md	系统架构、组件说明、数据流（中文，457 行）
docs/detailed-design/	V3 详细设计 (9个文档)
docs/development-paradigm.md	开发范式流程图
docs/test-report.md	测试报告
docs/changelog-v1-to-v3.md	V1→V3 演进记录
docs/module-interfaces.md	模块接口定义
CONTRIBUTING.md	贡献指南
_AI_USAGE_LOG.md	AI 使用日志
AGENTS.md	AI 协作方式与项目说明

核心命令

# 非 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> runtime/

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

# 黑盒数据生成
python black-box-data-create/main.py --design "詳細設計書_xxxx.md" --source "xxxx.cbl" --file-db-md "COPY句定義書.md" --cpy "cpy" --db-md "DB定義書.md" --output "output"

依赖

• Python 3.12+ + lark, pyyaml
• GnuCOBOL 3.2.0 (GC32-BDB-SP1，含 DB2/SQLite 支持)
• gixsql (已 vendored 在 gixsql/ 目录)
• DeepSeek API (可选，用于LLM测试策略生成)

环境要求

组件	要求
OS	Windows 10/11
Python	3.12+
GnuCOBOL	3.2.0
磁盘	≥ 500MB