hangshuo652
732a0bbdaa
从 feat/phase2-review-fixes 恢复: JIN05UPD, KYU02REG, KYU04CAL, KYU05DED, KYU06UPD, SHA02MNC, SHA03MNP, SHA04TWO, SHA06TWM, SHA07KBR
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驱动的程序分类和测试策略生成 |
工作流程
- 白盒分析：
cobol_testgen静态解析COBOL，生成测试数据 - 黑盒生成：
black-box-data-create使用DeepSeek LLM生成测试数据 - 全流程验证：
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：
gixppESQL 预处理 →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 |