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

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

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

## 快速开始

```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
```

## 架构

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

两条管道自动路由：
- **非 DB**：`cobc` 编译 → flat file 二进制比对
- **DB**：`gixpp` ESQL 预处理 → `cobc -l gixsql` 编译 → SQLite 表比对

## 文档索引

| 文档 | 说明 |
|------|------|
| `SETUP.md` | 环境搭建、运行指南、检查清单（含 DB 管道） |
| `docs/v3-理解文档.md` | 系统架构、组件说明、数据流（中文，457 行） |
| `docs/changelog-v1-to-v3.md` | V1→V3 演进记录 |
| `docs/module-interfaces.md` | 模块接口定义 |
| `docs/detailed-design/00-overview.md` | V3系统总体设计 |
| `docs/detailed-design/01-cobol-testgen-core.md` | 核心引擎详细设计 |
| `docs/detailed-design/02-orchestrator-db.md` | DB管道编排详细设计 |
| `docs/detailed-design/03-runners.md` | 编译运行引擎详细设计 |
| `docs/detailed-design/04-hina-classification.md` | HINA分类系统详细设计 |
| `docs/detailed-design/05-agents-llm.md` | LLM代理详细设计 |
| `docs/detailed-design/06-comparator.md` | 比对模块详细设计 |
| `docs/detailed-design/07-config-system.md` | 配置系统详细设计 |
| `docs/detailed-design/08-data-flow.md` | 数据流设计 |
| `_AI_USAGE_LOG.md` | AI使用日志 |
| `docs/development-paradigm.md` | 开发范式流程图 |
| `DESIGN.md` | Web UI 设计规范 |
| `CONTRIBUTING.md` | 贡献指南 |

## 核心命令

```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 编译运行
```

## 项目性质

本项目是 **AI 辅助的 COBOL 程序迁移验证工具**，用于验证 COBOL 程序向 Java/Spark 迁移的正确性。

### 核心功能

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

### 技术特点

- **非阻塞路径枚举**: O(N) 算法替代 O(2^N) 爆炸
- **MC/DC 条件覆盖**: 支持 AND/OR/NOT 复合条件
- **DB 种子键一致性**: WHERE 宿主变量 MOVE 链解析
- **中文 HTML 报告**: 全中文覆盖率报告

---

## 成果摘要

### 开发成果

| 指标 | 数量 |
|------|------|
| 核心代码 | 22 个模块，~8000 行 |
| 测试文件 | 80+ 个测试用例 |
| 基准程序 | 43 个 COBOL 程序 |
| 修复数量 | 19 个关键 bug 修复 |
| 设计文档 | 9 个 V3 详细设计文档 |

### 覆盖率

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

### 技术亮点

1. **Lark 语法解析**: 使用 Earley parser 解析 COBOL 语法
2. **MC/DC 条件覆盖**: 支持复合条件的最小条件覆盖
3. **双管道架构**: 非 DB 和 DB 管道并行运行
4. **AI 辅助**: DeepSeek LLM 驱动的程序分类和测试策略

---

## 团队分工

### AI 辅助 (DeepSeek)

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

### 人工审查

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

---

## 技术难度

### 难点分析

| 难点 | 说明 | 解决方案 |
|------|------|----------|
| COBOL 语法复杂性 | 支持 33+ 种语句类型 | Lark Earley parser + 状态机 |
| 路径爆炸 | 复合条件导致路径指数增长 | O(N) MC/DC 算法 |
| DB 管道一致性 | 种子键与运行时查询键不一致 | MOVE 链解析 + 列名归一化 |
| 覆盖率标记 | 复合条件分支标记错误 | 条件树 + evaluate_tree |

### 已知限制

| 限制 | 影响 | 状态 |
|------|------|------|
| 条件覆盖率 75% | `_FUNC_MOD` 合成函数不可匹配 | 待优化 |
| 无 Java 比对管道 | 仅验证 COBOL 输出 | 规划中 |
| DB 管道需 gixsql | 依赖外部工具 | 已 vendored |

---

## 依赖

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