cobol-java-v3/docs/detailed-design/00-overview.md

V3系统总体设计

版本: v1.0 | 日期: 2026-08-22 本文档描述COBOL迁移验证平台V3的总体架构和模块设计。

---

一、系统概述

1.1 系统定位

COBOL迁移验证平台V3是一个AI辅助的自动化测试工具，用于验证COBOL程序向Java/Spark迁移的正确性。

1.2 核心能力

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

1.3 技术栈

组件	技术
语言	Python 3.12+
解析器	Lark (Earley parser)
COBOL编译	GnuCOBOL 3.2.0
DB管道	gixsql + SQLite
AI模型	DeepSeek
测试框架	pytest

---

二、系统架构

2.1 架构图

┌─────────────────────────────────────────────────────────────────┐
│                        V3系统架构                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│  │  CLI入口     │     │  Web界面     │     │  API接口     │    │
│  │  main.py     │     │  web/        │     │  __init__    │    │
│  └──────┬───────┘     └──────┬───────┘     └──────┬───────┘    │
│         │                    │                    │            │
│         └────────────────────┼────────────────────┘            │
│                              │                                 │
│                              ▼                                 │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                   编排层 (Orchestrator)                   │  │
│  │  orchestrator.py (非DB)    orchestrator_db.py (DB)      │  │
│  └─────────────────────────────────────────────────────────┘  │
│                              │                                 │
│         ┌────────────────────┼────────────────────┐            │
│         │                    │                    │            │
│         ▼                    ▼                    ▼            │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│  │  核心引擎    │     │  运行引擎    │     │  AI代理      │    │
│  │ cobol_testgen│     │  runners/    │     │  agents/     │    │
│  └──────────────┘     └──────────────┘     └──────────────┘    │
│         │                    │                    │            │
│         │                    │                    │            │
│         ▼                    ▼                    ▼            │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐    │
│  │  比对模块    │     │  报告模块    │     │  配置模块    │    │
│  │ comparator/  │     │  report/     │     │  config/     │    │
│  └──────────────┘     └──────────────┘     └──────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

2.2 分层架构

层级	模块	职责
L1 数据层	data/	共享数据模型
L2 核心层	cobol_testgen/, config/	COBOL解析、配置管理
L3 业务层	hina/, agents/, comparator/	分类、AI代理、比对
L4 编排层	orchestrator*, runners/	流程编排、执行
L5 接口层	main.py, web/, __init__.py	用户接口

---

三、模块清单

3.1 核心模块

模块	文件数	行数	职责
cobol_testgen/	22	~8000	COBOL解析、测试数据生成
orchestrator_db.py	1	1334	DB管道6步编排
runners/	8	~600	编译运行引擎
hina/	11	~2000	HINA程序分类
agents/	6	~800	LLM代理
comparator/	6	~400	字段比对
config/	5	~300	配置管理
report/	1	~200	报告生成

3.2 模块依赖关系

models.py (零依赖)
    │
    ├── read.py (lark)
    ├── cond.py (stdlib)
    ├── core.py (cond)
    ├── design.py (models, cond, core)
    ├── coverage.py (models, cond)
    ├── output.py (file_io)
    ├── to_sql.py (stdlib)
    ├── runner.py (file_io)
    ├── flatfile.py (read, file_io)
    │
    └── __init__.py (所有上层模块)

---

四、数据流

4.1 非DB管道数据流

COBOL源码
    │
    ▼
read.py: preprocess() + parse_data_division()
    │
    ▼
core.py: build_branch_tree()
    │
    ▼
design.py: enum_paths() + generate_records()
    │
    ▼
output.py: output_json() + output_input_files()
    │
    ▼
runners/cobol_runner.py: compile() + run()
    │
    ▼
comparator/: compare_field()
    │
    ▼
report/generator.py: generate_report()

4.2 DB管道数据流

COBOL源码 (含EXEC SQL)
    │
    ▼
gixsql_runner.py: preprocess() + compile()
    │
    ▼
orchestrator_db.py: step2_generate_inputs()
    │
    ├── cobol_testgen: extract_structure + generate_data
    ├── to_sql.py: build_db_input()
    └── flatfile.py: write_all_files()
    │
    ▼
orchestrator_db.py: step3_run_cobol()
    │
    ▼
orchestrator_db.py: step4_extract_intermediate()
    │
    ▼
orchestrator_db.py: step5_run_java() (可选)
    │
    ▼
orchestrator_db.py: step6_verify()

---

五、接口设计

5.1 公开API

# cobol_testgen/__init__.py

def extract_structure(
    cobol_source: str,
    copybook_dirs: list[str] = None
) -> dict:
    """解析COBOL源码，返回结构信息"""
    pass

def generate_data(
    cobol_source: str,
    structure: dict,
    copybook_dirs: list[str] = None
) -> list[dict]:
    """生成分支覆盖测试数据"""
    pass

def main():
    """CLI入口"""
    pass

5.2 配置接口

# config/__init__.py

@dataclass
class Config:
    """全局配置"""
    project_name: str
    copybook_paths: list[str]
    dialect: str
    llm_model: str
    gcov_enabled: bool
    # ... 更多字段

---

六、错误处理

6.1 错误分类

类别	示例	处理策略
解析错误	COBOL语法不合法	抛出异常，返回错误信息
编译错误	cobc编译失败	记录日志，跳过该程序
运行错误	程序执行异常	捕获异常，标记失败
超时错误	执行超时	强制终止，记录超时

6.2 容错机制

• 解析器超时：pipeline_bridge 3秒超时回退
• LLM失败：回退到规则引擎
• gcov失败：跳过覆盖率收集
• DB连接失败：重试或跳过

---

七、性能设计

7.1 性能指标

指标	目标
单程序解析	< 5秒
测试数据生成	< 30秒
编译运行	< 60秒
覆盖率报告	< 10秒

7.2 优化策略

• 路径枚举：O(N)线性算法替代O(2^N)
• 并行执行：多场景gcov并行收集
• 缓存机制：LLM结果缓存
• 增量补充：质量门循环最多4次

---

八、安全设计

8.1 输入验证

• COBOL源码：长度限制、编码检查
• 配置文件：YAML schema验证
• 文件路径：路径遍历防护

8.2 资源限制

• LLM调用：最大成本限制
• 执行时间：超时强制终止
• 内存使用：大文件分块处理

---

九、测试策略

9.1 测试层次

层次	覆盖率目标	工具
单元测试	≥ 90%	pytest
集成测试	≥ 80%	pytest
端到端测试	100%通过	自定义脚本

9.2 测试数据

• 43个COBOL基准程序
• 33+2种程序类型
• 58个电信测试程序

---

十、部署设计

10.1 运行环境

组件	要求
OS	Windows 10/11
Python	3.12+
GnuCOBOL	3.2.0
磁盘	≥ 500MB

10.2 安装步骤

# 1. 安装Python依赖
pip install lark pathlib pyyaml

# 2. 安装GnuCOBOL
# 下载GC32-BDB-SP1，添加到PATH

# 3. 验证安装
python -c "from cobol_testgen import extract_structure; print('OK')"