# 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: cobol_testgen（白盒）
  │     ├── 静态分析 + 测试数据生成
  │     ├── 编译运行 COBOL 程序
  │     └── gcov 覆盖率收集
  │
  └── 步骤2: black-box-data-create（黑盒）
        ├── 解析設計書 + COPY + DB定義
        ├── LLM 生成 JSON/SQL
        └── 输出到 output/{程序ID}/g{N}/
```

---

## 成果摘要

### 开发成果

| 指标 | 数量 |
|------|------|
| 核心代码 | 22 个模块，~8000 行 |
| 黑盒模块 | 8 个模块，~5000 行 |
| 测试文件 | 80+ 个测试用例 |
| 基准程序 | 43 个 COBOL 程序 |
| 对应PGMパターン | 16 种，24 个程序 |
| 修复数量 | 19 个关键 bug 修复 |
| 设计文档 | 9 个 V3 详细设计文档 |

### 覆盖率

| 类型 | 覆盖率 |
|------|--------|
| 分支覆盖率 | 75% |
| 条件覆盖率 | 75% |
| 测试通过率 | 95%+ |

### 技术亮点

1. **Lark 语法解析**: 使用 Earley parser 解析 COBOL 语法
2. **MC/DC 条件覆盖**: 支持复合条件的最小条件覆盖
3. **双管道架构**: 白盒（静态分析）+ 黑盒（LLM生成）并行运行
4. **多KEY测试**: 自动验证复合KEY的比较正确性
5. **PGMパターン匹配**: 16种程序模式自动识别和规则匹配
6. **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 | 已实现重试机制 |
| 黑盒仅支持日语設計書 | 中文設計書需适配 | 待优化 |

---

## 快速开始

```bash
# 安装依赖
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）

白盒+黑盒双管道一键执行：

```bash
python run.py \
    --design "D:\cobol-tna-system\詳細設計書\詳細設計書_ZAN04MAT.md" \
    --source "D:\cobol-tna-system\src\ZAN04MAT.cbl" \
    --file-db-md "D:\cobol-tna-system\詳細設計書\COPY句定義書.md" \
    --cpy "D:\cobol-tna-system\cpy" \
    --db-md "D:\cobol-tna-system\詳細設計書\DB定義書.md" \
    --output "D:\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） |

### 输出目录结构

```
output/
└── ZAN04MAT/
    ├── main/                    # 白盒输出
    │   ├── json/                # テストデータJSON
    │   ├── input/               # 入力ファイル
    │   └── gcov/                # カバレッジデータ
    ├── g1/                      # 黑盒グループ1
    │   └── ZAN04MAT_g1.json
    ├── g2/                      # 黑盒グループ2
    │   └── ZAN04MAT_g2.json
    └── g3/                      # 黑盒グループ3
        └── ZAN04MAT_g3.json
```

## 架构

```
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/detailed-design/` | V3 详细设计文档（10个） |
| `docs/development-paradigm.md` | 开发范式流程图 |
| `docs/test-report.md` | 测试报告 |
| `_AI_USAGE_LOG.md` | AI 使用日志 |
| `AGENTS.md` | 项目指令文档 |
| `sample/` | 示例数据 |

## 核心命令

```bash
# 非 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 "D:\xxxx\詳細設計書_xxxx.md" --source "D:\xxxx\xxxx.cbl" --file-db-md "D:\xxxx\COPY句定義書.md" --cpy "D:\cobol-tna-system\cpy" --db-md "D:\xxxx\DB定義書.md" --output "D:\xxxx\output"

```

## 依赖

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