146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# COBOL → Java/Spark 迁移验证平台 V3
|
||
|
||
AI 辅助的自动化测试工具，用于验证 COBOL 程序向 Java/Spark 迁移的正确性。支持非 DB（flat file）和 DB（EXEC SQL → gixsql + SQLite）两条平行管道。
|
||
|
||
## 核心命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install lark pathlib pyyaml
|
||
|
||
# 运行非 DB 回归测试
|
||
python test-data/s15_coverage_verification.py
|
||
|
||
# 运行 DB 端到端测试
|
||
python test-data/s30_db_e2e.py
|
||
|
||
# 单程序运行（自动路由）
|
||
python -m cobol_testgen ../cobol-tna-system/src/KIN01INP.cbl
|
||
|
||
# 带 gcov 覆盖率的单程序运行
|
||
python -m cobol_testgen --gcov <cobol_src> runtime/
|
||
|
||
# 诊断脚本
|
||
python diagnose_db2.py # DB 全流程
|
||
python diagnose_kind8dbrun.py # DB 编译运行
|
||
```
|
||
|
||
## 架构
|
||
|
||
```
|
||
CLI (main.py)
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 编排层 (Orchestrator) │
|
||
│ orchestrator.py (非DB) orchestrator_db.py (DB) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
├──┬──────────┬──────────┬──────────┬──────────┐
|
||
▼ ▼ ▼ ▼ ▼ ▼
|
||
cobol_testgen runners comparator agents hina/
|
||
(数据生成) (编译运行) (比对验证) (LLM) (分类)
|
||
│
|
||
├── config/
|
||
│
|
||
└── report/
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
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
|
||
└── sample/ # 示例数据
|
||
```
|
||
|
||
## 测试命令
|
||
|
||
```bash
|
||
# 运行所有单元测试
|
||
python -m pytest tests/ -v
|
||
|
||
# 运行核心引擎测试
|
||
python -m pytest tests/cobol_testgen/ -v
|
||
|
||
# 运行覆盖率验证
|
||
python test-data/s15_coverage_verification.py
|
||
|
||
# 运行 DB 端到端测试
|
||
python test-data/s30_db_e2e.py
|
||
```
|
||
|
||
## 关键约束与注意事项
|
||
|
||
### 解析器
|
||
- **Lark 语法** (`grammar.lark`): Earley parser, dynamic lexer
|
||
- **命名终端**: 必须使用 `USAGE_VAL` 而非内联字符串
|
||
- **88 级限制**: 目标程序无 88 级 VALUE 子句
|
||
- **REDEFINES/FILLER**: 捕获但跳过 (debug 日志警告)
|
||
|
||
### 路径枚举
|
||
- **MC/DC 条件**: 支持 AND/OR/NOT 复合条件
|
||
- **路径上限**: 规则引擎 100 路径, LLM 模式 5000 路径
|
||
- **O(N) 算法**: 避免 O(2^N) 爆炸
|
||
|
||
### DB 管道
|
||
- **gixsql**: 预处理 EXEC SQL → SQLite
|
||
- **种子键一致性**: WHERE 宿主变量 MOVE 链解析到输入记录根字段
|
||
- **列名归一化**: `-`/`_` 容忍 (`EMP-ID` vs `EMP_ID`)
|
||
|
||
### 覆盖率
|
||
- **分支覆盖率目标**: 75%
|
||
- **条件覆盖率**: 75% (`_FUNC_MOD` 合成函数不可匹配)
|
||
- **HTML 报告**: 全中文 (标题、图例、徽章)
|
||
|
||
## 环境要求
|
||
|
||
- Python 3.12+ (`lark`, `pyyaml`)
|
||
- GnuCOBOL 3.2.0 (GC32-BDB-SP1)
|
||
- gixsql (已 vendored 在 `gixsql/` 目录)
|
||
- DeepSeek API (可选, 用于 LLM 路径生成)
|
||
|
||
## AI 使用规范
|
||
|
||
本项目使用 DeepSeek 作为 AI 辅助工具。使用时需注意:
|
||
|
||
1. **API Key**: 设置 `DEEPSEEK_API_KEY` 环境变量
|
||
2. **日志记录**: 所有 AI 生成/修改的文件需记录在 `_AI_USAGE_LOG.md`
|
||
3. **审查流程**: 代码变更需经过 code-review skill 审查
|
||
4. **硬编码禁止**: 禁止硬编码绝对路径、API Key、密码
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| `SETUP.md` | 环境搭建、运行指南 |
|
||
| `docs/v3-理解文档.md` | 系统架构、组件说明 |
|
||
| `docs/detailed-design/` | V3 详细设计 (9个文档) |
|
||
| `docs/development-paradigm.md` | 开发范式流程图 |
|
||
| `docs/test-report.md` | 测试报告 |
|
||
| `_AI_USAGE_LOG.md` | AI 使用日志 |
|