# V3系统总体设计

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

---

## 一、系统概述

### 1.1 系统定位

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

### 1.2 核心能力

| 能力 | 说明 |
|------|------|
| COBOL源码解析 | 自动解析DATA DIVISION和PROCEDURE DIVISION（支持新旧双解析器） |
| 测试数据生成 | 基于分支覆盖的测试数据自动生成（规则引擎 + LLM双模式） |
| 双管道验证 | 支持非DB（flat file）和DB（SQLite）两种验证模式 |
| 全流程入口 | `run.py` 一键执行白盒+黑盒全流程 |
| 黑盒LLM生成 | `black-box-data-create` 基于设计书的LLM测试数据生成 |
| 覆盖率分析 | 静态分支覆盖 + 动态gcov覆盖，生成HTML报告 |
| AI辅助 | LLM驱动的程序分类、测试策略生成、诊断建议 |

### 1.3 技术栈

| 组件 | 技术 |
|------|------|
| 语言 | Python 3.12+ |
| 解析器 | Lark (Earley parser) + 新fast parser (line-based state machine) |
| COBOL编译 | GnuCOBOL 3.2.0 |
| DB管道 | gixsql + SQLite |
| AI模型 | DeepSeek (deepseek-v4-flash) |
| 测试框架 | pytest |

---

## 二、系统架构

### 2.1 架构图

```
┌─────────────────────────────────────────────────────────────────────┐
│                         V3系统架构                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐     ┌──────────────┐                              │
│  │  run.py      │     │  main.py     │                              │
│  │  全流程入口  │     │  CLI入口     │                              │
│  └──────┬───────┘     └──────┬───────┘                              │
│         │                    │                                      │
│         ▼                    ▼                                      │
│  ┌──────────────┐     ┌──────────────────────────────────────────┐  │
│  │  Step1:      │     │          编排层 (Orchestrator)            │  │
│  │  cobol_testgen│    │  orchestrator.py (非DB)                   │  │
│  │  (白盒)      │     │  orchestrator_db.py (DB, 6步)            │  │
│  │  Step2:      │     └──────────────────────────────────────────┘  │
│  │  black-box   │              │                                    │
│  │  (黑盒LLM)   │              │                                    │
│  └──────┬───────┘              │                                    │
│         │         ┌────────────┼────────────┐                       │
│         │         │            │            │                       │
│         ▼         ▼            ▼            ▼                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │  核心引擎    │  │  运行引擎    │  │  AI代理      │              │
│  │ cobol_testgen│  │  runners/    │  │  agents/     │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│         │                  │                 │                      │
│         ▼                  ▼                 ▼                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │  比对模块    │  │  报告模块    │  │  配置模块    │              │
│  │ comparator/  │  │  report/     │  │  config/     │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │              black-box-data-create/ (黑盒LLM模块)            │  │
│  │  InputParser → RuleLoader → PromptBuilder → APIClient → Writer│  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 2.2 分层架构

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

---

## 三、模块清单

### 3.1 核心模块

| 模块 | 文件数 | 行数 | 职责 |
|------|--------|------|------|
| cobol_testgen/ | 22 | ~10000 | COBOL解析、测试数据生成 |
| black-box-data-create/ | 12 | ~1500 | 黑盒LLM测试数据生成 |
| orchestrator_db.py | 1 | ~1000 | DB管道6步编排 |
| orchestrator.py | 1 | ~500 | 非DB管道编排 |
| runners/ | 7 | ~600 | 编译运行引擎 |
| hina/ | 12 | ~2600 | HINA程序分类 |
| agents/ | 7 | ~1100 | LLM代理 |
| comparator/ | 6 | ~400 | 字段比对 |
| config/ | 4 | ~400 | 配置管理 |
| report/ | 1 | ~200 | 报告生成 |

### 3.2 模块依赖关系

```
models.py (零依赖)
    │
    ├── read.py (lark)
    ├── cond.py (stdlib)
    ├── core.py (cond)
    ├── procedure_parser.py (re) [新]
    ├── pipeline_bridge.py (procedure_parser, core) [新]
    ├── design.py (models, cond, core)
    ├── design_mcdc.py (models, cond) [新]
    ├── coverage.py (models, cond)
    ├── output.py (file_io)
    ├── to_sql.py (stdlib)
    ├── flatfile.py (read, file_io) [新]
    ├── data_merger.py (generate_data, design_data) [新]
    ├── gcov.py [新]
    │
    └── __init__.py (所有上层模块)
