Files

T

hangshuo652 dec597eff0 docs: 更新设计文档以匹配Black-white-box-Merge分支最新代码

- 00-overview.md: 重写架构图（移除web/入口）、更新模块清单、更新API签名
- 05-agents-llm.md: 修复章节编号（Section 7/8子节编号错误）
- 08-data-flow.md: 修复Mermaid代码块格式（单反引号→三反引号）
- 09-run-pipeline.md: 新增run.py全流程入口+black-box-data-create详细设计
- DESIGN.md: 重写为竞赛要求格式（场景价值、范式图、Agent架构、工具清单）
- README.md: 添加项目性质声明（新规）、团队分工、技术难度评估

2026-08-23 21:10:33 +08:00

16 KiB

Raw Blame History

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

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 使用日志

16 KiB Raw Blame History Unescape Escape

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

一、场景与价值

1.1 业务场景

1.2 解决方案

1.3 价值量化

二、开发范式流程图

范式步骤与AI日志对应

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

Agent能力说明

四、系统架构

4.1 架构图

4.2 分层架构

4.3 数据流

非DB管道

DB管道

五、工具/API清单

5.1 核心工具

5.2 AI模型

5.3 开发工具

5.4 外部服务

六、目录结构

七、测试策略

7.1 测试层次

7.2 测试数据

八、环境要求

九、文档索引

16 KiB

Raw Blame History

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