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

> 版本: v3.0 | 日期: 2026-08-23
> 本文档描述COBOL迁移验证平台的场景价值、开发范式、Agent架构、系统架构及工具清单。

---

## 一、场景与价值

### 1.1 业务场景

大型企业在进行COBOL向Java/Spark迁移时，面临以下核心挑战：

- **验证成本高**：人工逐行比对COBOL与Java输出，耗时数周
- **覆盖不全**：手工测试难以覆盖所有分支路径，遗漏边界条件
- **回归风险**：修改后无法快速验证功能一致性

### 1.2 解决方案

本平台通过**AI辅助自动化测试**，实现：

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

### 1.3 价值量化

| 指标 | 传统方式 | 本平台 | 提升 |
|------|----------|--------|------|
| 单程序验证时间 | 2-3天 | 10分钟 | **99%+** |
| 分支覆盖率 | 30-50% | 75%+ | **50%+** |
| 回归测试时间 | 1-2周 | 1小时 | **99%+** |

---

## 二、开发范式流程图

> 详细流程见 `docs/development-paradigm.md`

```mermaid
graph TD
    A[1. 需求分析] --> B[2. AI方案生成]
    B --> C{3. 人工审核}
    C -->|通过| D[4. AI编码实现]
    C -->|需要修改| B
    D --> E[5. 测试验证]
    E --> F{6. 质量评审}
    F -->|达标| G[7. 交付归档]
    F -->|未达标| D
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#f3e5f5
    style E fill:#e8f5e8
    style F fill:#fff3e0
    style G fill:#e8f5e8
```

### 范式步骤与AI日志对应

| 步骤 | 名称 | 负责人 | AI日志范式步骤 |
|:----:|------|:------:|----------------|
| 1 | 需求分析 | 人工 | 需求分析 |
| 2 | AI方案生成 | AI | AI方案生成 |
| 3 | 人工审核 | 人工 | 人工审核 |
| 4 | AI编码实现 | AI | AI编码实现 |
| 5 | 测试验证 | 工具+人工 | 测试验证 |
| 6 | 质量评审 | 人工 | 质量评审 |
| 7 | 交付归档 | 人工 | 交付归档 |

---

## 三、Agent架构图（感知-规划-行动-记忆）

```
┌─────────────────────────────────────────────────────────────────┐
│                        Agent 架构                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                     感知层 (Perception)                   │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │ COBOL解析    │  │ 设计书解析   │  │ COPY句解析   │  │   │
│  │  │ read.py      │  │ LLM读取     │  │ copybook     │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                     规划层 (Planning)                     │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │ 分支树构建   │  │ 路径枚举     │  │ MC/DC分析    │  │   │
│  │  │ core.py      │  │ design.py    │  │ cond.py      │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                     行动层 (Action)                       │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │ 测试数据生成 │  │ COBOL编译运行│  │ 输出比对     │  │   │
│  │  │ output.py    │  │ runners/     │  │ comparator/  │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                     记忆层 (Memory)                       │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │ 覆盖率记录   │  │ 测试报告     │  │ AI使用日志   │  │   │
│  │  │ coverage.py  │  │ report/      │  │ _AI_USAGE_LOG│  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Agent能力说明

| 层级 | 能力 | 实现模块 |
|------|------|----------|
| 感知 | COBOL源码解析、设计书理解 | `read.py`, LLM |
| 规划 | 分支分析、路径规划、测试策略 | `core.py`, `cond.py`, `design.py` |
| 行动 | 数据生成、编译运行、结果比对 | `output.py`, `runners/`, `comparator/` |
| 记忆 | 覆盖率追踪、报告生成、日志记录 | `coverage.py`, `report/`, `_AI_USAGE_LOG.md` |

---

## 四、系统架构

### 4.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/     │    │
│  └──────────────┘     └──────────────┘     └──────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 4.2 分层架构

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

### 4.3 数据流

#### 非DB管道

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

#### DB管道

```
COBOL源码 → gixsql_runner.py → orchestrator_db.py → cobol_testgen → to_sql.py → flatfile.py → SQLite → comparator/ → report/
```

---

## 五、工具/API清单

### 5.1 核心工具

| 工具 | 用途 | 版本 |
|------|------|------|
| Python | 主要开发语言 | 3.12+ |
| Lark | COBOL语法解析 | 1.1.0+ |
| GnuCOBOL | COBOL编译器 | 3.2.0 |
| gixsql | SQL预处理 | 已vendored |
| pytest | 测试框架 | 最新版 |

### 5.2 AI模型

| 模型 | 用途 | API |
|------|------|-----|
| DeepSeek | 程序分类、测试策略生成 | DeepSeek API |

### 5.3 开发工具

| 工具 | 用途 |
|------|------|
| Git | 版本控制 |
| VS Code | 代码编辑 |
| OpenCode | AI辅助开发 |

### 5.4 外部服务

| 服务 | 用途 | 状态 |
|------|------|------|
| DeepSeek API | LLM调用 | 可选 |
| Gitea | 代码托管 | 组委会提供 |

---

## 六、目录结构

```
cobol-java-v3/
├── cobol_testgen/           # 核心引擎 (~8000行)
│   ├── __init__.py          # 公开 API 入口
│   ├── models.py            # 共享数据模型 (零依赖)
│   ├── read.py              # INPUT: 预处理 + DATA DIVISION 解析
│   ├── core.py              # CORE: 分支树构建
│   ├── cond.py              # CONDITION: 条件解析 + MC/DC
│   ├── design.py            # DESIGN: 路径枚举 + 值生成
│   ├── coverage.py          # COVERAGE: 覆盖标记 + HTML 报告
│   ├── output.py            # OUTPUT: JSON 输出
│   └── to_sql.py            # SQL 辅助: WHERE 约束解析
├── runners/                 # 编译运行引擎
│   ├── cobol_runner.py      # GnuCOBOL 编译运行
│   └── gixsql_runner.py     # DB 管道编译运行
├── agents/                  # LLM 代理
│   └── api_client.py        # DeepSeek API 调用
├── comparator/              # 字段比对
├── hina/                    # HINA 程序分类
├── config/                  # 配置管理
├── report/                  # 报告生成
├── test-data/               # 测试套件
├── tests/                   # 单元测试 (80+文件)
├── benchmark-programs/      # 43个基准 COBOL 程序
├── docs/                    # 文档
│   ├── detailed-design/     # V3 详细设计 (9个文档)
│   ├── development-paradigm.md
│   └── test-report.md
└── sample/                  # 示例数据
```

---

## 七、测试策略

### 7.1 测试层次

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

### 7.2 测试数据

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

---

## 八、环境要求

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

---

## 九、文档索引

| 文档 | 说明 |
|------|------|
| `SETUP.md` | 环境搭建、运行指南 |
| `docs/v3-理解文档.md` | 系统架构、组件说明 |
| `docs/detailed-design/` | V3 详细设计 (9个文档) |
| `docs/development-paradigm.md` | 开发范式流程图 |
| `docs/test-report.md` | 测试报告 |
| `_AI_USAGE_LOG.md` | AI 使用日志 |