```

---

## 四、数据流

### 4.1 全流程入口 (run.py)

```
run.py
  │
  ├── Step1: python -m cobol_testgen --gcov <source> <output>
  │     │
  │     ├── read.py: preprocess() + parse_data_division()
  │     ├── core.py / procedure_parser.py: build_branch_tree()
  │     ├── design.py / design_mcdc.py: enum_paths() + generate_records()
  │     ├── output.py: output_json() + output_input_files()
  │     └── coverage.py: HTML覆盖率报告
  │
  └── Step2: black-box-data-create/main.py
        │
        ├── InputParser: 解析设计书 + COPYBOOK + DB定义
        ├── RuleLoader: PGM模式匹配 → 规则文件
        ├── PromptBuilder: 组装LLM提示词
        ├── APIClient: DeepSeek API调用
        └── OutputWriter: JSON/SQL输出
```

### 4.2 非DB管道数据流

```
COBOL源码 → read.py → core.py → design.py → output.py → cobol_runner.py → comparator/ → report/
```

### 4.3 DB管道数据流

```
COBOL源码 → gixsql_runner.py → orchestrator_db.py (6步)
  Step1: gixpp + cobc编译
  Step2: generate_data → flatfile.write_all_files + DB初始化 + JSON输出
  Step3: gixsql_runner.run (COBOL + SQLite)
  Step4: SQLite → JSON中间数据
  Step5: Java执行 (可选)
  Step6: 结果比对
```

---

## 五、接口设计

### 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 incremental_supplement(
    branch_tree: list,
    gaps: list,
    data_fields: list
) -> list[dict]:
    """增量补充未覆盖分支的测试数据"""
    pass

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

### 5.2 黑盒LLM API

```python
# black-box-data-create/agent/__init__.py

def generate(
    design_md: str,        # 詳細設計書パス
    source_cbl: str,       # COBOLソースパス
    file_db_md: str,       # COPY句定義書パス
    cpy_dir: str,          # COPYBOOKディレクトリ
    db_md: str,            # DB定義書パス
    output_dir: str,       # 出力ディレクトリ
    api_key: str,          # DeepSeek API Key
    api_model: str,        # モデル名 (default: deepseek-v4-flash)
    rules_dir: str,        # ルールディレクトリ
    max_tokens: int,       # トークン上限 (default: 32768)
) -> dict:
    """黑盒LLM测试数据生成主入口"""
    pass
```

### 5.3 配置接口

```python
# config/__init__.py

@dataclass
class Config:
    """全局配置（从TOML加载）"""
    project_name: str
    copybook_paths: list[str]
    dialect: str
    llm_model: str
    gcov_enabled: bool
    # ... 更多字段
```

---

## 六、错误处理

### 6.1 错误分类

| 类别 | 示例 | 处理策略 |
|------|------|----------|
| 解析错误 | COBOL语法不合法 | 抛出异常，返回错误信息 |
| 编译错误 | cobc编译失败 | 记录日志，跳过该程序 |
| 运行错误 | 程序执行异常 | 捕获异常，标记失败 |
| 超时错误 | 执行超时 | 强制终止，记录超时 |
| API错误 | DeepSeek调用失败 | 3次重试后回退到规则引擎 |

### 6.2 容错机制

- **解析器超时**：pipeline_bridge 3秒超时回退（新parser → 旧parser）
- **LLM失败**：black-box-data-create 回退到空结果
- **gcov失败**：跳过覆盖率收集
- **DB连接失败**：重试或跳过
- **API重试**：3次指数退避重试

---

## 七、性能设计

### 7.1 性能指标

| 指标 | 目标 |
|------|------|
| 单程序解析 | < 5秒 |
| 测试数据生成 | < 30秒 |
| 编译运行 | < 60秒 |
| 覆盖率报告 | < 10秒 |
| 全流程 (run.py) | < 120秒 |

### 7.2 优化策略

- **路径枚举**：O(N)线性算法（procedure_parser）替代O(2^N)
- **新解析器**：line-based state machine，10-50ms完成解析
- **并行执行**：多场景gcov并行收集
- **缓存机制**：LLM结果SHA256缓存
- **增量补充**：质量门循环最多4次

---

## 八、安全设计

### 8.1 输入验证

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

### 8.2 资源限制

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

---

## 九、测试策略

### 9.1 测试层次

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

### 9.2 测试数据

- 43个COBOL基准程序
- 33+2种程序类型
- 14个程序YAML schema

---

## 十、部署设计

### 10.1 运行环境

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

### 10.2 安装步骤

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

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

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