hangshuo652
dec597eff0
- 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: 添加项目性质声明（新规）、团队分工、技术难度评估
309 lines
16 KiB
Markdown
309 lines
16 KiB
Markdown
# 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 使用日志 |
|