# COBOL → Java/Spark 迁移验证平台 — 快速入门

> 5分钟快速上手指南

---

## 一、环境准备

### 1.1 系统要求

- Python 3.12+
- GnuCOBOL 3.2.0（可选，用于COBOL编译）
- Java JDK 8+（可选，用于Java编译）

### 1.2 安装依赖

```bash
# 安装Python依赖
pip install lark pathlib pyyaml httpx

# 或使用requirements.txt
pip install -r requirements.txt
```

---

## 二、快速开始

### 2.1 验证单个COBOL程序

```bash
# 基本用法
python -m cobol_testgen <cobol_source> [output_dir]

# 示例
python -m cobol_testgen benchmark-programs/KIN01INP.cbl output/
```

**执行流程：**
1. 解析COBOL源码
2. 分析分支路径
3. 生成测试数据
4. 编译运行COBOL程序
5. 编译运行Java程序
6. 字段级输出比对
7. 生成验证报告

### 2.2 带覆盖率的验证

```bash
# 启用gcov覆盖率
python -m cobol_testgen --gcov benchmark-programs/KIN01INP.cbl output/
```

### 2.3 批量验证

```bash
# 验证多个程序
python -m cobol_testgen benchmark-programs/*.cbl output/
```

---

## 三、运行测试套件

### 3.1 运行所有测试

```bash
# 运行pytest测试
python -m pytest tests/ -v

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

### 3.2 运行验证脚本

```bash
# 运行覆盖率验证
python test-data/s15_coverage_verification.py

# 运行DB端到端测试（需要数据库）
python test-data/s30_db_e2e.py
```

---

## 四、配置说明

### 4.1 环境变量配置

```bash
# 设置LLM API密钥（可选）
export LLM_API_KEY="your-api-key"

# 设置LLM模型（默认deepseek-v4-flash）
export LLM_MODEL="deepseek-v4-flash"

# 设置DeepSeek API密钥（可选）
export DEEPSEEK_API_KEY="your-deepseek-key"
```

### 4.2 配置文件

项目配置位于 `config/` 目录：

```
config/
├── __init__.py          # 配置初始化
├── program_schema.py    # 程序Schema定义
└── teams.json           # 团队配置（如有）
```

---

## 五、输出说明

### 5.1 输出目录结构

```
output/
├── test_input.json      # 生成的测试输入数据
├── test_output.json     # 期望的测试输出
├── working_storage.json # 工作存储区数据
├── diff_result.json     # 差异比对结果
└── coverage/            # 覆盖率报告
    ├── index.html       # 覆盖率概览
    └── detail.html      # 详细覆盖率
```

### 5.2 验证报告

验证完成后会生成HTML格式的验证报告，包含：
- 测试用例执行结果
- 字段级比对结果
- 覆盖率统计
- 差异分析

---

## 六、常见问题

### Q1: 编译COBOL失败

**问题：** `cobc: command not found`

**解决：** 安装GnuCOBOL
```bash
# Ubuntu/Debian
sudo apt-get install gnucobol

# macOS
brew install gnucobol
```

### Q2: LLM调用失败

**问题：** `LLMError: API key not set`

**解决：** 设置API密钥
```bash
export LLM_API_KEY="your-api-key"
```

### Q3: 测试数据生成失败

**问题：** `FieldTree parse error`

**解决：** 检查COBOL源码格式，确保是有效的COBOL代码

### Q4: 覆盖率报告为空

**问题：** 覆盖率报告显示0%

**解决：** 确保启用了gcov选项（`--gcov`）

---

## 七、进阶使用

### 7.1 使用规则引擎（不依赖LLM）

```python
from cobol_testgen import main

# 使用规则引擎生成测试数据
config = {"proc_parser": "rule", "llm_generator": False}
main(["benchmark-programs/KIN01INP.cbl"], "output/", config)
```

### 7.2 使用LLM生成测试数据

```python
from cobol_testgen import main

# 使用LLM生成测试数据
config = {"proc_parser": "ai", "llm_generator": True}
main(["benchmark-programs/KIN01INP.cbl"], "output/", config)
```

### 7.3 自定义配置

```python
from cobol_testgen import main

# 自定义配置
config = {
    "proc_parser": "rule",
    "llm_generator": False,
    "coverage_target": 0.85,
    "max_paths": 200,
}
main(["benchmark-programs/KIN01INP.cbl"], "output/", config)
```

---

## 八、下一步

- 阅读 [API文档](API.md) 了解详细接口
- 阅读 [设计文档](../DESIGN.md) 了解系统架构
- 阅读 [场景与价值](SCENE_VALUE.md) 了解业务背景

---

*本文档最后更新：2026-08-28*