# COBOL → Java/Spark 迁移验证平台 API 文档

> 版本: v1.0 | 日期: 2026-08-28

---

## 一、核心模块 API

### 1.1 cobol_testgen 模块

#### 主入口

```python
from cobol_testgen import main

# 运行测试数据生成
main(cobol_files, output_dir, config=None)
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `cobol_files` | `list[str]` | COBOL源码文件路径列表 |
| `output_dir` | `str` | 输出目录路径 |
| `config` | `dict` | 可选配置参数 |

#### FieldTree 类

```python
from cobol_testgen.read import FieldTree

# 解析COBOL源码
tree = FieldTree(copybook_name="example")

# 获取字段列表
fields = tree.flatten()  # 返回 dict[str, Field]
```

#### Field 类

```python
from cobol_testgen.read import Field

# 字段属性
field.name      # 字段名
field.level     # 层级
field.pic       # PIC子句
field.usage     # USAGE类型
field.offset    # 偏移量
field.length    # 长度
field.decimal   # 小数位
field.signed    # 是否有符号
field.occurs    # OCCURS次数
field.redefines # REDEFINES字段
field.conditions # 88级条件
field.children  # 子字段
```

### 1.2 coverage 模块

```python
from cobol_testgen.coverage import CoverageAnalyzer

# 创建覆盖率分析器
analyzer = CoverageAnalyzer()

# 标记覆盖情况
analyzer.mark_coverage(decision_points, path_assignments)

# 生成HTML报告
analyzer.generate_report(output_path)
```

### 1.3 design 模块

```python
from cobol_testgen.design import DesignAnalyzer

# 创建设计分析器
analyzer = DesignAnalyzer()

# 枚举路径
paths = analyzer.enum_paths(field_tree, mode="rule")  # mode: "rule" | "ai"

# 生成测试记录
records = analyzer.generate_records(paths, field_tree)
```

---

## 二、编排器 API

### 2.1 orchestrator 模块（非DB管道）

```python
from orchestrator import Orchestrator

# 创建编排器
orch = Orchestrator(config)

# 运行完整验证流程
result = orch.run(cobol_source, design_doc)

# 返回结果
result.status        # "pass" | "fail"
result.coverage      # 覆盖率百分比
result.test_cases    # 测试用例列表
result.diff_results  # 差异比对结果
```

### 2.2 orchestrator_db 模块（DB管道）

```python
from orchestrator_db import OrchestratorDB

# 创建DB编排器
orch = OrchestratorDB(config)

# 运行DB管道验证
result = orch.run(cobol_source, design_doc)

# 返回结果
result.status        # "pass" | "fail"
result.db_coverage   # DB相关覆盖率
result.sql_results   # SQL执行结果
```

---

## 三、Runner API

### 3.1 CobolRunner

```python
from runners import CobolRunner

# 创建COBOL运行器
runner = CobolRunner()

# 编译并运行COBOL程序
result = runner.compile_and_run(source_file, input_data)

# 返回结果
result.output        # 程序输出
result.return_code   # 返回码
result.coverage_data # 覆盖率数据
```

### 3.2 JavaRunner

```python
from runners import NativeJavaRunner, SparkJavaRunner

# 创建Java运行器
runner = NativeJavaRunner()  # 或 SparkJavaRunner(spark_master)

# 运行Java程序
result = runner.run(class_path, input_data)

# 返回结果
result.output        # 程序输出
result.return_code   # 返回码
```

---

## 四、Comparator API

```python
from comparator import FieldComparator

# 创建字段比对器
comparator = FieldComparator()

# 比对COBOL和Java输出
results = comparator.compare(cobol_output, java_output)

# 返回结果
for result in results:
    result.field_name   # 字段名
    result.cobol_value  # COBOL值
    result.java_value   # Java值
    result.status       # "match" | "mismatch"
    result.diff_type    # 差异类型
```

---

## 五、Agents API

### 5.1 LLMClient

```python
from agents.llm import LLMClient

# 创建LLM客户端
client = LLMClient(model="deepseek-v4-flash", timeout=15)

# 调用LLM
response = client.call(messages, retries=1)

# 参数说明
messages: list[dict]  # 消息列表，格式: [{"role": "system"|"user", "content": "..."}]
retries: int          # 重试次数
```

### 5.2 Agent1Parser

```python
from agents.agent1_parser import Agent1Parser

# 创建解析Agent
parser = Agent1Parser(llm_client)

# 解析COBOL COPYBOOK
field_tree = parser.parse(cobol_text)

# 返回FieldTree对象
```

### 5.3 Agent2Data

```python
from agents.agent2_data import Agent2Data

# 创建数据生成Agent
agent = Agent2Data(llm_client)

# 生成测试数据
test_suite = agent.design(field_tree, target="boundary", spark_mode=False)

# 返回TestSuite对象
```

### 5.4 Agent3Diagnostic

```python
from agents.agent3_diagnostic import Agent3Diagnostic

# 创建诊断Agent
agent = Agent3Diagnostic(llm_client)

# 分析差异
diagnosis = agent.analyze(field_result)

# 返回诊断结果字符串
```

---

## 六、数据模型

### 6.1 TestCase

```python
from data.test_case import TestCase

# 测试用例
tc = TestCase(
    id="TC-001",
    fields={"FIELD1": value1, "FIELD2": value2},
    coverage_targets=["DP-001", "DP-002"]
)
```

### 6.2 TestSuite

```python
from data.test_case import TestSuite

# 测试套件
suite = TestSuite(test_cases=[tc1, tc2, tc3])
suite.spark_config  # 可选Spark配置
```

### 6.3 FieldResult

```python
from data.diff_result import FieldResult

# 字段比对结果
result = FieldResult(
    field_name="AMOUNT",
    cobol_value="1000",
    java_value="1000",
    status="match"
)
```

---

## 七、配置参数

### 7.1 全局配置

```python
CONFIG = {
    "proc_parser": "rule",      # "rule" | "ai"
    "llm_generator": True,      # 是否使用LLM生成测试数据
    "coverage_target": 0.75,    # 目标覆盖率
    "max_paths": 100,           # 最大路径数
}
```

### 7.2 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `LLM_API_KEY` | LLM API密钥 | - |
| `LLM_MODEL` | LLM模型名称 | `deepseek-v4-flash` |
| `LLM_API_BASE` | LLM API地址 | `https://api.openai.com/v1` |
| `DEEPSEEK_API_KEY` | DeepSeek API密钥 | - |

---

## 八、错误处理

### 8.1 常见异常

| 异常类型 | 说明 | 处理方式 |
|----------|------|----------|
| `FileNotFoundError` | 文件不存在 | 检查文件路径 |
| `json.JSONDecodeError` | JSON解析失败 | 检查输入格式 |
| `LLMError` | LLM调用失败 | 重试或检查API密钥 |
| `CompilationError` | COBOL编译失败 | 检查源码语法 |

### 8.2 错误恢复

```python
try:
    result = orch.run(cobol_source, design_doc)
except LLMError:
    # 降级到规则引擎
    config["proc_parser"] = "rule"
    result = orch.run(cobol_source, design_doc)
except CompilationError as e:
    # 记录编译错误
    logger.error(f"Compilation failed: {e}")
    result = {"status": "error", "message": str(e)}
```

---

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