325 lines
9.8 KiB
Markdown
325 lines
9.8 KiB
Markdown
# 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
|
||
|
||
```python
|
||
# 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 配置接口
|
||
|
||
```python
|
||
# 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 安装步骤
|
||
|
||
```bash
|
||
# 1. 安装Python依赖
|
||
pip install lark pathlib pyyaml
|
||
|
||
# 2. 安装GnuCOBOL
|
||
# 下载GC32-BDB-SP1，添加到PATH
|
||
|
||
# 3. 验证安装
|
||
python -c "from cobol_testgen import extract_structure; print('OK')"
|
||
```
|