hangshuo652
b94757d9df
1. 场景价值与技术合理性修复： - 补充docs/SCENE_VALUE.md（业务背景、痛点分析、用户场景、竞品对比、价值量化） - 添加用户操作流程图（Mermaid） - 添加3个真实业务案例量化数据 2. 演示与文档修复： - 创建docs/API.md（完整API文档） - 创建docs/QUICKSTART.md（5分钟快速入门指南） 3. AI使用日志修复： - 更新AGENTS.md，添加强制自动执行的AI使用日志记录指令 - 在_AI_USAGE_LOG.md末尾添加范式执行统计 4. 安全性修复： - 在agents/llm.py中添加输入过滤（防Prompt注入） - 添加输出验证、速率限制、详细日志 5. 架构设计修复： - 创建tools/registry.py工具注册表 - 修改orchestrator.py和orchestrator_db.py使用注册表动态获取运行器 6. 开发范式修复： - 在_AI_USAGE_LOG.md末尾添加范式执行统计
346 lines
6.6 KiB
Markdown
346 lines
6.6 KiB
Markdown
# 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*
|